GitLab 의존성 프록시 관리

요약

컨테이너 이미지와 패키지를 포함하여 자주 액세스하는 업스트림 아티팩트에 대한 의존성 프록시로 GitLab을 사용할 수 있습니다. 이 문서는 관리 설명서입니다. GitLab 의존성 프록시는 다음과 같이 동작합니다. 의존성 프록시는 기본적으로 활성화되어 있습니다.

히스토리

GitLab Premium 11.11에서 도입.
13.6에서 GitLab Premium에서 GitLab Free로 이동.

컨테이너 이미지와 패키지를 포함하여 자주 액세스하는 업스트림 아티팩트에 대한 의존성 프록시로 GitLab을 사용할 수 있습니다.

이 문서는 관리 설명서입니다. 의존성 프록시를 사용하는 방법은 다음 문서를 참고합니다.

컨테이너 이미지용 의존성 프록시 사용자 가이드
가상 레지스트리 사용자 가이드

GitLab 의존성 프록시는 다음과 같이 동작합니다.

기본적으로 켜져 있습니다.
관리자가 끌 수 있습니다.

의존성 프록시 끄기#

의존성 프록시는 기본적으로 활성화되어 있습니다. 관리자라면 의존성 프록시를 끌 수 있습니다. 의존성 프록시를 끄려면 사용 중인 GitLab 설치에 해당하는 지침을 따릅니다.

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다.
```
gitlab_rails['dependency_proxy_enabled'] = false
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

설치가 완료된 후 의존성 프록시를 끄도록 전역 appConfig를 업데이트합니다.

global:
  appConfig:
    dependencyProxy:
      enabled: false
      bucket: gitlab-dependency-proxy
      connection:
        secret:
        key:

자세한 내용은 Globals를 사용하여 차트 구성을 참고합니다.

설치가 완료된 후 config/gitlab.yml의 dependency_proxy 섹션을 구성합니다. 의존성 프록시를 끄려면 enabled를 false로 설정합니다.
```
dependency_proxy:
  enabled: false
```
변경 사항을 적용하려면 GitLab을 재시작합니다.

멀티 노드 GitLab 설치#

각 웹 노드와 Sidekiq 노드에 대해 Linux 패키지 설치 단계를 따릅니다.

의존성 프록시 켜기#

의존성 프록시는 기본적으로 켜져 있지만 관리자가 끌 수 있습니다. 수동으로 끄려면 의존성 프록시 끄기의 지침을 따릅니다.

스토리지 경로 변경#

기본적으로 의존성 프록시 파일은 로컬에 저장되지만, 기본 로컬 위치를 변경하거나 오브젝트 스토리지를 사용할 수도 있습니다.

로컬 스토리지 경로 변경#

Linux 패키지 설치의 의존성 프록시 파일은 /var/opt/gitlab/gitlab-rails/shared/dependency_proxy/ 아래에 저장되고, 소스 설치의 경우 shared/dependency_proxy/(Git 홈 디렉터리 기준 상대 경로)에 저장됩니다.

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다.

gitlab_rails['dependency_proxy_storage_path'] = "/mnt/dependency_proxy"

파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

config/gitlab.yml의 dependency_proxy 섹션을 편집합니다.

dependency_proxy:
  enabled: true
  storage_path: shared/dependency_proxy

변경 사항을 적용하려면 GitLab을 재시작합니다.

오브젝트 스토리지 사용#

로컬 스토리지에 의존하는 대신 통합 오브젝트 스토리지 설정을 사용할 수 있습니다. 이 섹션은 이전 구성 형식을 설명합니다. 마이그레이션 단계는 그대로 적용됩니다.

GitLab에서 오브젝트 스토리지를 사용하는 방법을 참고합니다.

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다(필요한 경우 주석 처리를 해제합니다).

gitlab_rails['dependency_proxy_enabled'] = true
gitlab_rails['dependency_proxy_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/dependency_proxy"
gitlab_rails['dependency_proxy_object_store_enabled'] = true
gitlab_rails['dependency_proxy_object_store_remote_directory'] = "dependency_proxy" # The bucket name.
gitlab_rails['dependency_proxy_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
gitlab_rails['dependency_proxy_object_store_connection'] = {
  ##
  ## If the provider is AWS S3, uncomment the following
  ##
  #'provider' => 'AWS',
  #'region' => 'eu-west-1',
  #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
  #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
  ##
  ## If the provider is other than AWS (an S3-compatible one), uncomment the following
  ##
  #'host' => 's3.amazonaws.com',
  #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
  #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
  #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
}

파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

config/gitlab.yml의 dependency_proxy 섹션을 편집합니다(필요한 경우 주석 처리를 해제합니다).

dependency_proxy:
  enabled: true
  ##
  ## The location where build dependency_proxy are stored (default: shared/dependency_proxy).
  ##
  # storage_path: shared/dependency_proxy
  object_store:
    enabled: false
    remote_directory: dependency_proxy  # The bucket name.
    #  proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
    connection:
    ##
    ## If the provider is AWS S3, use the following
    ##
      provider: AWS
      region: us-east-1
      aws_access_key_id: AWS_ACCESS_KEY_ID
      aws_secret_access_key: AWS_SECRET_ACCESS_KEY
      ##
      ## If the provider is other than AWS (an S3-compatible one), comment out the previous 4 lines and use the following instead:
      ##
      #  host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
      #  aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
      #  endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
      #  path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.

변경 사항을 적용하려면 GitLab을 재시작합니다.

로컬 의존성 프록시 blob 및 매니페스트를 오브젝트 스토리지로 마이그레이션#

오브젝트 스토리지를 구성한 후 다음 태스크로 기존 의존성 프록시 blob과 매니페스트를 로컬 스토리지에서 원격 스토리지로 마이그레이션합니다. 처리는 백그라운드 워커에서 수행되며 다운타임이 필요하지 않습니다.

Linux 패키지 설치의 경우:

sudo gitlab-rake "gitlab:dependency_proxy:migrate"

자체 컴파일 설치의 경우:

RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:dependency_proxy:migrate

PostgreSQL 콘솔로 진행 상황을 추적하고 모든 의존성 프록시 blob과 매니페스트가 정상적으로 마이그레이션되었는지 확인할 수도 있습니다.

Linux 패키지 설치는 sudo gitlab-rails dbconsole --database main 입니다.
자체 컴파일 인스턴스는 sudo -u git -H psql -d gitlabhq_production 입니다.

각 쿼리에서 objectstg(file_store = '2' 인 항목)가 모든 의존성 프록시 blob과 매니페스트의 개수와 같은지 확인합니다.

gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM dependency_proxy_blobs;

total | filesystem | objectstg
------+------------+-----------
 22   |          0 |        22

gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM dependency_proxy_manifests;

total | filesystem | objectstg
------+------------+-----------
 10   |          0 |        10

dependency_proxy 폴더의 디스크에 파일이 남아 있지 않은지 확인합니다.

sudo find /var/opt/gitlab/gitlab-rails/shared/dependency_proxy -type f | grep -v tmp | wc -l

JWT 만료 시간 변경#

의존성 프록시는 Docker v2 토큰 인증 흐름을 따르며, 풀 요청에 사용할 JWT를 클라이언트에 발급합니다. 토큰 만료 시간은 애플리케이션 설정 container_registry_token_expire_delay로 구성할 수 있습니다. 이 값은 Rails 콘솔에서 변경할 수 있습니다.

# update the JWT expiration to 30 minutes
ApplicationSetting.update(container_registry_token_expire_delay: 30)

기본 만료 시간과 GitLab.com의 만료 시간은 15분입니다.

프록시 뒤에서 의존성 프록시 사용#

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다.

gitlab_workhorse['env'] = {
  "http_proxy" => "http://USERNAME:PASSWORD@example.com:8080",
  "https_proxy" => "http://USERNAME:PASSWORD@example.com:8080"
}

파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

GitLab 의존성 프록시 관리

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

히스토리

GitLab Premium 11.11에서 도입.
13.6에서 GitLab Premium에서 GitLab Free로 이동.

컨테이너 이미지와 패키지를 포함하여 자주 액세스하는 업스트림 아티팩트에 대한 의존성 프록시로 GitLab을 사용할 수 있습니다.

이 문서는 관리 설명서입니다. 의존성 프록시를 사용하는 방법은 다음 문서를 참고합니다.

컨테이너 이미지용 의존성 프록시 사용자 가이드
가상 레지스트리 사용자 가이드

GitLab 의존성 프록시는 다음과 같이 동작합니다.

기본적으로 켜져 있습니다.
관리자가 끌 수 있습니다.

의존성 프록시 끄기#

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다.
```
gitlab_rails['dependency_proxy_enabled'] = false
```
파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

설치가 완료된 후 의존성 프록시를 끄도록 전역 appConfig를 업데이트합니다.

global:
  appConfig:
    dependencyProxy:
      enabled: false
      bucket: gitlab-dependency-proxy
      connection:
        secret:
        key:

자세한 내용은 Globals를 사용하여 차트 구성을 참고합니다.

설치가 완료된 후 config/gitlab.yml의 dependency_proxy 섹션을 구성합니다. 의존성 프록시를 끄려면 enabled를 false로 설정합니다.
```
dependency_proxy:
  enabled: false
```
변경 사항을 적용하려면 GitLab을 재시작합니다.

멀티 노드 GitLab 설치#

각 웹 노드와 Sidekiq 노드에 대해 Linux 패키지 설치 단계를 따릅니다.

의존성 프록시 켜기#

의존성 프록시는 기본적으로 켜져 있지만 관리자가 끌 수 있습니다. 수동으로 끄려면 의존성 프록시 끄기의 지침을 따릅니다.

스토리지 경로 변경#

기본적으로 의존성 프록시 파일은 로컬에 저장되지만, 기본 로컬 위치를 변경하거나 오브젝트 스토리지를 사용할 수도 있습니다.

로컬 스토리지 경로 변경#

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다.

gitlab_rails['dependency_proxy_storage_path'] = "/mnt/dependency_proxy"

파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

config/gitlab.yml의 dependency_proxy 섹션을 편집합니다.

dependency_proxy:
  enabled: true
  storage_path: shared/dependency_proxy

변경 사항을 적용하려면 GitLab을 재시작합니다.

오브젝트 스토리지 사용#

GitLab에서 오브젝트 스토리지를 사용하는 방법을 참고합니다.

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다(필요한 경우 주석 처리를 해제합니다).

gitlab_rails['dependency_proxy_enabled'] = true
gitlab_rails['dependency_proxy_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/dependency_proxy"
gitlab_rails['dependency_proxy_object_store_enabled'] = true
gitlab_rails['dependency_proxy_object_store_remote_directory'] = "dependency_proxy" # The bucket name.
gitlab_rails['dependency_proxy_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
gitlab_rails['dependency_proxy_object_store_connection'] = {
  ##
  ## If the provider is AWS S3, uncomment the following
  ##
  #'provider' => 'AWS',
  #'region' => 'eu-west-1',
  #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
  #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
  ##
  ## If the provider is other than AWS (an S3-compatible one), uncomment the following
  ##
  #'host' => 's3.amazonaws.com',
  #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
  #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
  #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
}

파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.

config/gitlab.yml의 dependency_proxy 섹션을 편집합니다(필요한 경우 주석 처리를 해제합니다).

dependency_proxy:
  enabled: true
  ##
  ## The location where build dependency_proxy are stored (default: shared/dependency_proxy).
  ##
  # storage_path: shared/dependency_proxy
  object_store:
    enabled: false
    remote_directory: dependency_proxy  # The bucket name.
    #  proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
    connection:
    ##
    ## If the provider is AWS S3, use the following
    ##
      provider: AWS
      region: us-east-1
      aws_access_key_id: AWS_ACCESS_KEY_ID
      aws_secret_access_key: AWS_SECRET_ACCESS_KEY
      ##
      ## If the provider is other than AWS (an S3-compatible one), comment out the previous 4 lines and use the following instead:
      ##
      #  host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
      #  aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
      #  endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
      #  path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.

변경 사항을 적용하려면 GitLab을 재시작합니다.

로컬 의존성 프록시 blob 및 매니페스트를 오브젝트 스토리지로 마이그레이션#

Linux 패키지 설치의 경우:

sudo gitlab-rake "gitlab:dependency_proxy:migrate"

자체 컴파일 설치의 경우:

RAILS_ENV=production sudo -u git -H bundle exec rake gitlab:dependency_proxy:migrate

PostgreSQL 콘솔로 진행 상황을 추적하고 모든 의존성 프록시 blob과 매니페스트가 정상적으로 마이그레이션되었는지 확인할 수도 있습니다.

Linux 패키지 설치는 sudo gitlab-rails dbconsole --database main 입니다.
자체 컴파일 인스턴스는 sudo -u git -H psql -d gitlabhq_production 입니다.

각 쿼리에서 objectstg(file_store = '2' 인 항목)가 모든 의존성 프록시 blob과 매니페스트의 개수와 같은지 확인합니다.

gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM dependency_proxy_blobs;

total | filesystem | objectstg
------+------------+-----------
 22   |          0 |        22

gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM dependency_proxy_manifests;

total | filesystem | objectstg
------+------------+-----------
 10   |          0 |        10

dependency_proxy 폴더의 디스크에 파일이 남아 있지 않은지 확인합니다.

sudo find /var/opt/gitlab/gitlab-rails/shared/dependency_proxy -type f | grep -v tmp | wc -l

JWT 만료 시간 변경#

# update the JWT expiration to 30 minutes
ApplicationSetting.update(container_registry_token_expire_delay: 30)

기본 만료 시간과 GitLab.com의 만료 시간은 15분입니다.

프록시 뒤에서 의존성 프록시 사용#

/etc/gitlab/gitlab.rb를 편집하여 다음 줄을 추가합니다.

gitlab_workhorse['env'] = {
  "http_proxy" => "http://USERNAME:PASSWORD@example.com:8080",
  "https_proxy" => "http://USERNAME:PASSWORD@example.com:8080"
}

파일을 저장하고 변경 사항을 적용하려면 GitLab을 재구성합니다.