Linux 패키지 설치를 위한 구성 옵션

Tier: Free, Premium, Ultimate Offering: Self-Managed

GitLab을 구성하려면 /etc/gitlab/gitlab.rb 파일에 관련 옵션을 설정하십시오.

gitlab.rb.template에는 사용 가능한 옵션의 완전한 디렉터리이 포함되어 있습니다. 새로운 설치에는 템플릿에 나열된 모든 옵션이 기본적으로 /etc/gitlab/gitlab.rb에 나열됩니다.

note
/etc/gitlab/gitlab.rb를 편집할 때 제공된 예제는 항상 인스턴스의 기본 설정을 반영하지 않을 수 있습니다.

기본 설정 디렉터리은 패키지 기본값을 참조하세요.

GitLab의 외부 URL 구성

사용자에게 올바른 리포지터리 복제 링크를 표시하려면 GitLab이 사용자가 리포지터리에 액세스하는 데 사용하는 URL을 제공해야 합니다. 서버의 IP를 사용할 수 있지만 완전한 도메인 이름(FQDN)을 사용하는 것이 좋습니다. Self-Managed GitLab 인스턴스에서 DNS 사용에 대한 자세한 내용은 DNS 문서를 참조하십시오.

외부 URL 변경:

  1. 선택 사항. 외부 URL을 변경하기 전에 이전에 사용자 지정 홈페이지 URL 또는 로그아웃 후 경로를 정의했는지 확인하십시오. 이러한 설정은 새로운 외부 URL 구성 후 어의지 않는 리디렉션을 발생시킬 수 있습니다. URL을 정의한 경우 완전히 제거하십시오.

  2. /etc/gitlab/gitlab.rb를 수정하고 external_url을 원하는 URL로 변경하십시오:

    external_url "http://gitlab.example.com"
    

    또는 서버의 IP 주소를 사용할 수도 있습니다:

    external_url "http://10.0.0.1"
    

    이전 예에서는 일반 HTTP를 사용했습니다. HTTPS를 사용하려면 SSL 구성을 참조하십시오.

  3. GitLab을 재구성하십시오:

    sudo gitlab-ctl reconfigure
    
  4. 선택 사항. 일정 기간 동안 GitLab을 사용하고 있었다면 외부 URL을 변경한 후 Markdown 캐시를 무효화해야 합니다.

설치 시 외부 URL 지정

Linux 패키지를 사용하는 경우 EXTERNAL_URL 환경 변수를 사용하여 최소한의 명령어로 GitLab 인스턴스를 설정할 수 있습니다. 이 변수가 설정되면 자동으로 감지되어 그 값이 gitlab.rb 파일에 external_url로 쓰여집니다.

EXTERNAL_URL 환경 변수는 패키지의 설치 및 업그레이드에만 영향을 미칩니다. 일반적인 재구성 실행에서는 /etc/gitlab/gitlab.rb의 값이 사용됩니다.

패키지 업데이트의 일환으로 EXTERNAL_URL 변수가 무심코 설정된 경우 /etc/gitlab/gitlab.rb의 기존 값을 암시적으로 대체하며 경고없이 이루어집니다. 따라서 전역적으로 변수를 설정하지 않고 설치 명령에 명시적으로 전달하는 것이 좋습니다:

sudo EXTERNAL_URL="https://gitlab.example.com" apt-get install gitlab-ee

GitLab의 상대적 URL 구성

note
자체 컴파일(소스) 설치의 경우 별도 문서가 있습니다.

GitLab을 고유의 (하위)도메인에 설치하는 것이 좋지만 간혹 불가능할 때가 있습니다. 이 경우 GitLab을 https://example.com/gitlab와 같이 상대적 URL에 설치할 수 있습니다.

URL을 변경하면 모든 원격 URL도 변경되므로 GitLab 인스턴스를 가리키는 로컬 리포지터리의 모든 URL을 매뉴얼으로 편집해야 합니다.

GitLab에서 상대적 URL을 활성화하려면:

  1. /etc/gitlab/gitlab.rb에서 external_url을 설정하십시오:

    external_url "https://example.com/gitlab"
    

    이 예제에서 GitLab이 제공되는 상대적 URL은 /gitlab입니다. 원하는 값으로 변경하십시오.

  2. GitLab을 재구성하십시오:

    sudo gitlab-ctl reconfigure
    

문제가 발생하는 경우 문제 해결 섹션을 참조하십시오.

루트 사용자가 아닌 사용자로부터 외부 구성 파일 로드

Linux 패키지 설치는 모든 구성을 /etc/gitlab/gitlab.rb 파일에서 로드합니다. 이 파일에는 엄격한 파일 권한이 있으며 root 사용자가 소유하고 있습니다. 엄격한 권한과 소유권의 이유는 /etc/gitlab/gitlab.rbgitlab-ctl reconfigure에서 root 사용자에 의해 Ruby 코드로 실행되기 때문입니다. 따라서 /etc/gitlab/gitlab.rb에 쓰기 액세스 권한이 있는 사용자는 root에 의해 코드로 실행되는 구성을 추가할 수 있습니다.

일부 조직에서는 구성 파일에는 액세스할 수 있지만 루트 사용자로는 액세스할 수 없는 경우가 있습니다. 파일 안에서 외부 구성 파일을 지정하여 포함할 수 있습니다:

  1. /etc/gitlab/gitlab.rb를 수정하십시오:

    from_file "/home/admin/external_gitlab.rb"
    
  2. GitLab을 재구성하십시오:

    sudo gitlab-ctl reconfigure
    

from_file를 사용할 때:

  • from_file를 사용하여 /etc/gitlab/gitlab.rb에 포함된 코드는 GitLab을 재구성할 때 root 권한으로 실행됩니다.
  • from_file 이후에 /etc/gitlab/gitlab.rb에 설정된 구성은 포함된 파일의 구성보다 우선합니다.

파일에서 인증서 읽기

인증서는 별도의 파일로 저장하고 sudo gitlab-ctl reconfigure를 실행할 때 메모리에 로드할 수 있습니다. 인증서가 포함된 파일은 일반 텍스트여야 합니다.

이 예에서는 PostgreSQL 서버 인증서/etc/gitlab/gitlab.rb에 직접 복사하여 붙여넣는 대신 파일에서 읽습니다.

postgresql['internal_certificate'] = File.read('/path/to/server.crt')

Git 데이터를 대체 디렉터리에 저장

Linux 패키지 설치는 기본적으로 Git 리포지터리 데이터를 /var/opt/gitlab/git-data에 저장합니다. 리포지터리는 repositories라는 하위 폴더에 저장됩니다.

git-data 상위 디렉터리의 위치를 변경하려면:

  1. /etc/gitlab/gitlab.rb를 수정하십시오:

    git_data_dirs({ "default" => { "path" => "/mnt/nas/git-data" } })
    

    하나 이상의 Git 데이터 디렉터리를 추가할 수 있습니다:

    git_data_dirs({
      "default" => { "path" => "/var/opt/gitlab/git-data" },
      "alternative" => { "path" => "/mnt/nas/git-data" }
    })
    

    대상 디렉터리와 해당 하위 경로는 심볼릭 링크일 수 없습니다.

  2. GitLab을 재구성하십시오:

    sudo gitlab-ctl reconfigure
    
  3. 선택 사항. /var/opt/gitlab/git-data에 이미 기존의 Git 리포지터리가 있는 경우:

    1. 리포지터리를 이동하는 동안 사용자가 쓰기를 하지 못하도록합니다:

      sudo gitlab-ctl stop
      
    2. 리포지터리를 새 위치로 동기화하십시오. repositories 뒤에는 슬래시가 없으며, git-data 뒤에는 슬래시가 있습니다:

      sudo rsync -av --delete /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/
      
    3. 잘못된 권한을 수정하고 필요한 프로세스를 시작하도록 GitLab을 재구성하십시오:

      sudo gitlab-ctl reconfigure
      
    4. /mnt/nas/git-data/에서 디렉터리 레이아웃을 다시 확인하십시오. 예상 출력은 repositories여야 합니다:

      sudo ls /mnt/nas/git-data/
      
    5. GitLab을 시작하고 웹 인터페이스에서 리포지터리를 둘러볼 수 있는지 확인하십시오:

      sudo gitlab-ctl start
      

별도의 서버에서 Gitaly를 실행 중이라면 각 Git 데이터 디렉터리에 대해 gitaly_address를 포함해야 합니다. Gitaly 구성 설명서를 참조하십시오.

모든 리포지터리를 이동하는 대신 특정 프로젝트를 기존 리포지터리 스토리지 간에 이동하려면, 프로젝트 API 편집 엔드포인트를 사용하여 repository_storage 속성을 지정하십시오.

Git 사용자 또는 그룹 이름 변경

caution
기존 설치의 사용자 또는 그룹을 변경하는 것은 예측할 수없는 부작용을 일으킬 수 있으므로 변경을 권장하지 않습니다.

기본적으로 Linux 패키지 설치는 GitLab Shell 로그인을 위해 사용자 이름 git, Git 데이터 자체의 소유권 및 웹 인터페이스에서의 SSH URL 생성에 대해 git 그룹을 사용합니다. 마찬가지로 git 그룹은 Git 데이터의 그룹 소유권에 사용됩니다.

새로운 Linux 패키지 설치에서 사용자 및 그룹 변경:

  1. /etc/gitlab/gitlab.rb 파일 편집:

    user['username'] = "gitlab"
    user['group'] = "gitlab"
    
  2. GitLab 재구성:

    sudo gitlab-ctl reconfigure
    

기존 설치의 사용자 이름을 변경하는 경우, 재구성 실행은 중첩된 디렉터리의 소유권을 변경하지 않으므로 매뉴얼으로 수행해야 합니다.

적어도 리포지터리 및 업로드 디렉터리의 소유권을 변경해야 합니다:

sudo chown -R gitlab:gitlab /var/opt/gitlab/git-data/repositories
sudo chown -R gitlab:gitlab /var/opt/gitlab/gitlab-rails/uploads

숫자 사용자 및 그룹 식별자 지정

Linux 패키지 설치는 GitLab, PostgreSQL, Redis, NGINX 등의 사용자를 생성합니다. 이러한 사용자의 숫자 식별자를 지정하려면:

  1. 나중에 필요할 수 있으므로 이전 사용자 및 그룹 식별자를 기록합니다:

    sudo cat /etc/passwd
    
  2. /etc/gitlab/gitlab.rb 파일을 편집하고 원하는 식별자를 변경합니다:

    user['uid'] = 1234
    user['gid'] = 1234
    postgresql['uid'] = 1235
    postgresql['gid'] = 1235
    redis['uid'] = 1236
    redis['gid'] = 1236
    web_server['uid'] = 1237
    web_server['gid'] = 1237
    registry['uid'] = 1238
    registry['gid'] = 1238
    mattermost['uid'] = 1239
    mattermost['gid'] = 1239
    prometheus['uid'] = 1240
    prometheus['gid'] = 1240
    
  3. GitLab을 중지하고 재구성한 다음 GitLab을 시작합니다:

    sudo gitlab-ctl stop
    sudo gitlab-ctl reconfigure
    sudo gitlab-ctl start
    
  4. 선택 사항. user['uid']user['gid']를 변경하는 경우, Linux 패키지에서 직접 관리되지 않는 파일의 uid/guid를 반드시 업데이트하세요. 예를들어, 로그:

    find /var/log/gitlab -uid <old_uid> | xargs -I:: chown git ::
    find /var/log/gitlab -gid <old_uid> | xargs -I:: chgrp git ::
    find /var/opt/gitlab -uid <old_uid> | xargs -I:: chown git ::
    find /var/opt/gitlab -gid <old_uid> | xargs -I:: chgrp git ::
    

사용자 및 그룹 계정 관리 비활성화

기본적으로 Linux 패키지 설치는 시스템 사용자 및 그룹 계정을 생성하고 정보를 최신 상태로 유지합니다. 이러한 시스템 계정은 패키지의 다양한 컴포넌트를 실행합니다. 대부분의 사용자는 이 동작을 변경할 필요가 없습니다. 그러나 시스템 계정이 LDAP 등 다른 소프트웨어에 의해 관리되는 경우 GitLab 패키지에서의 계정 관리를 비활성화해야 할 수 있습니다.

기본적으로 Linux 패키지 설치는 다음 사용자와 그룹이 존재한다고 예상합니다:

Linux 사용자 및 그룹 필수 여부 설명 기본 홈 디렉터리 기본 셸
git GitLab 사용자/그룹 /var/opt/gitlab bin/sh
gitlab-www 웹 서버 사용자/그룹 /var/opt/gitlab/nginx /bin/false
gitlab-prometheus 프로메테우스 모니터링 및 다양한 익스포터를 위한 프로메테우스 사용자/그룹 /var/opt/gitlab/prometheus /bin/sh
gitlab-redis 패키지의 Redis를 사용하는 경우에만 필요 GitLab을 위한 Redis 사용자/그룹 /var/opt/gitlab/redis /bin/false
gitlab-psql 패키지의 PostgreSQL을 사용하는 경우에만 필요 PostgreSQL 사용자/그룹 /var/opt/gitlab/postgresql /bin/sh
gitlab-consul GitLab Consul을 사용하는 경우에만 필요 GitLab Consul 사용자/그룹 /var/opt/gitlab/consul /bin/sh
registry GitLab Registry를 사용하는 경우에만 필요 GitLab Registry 사용자/그룹 /var/opt/gitlab/registry /bin/sh
mattermost GitLab Mattermost를 사용하는 경우에만 필요 GitLab Mattermost 사용자/그룹 /var/opt/gitlab/mattermost /bin/sh

사용자 및 그룹 계정 관리를 비활성화하려면:

  1. /etc/gitlab/gitlab.rb 파일을 편집:

    manage_accounts['enable'] = false
    
  2. 선택 사항. 다른 사용자/그룹 이름을 사용할 수도 있지만 사용자/그룹 세부 정보를 지정해야 합니다:

    # GitLab
    user['username'] = "git"
    user['group'] = "git"
    user['shell'] = "/bin/sh"
    user['home'] = "/var/opt/custom-gitlab"
       
    # Web server
    web_server['username'] = 'webserver-gitlab'
    web_server['group'] = 'webserver-gitlab'
    web_server['shell'] = '/bin/false'
    web_server['home'] = '/var/opt/gitlab/webserver'
       
    # 프로메테우스
    prometheus['username'] = 'gitlab-prometheus'
    prometheus['group'] = 'gitlab-prometheus'
    prometheus['shell'] = '/bin/sh'
    prometheus['home'] = '/var/opt/gitlab/prometheus'
       
    # Redis (외부 Redis를 사용하지 않는 경우 필요 없음)
    redis['username'] = "redis-gitlab"
    redis['group'] = "redis-gitlab"
    redis['shell'] = "/bin/false"
    redis['home'] = "/var/opt/redis-gitlab"
       
    # PostgreSQL (외부 PostgreSQL을 사용하지 않는 경우 필요 없음)
    postgresql['username'] = "postgres-gitlab"
    postgresql['group'] = "postgres-gitlab"
    postgresql['shell'] = "/bin/sh"
    postgresql['home'] = "/var/opt/postgres-gitlab"
       
    # Consul
    consul['username'] = 'gitlab-consul'
    consul['group'] = 'gitlab-consul'
    consul['dir'] = "/var/opt/gitlab/registry"
       
    # 레지스트리
    registry['username'] = "registry"
    registry['group'] = "registry"
    registry['dir'] = "/var/opt/gitlab/registry"
       
    # Mattermost
    mattermost['username'] = 'mattermost'
    mattermost['group'] = 'mattermost'
    mattermost['home'] = '/var/opt/gitlab/mattermost'
    
  3. GitLab을 재구성:

    sudo gitlab-ctl reconfigure
    

사용자의 홈 디렉터리 이동

GitLab 사용자의 경우, 지역 디스크에 홈 디렉터리를 설정하는 것이 좋습니다. NFS와 같은 공유 스토리지가 아닌 로컬 디스크에 설정해야 성능이 향상됩니다. NFS에 설정하는 경우 Git 요청은 Git 구성을 읽기 위해 추가로 네트워크 요청을 만들어야 하며, Git 작업에서 지연이 증가합니다.

기존 홈 디렉터리를 이동하려면 GitLab 서비스를 중지해야하며 약간의 다운타임이 필요합니다:

  1. GitLab을 중지:

    sudo gitlab-ctl stop
    
  2. runit 서버를 중지:

    sudo systemctl stop gitlab-runsvdir
    
  3. 홈 디렉터리 변경:

    sudo usermod -d /path/to/home <username>
    

    기존 데이터가 있다면 새 위치로 매뉴얼으로 복사하거나 rsync해야 합니다:

  4. /etc/gitlab/gitlab.rb 파일을 편집:

    user['home'] = "/var/opt/custom-gitlab"
    
  5. runit 서버 시작:

    sudo systemctl start gitlab-runsvdir
    
  6. GitLab을 재구성:

    sudo gitlab-ctl reconfigure
    

리포지터리 디렉터리 관리 비활성화

Linux 패키지는 필요한 모든 디렉터리를 올바른 소유권과 권한으로 생성하며 이를 최신 상태로 유지합니다.

일부 디렉터리에는 대량의 데이터가 저장되어 있으므로 특정 설정에서는 이러한 디렉터리가 NFS(또는 다른) 공유에 마운트될 가능성이 높습니다.

루트 사용자(초기 설정의 기본 사용자)가 디렉터리를 자동으로 생성하는 것을 허용하지 않는 일부 마운트 유형에는 예를 들어 root_squash가 공유에 활성화된 NFS가 있습니다. 이러한 경우를 해결하기 위해 Linux 패키지는 디렉터리의 소유자 사용자를 사용하여 해당 디렉터리를 만들려고 시도합니다.

/etc/gitlab 디렉터리 관리 비활성화

/etc/gitlab 디렉터리가 마운트된 경우 해당 디렉터리의 관리를 중지할 수 있습니다.

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    manage_storage_directories['manage_etc'] = false
    
  2. GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    

/var/opt/gitlab 디렉터리 관리 비활성화

개별 마운트에 모든 GitLab 리포지터리 디렉터리를 마운트하는 경우 리포지터리 디렉터리의 관리를 완전히 비활성화해야 합니다.

Linux 패키지 설치는 이러한 디렉터리가 파일 시스템에 존재할 것으로 예상합니다. 이 설정이 설정된 경우 올바른 권한으로 디렉터리를 생성하고 설정하는 것은 여러분에게 달려 있습니다.

이 설정을 활성화하면 다음과 같은 디렉터리 생성을 방지합니다:

기본 위치 권한 소유권 목적
/var/opt/gitlab/git-data 0700 git:git 리포지터리 디렉터리 보유
/var/opt/gitlab/git-data/repositories 2770 git:git Git 리포지터리 보유
/var/opt/gitlab/gitlab-rails/shared 0751 git:gitlab-www 큰 객체 디렉터리 보유
/var/opt/gitlab/gitlab-rails/shared/artifacts 0700 git:git CI artifact 보유
/var/opt/gitlab/gitlab-rails/shared/external-diffs 0700 git:git 외부 Merge Request 차이 보유
/var/opt/gitlab/gitlab-rails/shared/lfs-objects 0700 git:git LFS 객체 보유
/var/opt/gitlab/gitlab-rails/shared/packages 0700 git:git 패키지 리포지터리 보유
/var/opt/gitlab/gitlab-rails/shared/dependency_proxy 0700 git:git 의존성 프록시 보유
/var/opt/gitlab/gitlab-rails/shared/terraform_state 0700 git:git terraform 상태 보유
/var/opt/gitlab/gitlab-rails/shared/ci_secure_files 0700 git:git 업로드된 안전한 파일 보유
/var/opt/gitlab/gitlab-rails/shared/pages 0750 git:gitlab-www 사용자 페이지 보유
/var/opt/gitlab/gitlab-rails/uploads 0700 git:git 사용자 첨부 파일 보유
/var/opt/gitlab/gitlab-ci/builds 0700 git:git CI 빌드 로그 보유
/var/opt/gitlab/.ssh 0700 git:git 인증된 키 보유

리포지터리 디렉터리의 관리를 비활성화하려면 다음을 수행합니다:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    manage_storage_directories['enable'] = false
    
  2. GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    

특정 파일 시스템이 마운트된 후에만 Linux 패키지 설치 서비스 시작

특정 파일 시스템이 마운트되기 전에 Linux 패키지 설치 서비스(NGINX, Redis, Puma, 등)가 시작되는 것을 방지하려면 high_availability['mountpoint'] 설정을 지정할 수 있습니다:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    # /var/opt/gitlab이 마운트될 때까지 기다립니다
    high_availability['mountpoint'] = '/var/opt/gitlab'
    
  2. GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    
    note
    마운트 지점이 존재하지 않으면 GitLab의 다시 구성에 실패합니다.

런타임 디렉터리 구성

Prometheus 모니터링이 활성화된 경우, GitLab Exporter는 각 Puma 프로세스의 메트릭값(Rails metrics)을 수행합니다. 각 Puma 프로세스는 컨트롤러 요청마다 메트릭 파일을 임시 위치에 작성해야 합니다. 그런 다음 Prometheus는 모든 이러한 파일을 수집하고 그 값을 처리합니다.

디스크 I/O를 생성하지 않으려면 Linux 패키지는 런타임 디렉터리를 사용합니다.

reconfigure 중에 패키지는 /runtmpfs로 마운트되어 있는지 확인합니다. 그렇지 않으면 다음 경고가 표시되고 Rails metrics가 비활성화됩니다:

런타임 디렉터리 '/run'이 tmpfs로 마운트되지 않았습니다.

다시 Rails 메트릭을 활성화하려면:

  1. /etc/gitlab/gitlab.rb을 편집하여 tmpfs 마운트를 만듭니다 (구성에 =가 없음에 주의하십시오):

    runtime_dir '/path/to/tmpfs'
    
  2. GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    

인증 실패 금지 설정

Git 및 컨테이너 레지스트리에 대한 인증 실패 금지 를 구성할 수 있습니다. 클라이언트가 금지되면 403 오류 코드가 반환됩니다.

다음과 같은 설정을 구성할 수 있습니다:

설정 설명
enabled 기본적으로 false입니다. Git 및 레지스트리 인증 금지를 활성화하려면 true로 설정합니다.
ip_whitelist 차단하지 않을 IP입니다. Ruby 배열의 문자열 형식으로 작성해야 합니다. 단일 IP 또는 CIDR 표기법을 사용할 수 있습니다. 예: ["127.0.0.1", "127.0.0.2", "127.0.0.3", "192.168.0.1/24"].
maxretry 특정 시간 안에 요청을 최대 횟수.
findtime IP가 차단 디렉터리에 추가되기 전에 실패한 요청을 계산할 수 있는 시간의 최대량(초).
bantime IP가 차단된 총 시간(초).

Git 및 컨테이너 레지스트리 인증 금지를 구성하려면:

  1. /etc/gitlab/gitlab.rb을 편집합니다:

    gitlab_rails['rack_attack_git_basic_auth'] = {
      'enabled' => true,
      'ip_whitelist' => ["127.0.0.1"],
      'maxretry' => 10, # IP당 Git HTTP 인증 시도 횟수 제한
      'findtime' => 60, # 60초 후에 IP당 인증 시도 카운터 재설정
      'bantime' => 3600 # IP가 너무 많은 인증 시도 후 1시간(3600초) 동안 금지
    }
    
  2. GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    

설치 중 자동 캐시 정리 비활성화

대규모 GitLab 설치의 경우 rake cache:clear 작업 실행을 원치 않을 수 있습니다. 이는 완료하는 데 오랜 시간이 걸릴 수 있습니다. 기본적으로 캐시 정리 작업은 재구성 중에 자동으로 실행됩니다.

설치 중 자동 캐시 정리를 비활성화하려면:

  1. /etc/gitlab/gitlab.rb을 수정합니다:

    # 전체 RAILS 환경을 로드하는 데 시간이 오래 걸리는 대규모 gitlab 배포에 사용되는 고급 기능입니다.
    gitlab_rails['rake_cache_clear'] = false
    
  2. GitLab을 다시 구성합니다:

    sudo gitlab-ctl reconfigure
    

Sentry를 사용한 오류 보고 및 로깅

caution
GitLab 17.0부터 Sentry 버전 21.5.0 이상만 지원됩니다. 호스팅하는 Sentry 인스턴스의 이전 버전을 사용 중이라면 GitLab 환경에서 오류를 계속 수집하려면 Sentry를 업그레이드해야 합니다.

Sentry는 오픈 소스 오류 보고 및 로깅 도구로, SaaS (https://sentry.io) 또는 자체 호스팅으로 사용할 수 있습니다.

Sentry 구성 방법:

  1. Sentry에서 프로젝트 생성.
  2. 생성한 프로젝트의 데이터 소스 이름(DSN) 찾기.
  3. /etc/gitlab/gitlab.rb 편집:

    gitlab_rails['sentry_enabled'] = true
    gitlab_rails['sentry_dsn'] = 'https://<public_key>@<host>/<project_id>'            # Rails SDK에서 사용하는 값
    gitlab_rails['sentry_clientside_dsn'] = 'https://<public_key>@<host>/<project_id>' # 브라우저 JavaScript SDK에서 사용하는 값
    gitlab_rails['sentry_environment'] = 'production'
    

    Sentry 환경을 사용하여 여러 배포된 GitLab 환경(예: lab, 개발, 스테이징 및 프로덕션)에서 오류 및 문제를 추적할 수 있습니다.

  4. 선택 사항. 특정 서버에서 보낸 모든 이벤트에 사용자 지정 Sentry 태그를 설정하려면 GITLAB_SENTRY_EXTRA_TAGS 환경 변수를 설정할 수 있습니다. 이 변수는 해당 서버에서의 모든 예외에 Sentry로 전달해야 하는 모든 태그를 나타내는 JSON 인코딩 해시입니다.

    예를 들어, 다음과 같이 설정:

    gitlab_rails['env'] = {
      'GITLAB_SENTRY_EXTRA_TAGS' => '{"stage": "main"}'
    }
    

    그렇게 하면 stage 태그가 main 값으로 추가됩니다.

  5. GitLab 재구성:

    sudo gitlab-ctl reconfigure
    

콘텐츠 전달 네트워크(연결 끊김 처리) URL 설정

콘텐츠 전달 네트워크(CDN) 또는 자산 호스트를 사용하여 정적 자산 제공하기 위해 gitlab_rails['cdn_host']를 설정할 수 있습니다. 이는 Rails 자산 호스트를 구성합니다.

CDN/자산 호스트 설정 방법:

  1. /etc/gitlab/gitlab.rb 편집:

    gitlab_rails['cdn_host'] = 'https://mycdnsubdomain.fictional-cdn.com'
    
  2. GitLab 재구성:

    sudo gitlab-ctl reconfigure
    

일반적인 서비스를 자산 호스트로 구성하는 추가 문서는 이 이슈에서 추적됩니다.

콘텐츠 보안 정책(CSP) 설정

콘텐츠 보안 정책(CSP)을 설정하면 JavaScript 교차 사이트 스크립팅(XSS) 공격을 방지할 수 있습니다. 자세한 내용은 Mozilla CSP 문서를 참조하십시오.

CSP 및 인라인 JavaScript에 대한 nonce-source는 GitLab.com에서 사용할 수 있습니다. Self-Managed형에서는 기본적으로 구성되지 않습니다.

note
CSP 규칙을 부적절하게 구성하면 GitLab의 작동이 제대로 동작하지 않을 수 있습니다. 정책을 전파하기 전에 report_onlytrue로 변경하여 구성을 테스트할 수도 있습니다.

CSP 추가 방법:

  1. /etc/gitlab/gitlab.rb 편집:

    gitlab_rails['content_security_policy'] = {
        enabled: true,
        report_only: false
    }
    

    GitLab은 CSP에 대해 안전한 기본값을 자동으로 제공합니다. 지시문에 <default_value> 값을 명시적으로 설정하면 기본값을 사용하는 것과 동일합니다.

    사용자 지정 CSP 추가:

    gitlab_rails['content_security_policy'] = {
        enabled: true,
        report_only: false,
        directives: {
          default_src: "'none'",
          script_src: "https://example.com"
        }
    }
    

    명시적으로 구성되지 않은 지시문에 대해서는 안전한 기본값이 사용됩니다.

    CSP 지시문을 해제하려면 값을 false로 설정하십시오.

  2. GitLab 재구성:

    sudo gitlab-ctl reconfigure
    

설치시 초기 루트 비밀번호 설정

관리자 사용자 root의 초기 암호는 설치시 설정할 수 있습니다. 자세한 내용은 초기 암호 설정을 참조하십시오.

호스트 해더 공격 방지를 위한 허용된 호스트 설정

의도한 것과 다른 호스트 헤더를 수락하지 않도록 GitLab을 설정하려면:

  1. /etc/gitlab/gitlab.rb 편집:

    gitlab_rails['allowed_hosts'] = ['gitlab.example.com']
    
  2. GitLab 재구성:

    sudo gitlab-ctl reconfigure
    

allowed_hosts를 구성하지 않았을 경우 GitLab에서 알려진 보안 문제는 없지만 잠재적인 HTTP Host 헤더 공격에 대비한 깊이 있는 방어를 위해 권장됩니다.

Apache와 같은 사용자 지정 외부 프록시를 사용하는 경우, 외부 프록시에 localhost 주소 또는 이름(localhost 또는 127.0.0.1)을 추가해야 할 수 있습니다. 외부 프록시를 통해 전달된 잠재적인 HTTP Host 헤더 공격을 완화하기 위해 외부 프록시에 필터를 추가해야 합니다.

gitlab_rails['allowed_hosts'] = ['gitlab.example.com', '127.0.0.1', 'localhost']

평문 리포지터리 없이 컴포넌트에 민감한 구성 제공

일부 컴포넌트는 gitlab.rb에서 extra_config_command 옵션을 노출합니다. 이를 통해 평문 리포지터리에서 읽는 대신 외부 스크립트에서 비밀 정보를 동적으로 제공할 수 있습니다.

사용 가능한 옵션:

gitlab.rb 설정 책임
gitlab_rails['redis_extra_config_command'] GitLab Rails 애플리케이션에서 사용하는 Redis 구성 파일(resque.yml, redis.yml, redis.<redis_instance>.yml 파일)에 추가 구성을 제공합니다.
gitlab_rails['db_extra_config_command'] GitLab Rails 애플리케이션에서 사용하는 DB 구성 파일(database.yml)에 추가 구성을 제공합니다.
gitlab_kas['extra_config_command'] Kubernetes (KAS) GitLab 에이전트 서버에 추가 구성을 제공합니다.
gitlab_workhorse['extra_config_command'] GitLab Workhorse에 추가 구성을 제공합니다.
gitlab_exporter['extra_config_command'] GitLab Exporter에 추가 구성을 제공합니다.

이러한 옵션 중 하나에 할당된 값은 필요한 형식으로 민감한 구성을 STDOUT로 작성하는 실행 가능한 스크립트의 절대 경로여야 합니다. 컴포넌트는 다음을 수행합니다.

  1. 제공된 스크립트 실행.
  2. 사용자 및 기본 구성 파일에서 설정한 값 대신 스크립트에서 생성된 값으로 대체.

클라이언트 컴포넌트에 Redis 암호 제공

예를 들어, Redis 서버의 암호를 Redis에 연결해야 하는 컴포넌트에 지정하려면 아래 스크립트 및 gitlab.rb 스니펫을 사용할 수 있습니다.

  1. 아래 스크립트를 /opt/generate-redis-conf로 저장:

    #!/opt/gitlab/embedded/bin/ruby
       
    require 'json'
    require 'yaml'
       
    class RedisConfig
      REDIS_PASSWORD = `echo "toomanysecrets"`.strip # 레디스 암호를 가져오는 backticks 내부 명령을 변경하십시오
         
      class << self
        def rails
          puts YAML.dump({
            'password' => REDIS_PASSWORD
          })
        end
           
        def kas
          puts YAML.dump({
            'redis' => {
              'password' => REDIS_PASSWORD
            }
          })
        end
           
        def workhorse
          puts JSON.dump({
            redis: {
              password: REDIS_PASSWORD
            }
          })
        end
           
        def gitlab_exporter
          puts YAML.dump({
            'probes' => {
              'sidekiq' => {
                'opts' => {
                  'redis_password' => REDIS_PASSWORD
                }
              }
            }
          })
        end
      end
    end
       
    def print_error_and_exit
      $stdout.puts "Usage: redis_credentials <COMPONENT>"
      $stderr.puts "Supported components are: rails, kas, workhorse, gitlab_exporter"
         
      exit 1
    end
       
    print_error_and_exit if ARGV.length != 1
       
    component = ARGV.shift
    begin
      RedisConfig.send(component.to_sym)
    rescue NoMethodError
      print_error_and_exit
    end
    
  2. 위에서 생성한 스크립트가 실행 가능한지 확인:

    chmod +x /opt/generate-redis-conf
    
  3. 아래 스니펫을 /etc/gitlab/gitlab.rb에 추가:

    gitlab_rails['redis_extra_config_command'] = '/opt/generate-redis-conf rails'
    gitlab_workhorse['extra_config_command'] = '/opt/generate-redis-conf workhorse'
    gitlab_kas['extra_config_command'] = '/opt/generate-redis-conf kas'
    gitlab_exporter['extra_config_command'] = '/opt/generate-redis-conf gitlab_exporter'
    
  4. sudo gitlab-ctl reconfigure 실행.

GitLab Rails에 대한 PostgreSQL 사용자 비밀번호 제공하기

예를 들어, PostgreSQL 서버에 연결하기 위해 GitLab Rails가 사용해야 하는 비밀번호를 제공하는 아래 스크립트와 구성을 사용할 수 있습니다.

  1. 아래 스크립트를 /opt/generate-db-config로 저장하세요:

    #!/opt/gitlab/embedded/bin/ruby
       
    require 'yaml'
       
    db_password = `echo "toomanysecrets"`.strip # backticks 내부의 명령을 수정하여 DB 비밀번호를 가져오세요
       
    puts YAML.dump({
     'main' => {
       'password' => db_password
     },
     'ci' => {
       'password' => db_password
     }
    })
    
  2. 위에서 생성한 스크립트가 실행 가능한지 확인하세요:

    chmod +x /opt/generate-db-config
    
  3. 아래 스니펫을 /etc/gitlab/gitlab.rb에 추가하세요:

    gitlab_rails['db_extra_config_command'] = '/opt/generate-db-config'
    
  4. sudo gitlab-ctl reconfigure를 실행하세요.

관련 주제

문제 해결

상대 URL 문제 해결

상대 URL 구성(이미지 누락 또는 미응답 컴포넌트와 같은)으로 전환한 후 GitLab 자산에 문제가 있는 경우, GitLabFrontend 레이블이 지정된 이슈를 등록해주세요.

Mixlib::ShellOut::ShellCommandFailed: linux_user[GitLab user and group]

사용자의 홈 디렉터리를 이동할 때 runit 서비스를 중지하지 않고 사용자의 홈 디렉터리를 매뉴얼으로 이동하지 않으면 GitLab을 재구성하는 동안 오류가 발생할 수 있습니다:

account[GitLab user and group] (gitlab::users line 28) had an error: Mixlib::ShellOut::ShellCommandFailed: linux_user[GitLab user and group] (/opt/gitlab/embedded/cookbooks/cache/cookbooks/package/resources/account.rb line 51) had an error: Mixlib::ShellOut::ShellCommandFailed: Expected process to exit with [0], but received '8'
---- Begin output of ["usermod", "-d", "/var/opt/gitlab", "git"] ----
STDOUT:
STDERR: usermod: user git is currently used by process 1234
---- End output of ["usermod", "-d", "/var/opt/gitlab", "git"] ----
Ran ["usermod", "-d", "/var/opt/gitlab", "git"] returned 8

홈 디렉터리를 이동하기 전에 runit을 중지해야 합니다.

GitLab이 Git 사용자 또는 그룹 이름을 변경한 후 502 응답

기존 설치에서 Git 사용자 또는 그룹 이름을 변경한 경우, 이로 인해 여러 부작용이 발생할 수 있습니다.

파일 접근에 관련된 오류를 확인하고 권한을 수정해보세요:

gitlab gitlab-ctl tail -f