GitLab 설정 (gitlab.rb)¶

GitLab을 Reverse Proxy 구조에 맞게 설정하는 절차를 정의함.

1. 개요¶

다음 구조를 기준으로 설정함.

구조: Client → Nginx (443, SSL 종단) → GitLab (127.0.0.1:8081 또는 192.168.0.100:8081)
외부 URL: https://gitlab.example.com
외부 노출: 별도 Reverse Proxy(Nginx) 또는 Gateway(Nginx) 사용
운영 원칙: GitLab은 외부 인터넷에 직접 노출하지 않으며, Reverse Proxy를 통해서만 접근함
GitLab 내부 포트: 8081 (Reverse Proxy(Nginx)와 통신용, Loopback 또는 내부 네트워크 전용)
GitLab SSH 포트: 2222

1.1. 운영 정책¶

GitLab은 외부에 직접 노출하지 않음
GitLab Web Service 는 내부 포트(8081)만 사용
GitLab SSH Port 는 2222 포트로 분리 운영
TLS 종료는 Reverse Proxy(Nginx)에서 수행

2. 설정 파일 수정¶

sudo vi /etc/gitlab/gitlab.rb

3. 기본 설정¶

# 외부 접속 주소 (설치 시 설정값 확인)
external_url 'https://gitlab.example.com'

# 내부 Nginx 설정
nginx['listen_port'] = 8081
nginx['listen_https'] = false

# SSH 설정
gitlab_rails['gitlab_shell_ssh_port'] = 2222
gitlab_rails['gitlab_ssh_host'] = 'gitlab.example.com'
gitlab_sshd['enable'] = true
gitlab_sshd['listen_address'] = '[::]:2222'

# Let's Encrypt 비활성화
letsencrypt['enable'] = false

# 백업 경로
# /gitlab 상위 경로는 root:root 755 기준으로 유지함
# /gitlab/backups 는 03-gitlab-prepare-storage.md 에서 git:git 700 권한으로 사전 생성함
gitlab_rails['backup_path'] = '/gitlab/backups'
gitlab_rails['backup_keep_time'] = 604800

# 실접속 IP 반영
nginx['real_ip_header'] = 'X-Forwarded-For'
nginx['real_ip_recursive'] = true

3.1. 추가 보완 설정 (선택)¶

특수한 Reverse Proxy 또는 다단 프록시 환경에서 X-Forwarded-* 헤더 정합성 문제가 발생하는 경우, 다음 설정을 명시적으로 추가할 수 있음.

nginx['proxy_set_headers'] = {
    "X-Forwarded-Proto" => "https",
    "X-Forwarded-Ssl" => "on"
}

일반적인 환경에서는 external_url 'https://...' 설정만으로도 기본 헤더가 자동 적용됨
Redirect Loop, 422, CSRF 오류가 발생하는 경우 우선 앞단 Nginx의 proxy_set_header 전달 상태를 먼저 확인함
필요 시에만 명시적으로 override 함

4. 구성별 설정¶

GitLab 구성 방식에 따라 내부 바인딩 정책이 달라짐.

단일 서버 구성 (Nginx와 GitLab이 같은 서버)
- Reverse Proxy(Nginx) 와 GitLab을 동일 서버에서 운영하는 구조
분리 구성 (Nginx: 192.168.0.154, GitLab: 192.168.0.100)
- Gateway(Nginx) 와 GitLab을 서로 다른 서버에 분리하여 운영하는 구조
- GitLab Web Service 를 반드시 내부 포트(8081)로만 전달함. ex) proxy_pass http://192.168.0.100:8081;
앞단 프록시 헤더 설정은 08-GitLab Nginx Reverse Proxy 기준으로 유지함
trusted proxy 는 반드시 Reverse Proxy 서버만 지정함
trusted proxy 미설정 시 모든 요청이 프록시 IP로 인식됨

4.1 단일 서버 구성 (Nginx와 GitLab이 같은 서버)¶

Reverse Proxy(Nginx) 와 GitLab을 동일 서버에서 운영하는 구조
GitLab Web Service는 Loopback(127.0.0.1)만 사용

nginx['listen_addresses'] = ['127.0.0.1']

# 실접속 IP 반영
nginx['real_ip_trusted_addresses'] = ['127.0.0.1/32']
gitlab_rails['trusted_proxies'] = ['127.0.0.1/32']

4.2 분리 구성 (Nginx: 192.168.0.154, GitLab: 192.168.0.100)¶

Gateway(Nginx) 와 GitLab을 서로 다른 서버에 분리하여 운영하는 구조
GitLab Web Service 를 반드시 내부 포트(8081)로만 전달함. ex) proxy_pass http://192.168.0.100:8081;

nginx['listen_addresses'] = ['192.168.0.100']

# 실접속 IP 반영
nginx['real_ip_trusted_addresses'] = ['192.168.0.154/32']
gitlab_rails['trusted_proxies'] = ['192.168.0.154/32']

5. 설정 적용 및 상태 확인¶

sudo gitlab-ctl reconfigure
sudo gitlab-ctl status

6. 동작 확인¶

6.1 웹 접속 확인¶

curl -I https://gitlab.example.com

확인 항목:

로그인 페이지 정상 노출
redirect loop 없음
Mixed Content 없음

6.2 SSH 접속 확인¶

ssh -T git@gitlab.example.com -p 2222

정상 출력 예:

Welcome to GitLab, @username!

6.3 내부 포트 확인¶

sudo ss -tulnp | grep 8081

→ 127.0.0.1:8081 또는 192.168.0.100:8081 확인

6.4 GitLab 자체 점검¶

sudo gitlab-rake gitlab:check SANITIZE=true

7. Open Files Limit 확인 (Gitaly 최적화)¶

Omnibus GitLab은 설치 시 자동으로 조정하나, OS 환경에 따라 적용이 빗나갈 수 있으므로 반드시 확인함. GitLab(특히 Gitaly)은 파일 핸들을 대량으로 사용함.

Omnibus는 설치 시 자동으로 시스템 제한(Ulimit)을 조정하지만, 대규모 저장소 또는 동시 접속 증가 환경에서는 OS의 파일 디스크립터 제한에 의해 서비스 장애가 발생할 수 있으므로, 다음 기준으로 점검 및 설정함.

7.1. 설정 기준¶

시스템 기본값(sudo ulimit -n)보다 항상 높은 값으로 설정함
동시 사용자 및 저장소 수 증가를 고려하여 여유 있게 설정함
일반적인 운영 환경에서는 30000 이상을 권장함

Gitaly가 낮은 값으로 운영되면 too many open files 오류로 서비스가 중단될 수 있음

7.2. 현재 값 확인¶

# GitLab 서비스 레벨 확인
sudo systemctl show gitlab-runsvdir --property=LimitNOFILE

# Gitaly 프로세스 실제 적용값 확인
sudo cat /proc/$(pgrep -fo gitaly)/limits | grep "Max open files"

7.3. 값 조정¶

/etc/gitlab/gitlab.rb 에 추가:

gitaly['open_files_ulimit'] = 30000

적용 및 확인:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart gitaly

sudo cat /proc/$(pgrep -fo gitaly)/limits | grep "Max open files"

8. 문제 발생 시 체크¶

Redirect Loop
- external_url 확인
- Nginx의 proxy_set_header X-Forwarded-Proto https; 설정 여부 확인.
IP 차단 문제
- trusted_proxies 설정 확인
SSH 접속 문제
- Clone URL에 :2222 포함 여부 확인
- 방화벽 확인. 07-GitLab SELinux and Firewall 참조.
- gitlab-shell 설정 확인
CSS·JS·이미지·폰트 등 리소스 로드 오류
- Mixed Content 확인