GitLab 패키지 레지스트리 관리

요약

다양한 일반 패키지 관리자를 위한 비공개 리포지터리로 GitLab을 사용하려면 패키지 레지스트리를 사용하세요. 패키지 레지스트리는 다음 형식을 지원합니다: 패키지 레지스트리는 모델 레지스트리 데이터 저장에도 사용됩니다.

다양한 일반 패키지 관리자를 위한 비공개 리포지터리로 GitLab을 사용하려면 패키지 레지스트리를 사용하세요. 패키지를 빌드하고 게시할 수 있으며, 다운스트림 프로젝트에서 의존성으로 사용할 수 있습니다.

지원 형식#

패키지 레지스트리는 다음 형식을 지원합니다:

패키지 유형	GitLab 버전
Composer	13.2+
Conan 1	12.6+
Conan 2	18.1+
Go	13.1+
Maven	11.3+
npm	11.7+
NuGet	12.8+
PyPI	12.10+
Generic packages	13.5+
Helm Charts	14.1+

패키지 레지스트리는 모델 레지스트리 데이터 저장에도 사용됩니다.

기여 받기#

다음 표는 지원되지 않는 패키지 형식을 나열합니다. 이러한 형식에 대한 지원을 추가하기 위해 GitLab에 기여하는 것을 고려하세요.

형식	상태
Chef	#36889
CocoaPods	#36890
Conda	#36891
CRAN	#36892
Debian	Draft: Merge request
Opkg	#36894
P2	#36895
Puppet	#36897
RPM	#5932
RubyGems	#803
SBT	#36898
Terraform	Draft: Merge request
Vagrant	#36899

속도 제한#

다운스트림 프로젝트에서 의존성으로 패키지를 다운로드할 때 패키지 API를 통해 많은 요청이 이루어집니다. 따라서 적용된 사용자 및 IP 속도 제한에 도달할 수 있습니다. 이 문제를 해결하려면 패키지 API에 대한 특정 속도 제한을 정의할 수 있습니다. 자세한 내용은 패키지 레지스트리 속도 제한을 참조하세요.

패키지 레지스트리 활성화 또는 비활성화#

패키지 레지스트리는 기본적으로 활성화되어 있습니다. 비활성화하려면:

/etc/gitlab/gitlab.rb를 편집합니다:

# Change to true to enable packages - enabled by default if not defined
gitlab_rails['packages_enabled'] = false

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집합니다:

global:
  appConfig:
    packages:
      enabled: false

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['packages_enabled'] = false

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  packages:
    enabled: false

파일을 저장하고 GitLab을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

스토리지 경로 변경#

기본적으로 패키지는 로컬에 저장되지만 기본 로컬 위치를 변경하거나 오브젝트 스토리지를 사용할 수 있습니다.

로컬 스토리지 경로 변경#

기본적으로 패키지는 GitLab 설치에 상대적인 로컬 경로에 저장됩니다:

Linux package (Omnibus): /var/opt/gitlab/gitlab-rails/shared/packages/
Self-compiled (source): /home/git/gitlab/shared/packages/

로컬 스토리지 경로를 변경하려면:

/etc/gitlab/gitlab.rb를 편집하고 다음 줄을 추가합니다:
```
gitlab_rails['packages_storage_path'] = "/mnt/packages"
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  packages:
    enabled: true
    storage_path: /mnt/packages

파일을 저장하고 GitLab을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

이전 스토리지 경로에 이미 저장된 패키지가 있는 경우, 기존 패키지에 계속 액세스할 수 있도록 이전 위치에서 새 위치로 모든 것을 이동하세요:

mv /var/opt/gitlab/gitlab-rails/shared/packages/* /mnt/packages/

Docker와 Kubernetes는 로컬 스토리지를 사용하지 않습니다.

Helm 차트(Kubernetes)의 경우: 대신 오브젝트 스토리지를 사용하세요.
Docker의 경우: /var/opt/gitlab/ 디렉터리는 이미 호스트의 디렉터리에 마운트되어 있습니다. 컨테이너 내부의 로컬 스토리지 경로를 변경할 필요가 없습니다.

오브젝트 스토리지 사용#

로컬 스토리지에 의존하는 대신 오브젝트 스토리지를 사용하여 패키지를 저장할 수 있습니다.

자세한 내용은 통합 오브젝트 스토리지 설정 사용 방법을 참조하세요.

오브젝트 스토리지와 로컬 스토리지 간 패키지 마이그레이션#

오브젝트 스토리지를 구성한 후 다음 작업을 사용하여 로컬과 원격 스토리지 간에 패키지를 마이그레이션할 수 있습니다. 처리는 백그라운드 워커에서 수행되며 다운타임이 필요하지 않습니다.

오브젝트 스토리지로 마이그레이션#

마이그레이션 작업은 패키지 파일과 메타데이터 캐시를 오브젝트 스토리지로 이동합니다: 패키지 파일(packages_package_files), Helm 메타데이터 캐시(packages_helm_metadata_caches), NPM 메타데이터 캐시(packages_npm_metadata_caches), NuGet 기호(packages_nuget_symbols). 이전에 마이그레이션을 실행하여 이러한 유형 중 하나에 대한 파일이 남아 있는 경우 작업을 다시 실행하면 나머지 로컬 파일이 마이그레이션됩니다.

패키지를 오브젝트 스토리지로 마이그레이션합니다:

   sudo gitlab-rake "gitlab:packages:migrate"

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

PostgreSQL 콘솔을 사용하여 진행 상황을 추적하고 모든 패키지가 성공적으로 마이그레이션되었는지 확인합니다:

   sudo gitlab-rails dbconsole

   sudo gitlab-rails dbconsole --database main

   RAILS_ENV=production sudo -u git -H psql -d gitlabhq_production

다음 SQL 쿼리로 모든 패키지가 오브젝트 스토리지로 마이그레이션되었는지 확인합니다. objectstg 수는 total과 같아야 합니다:

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 packages_package_files;

예시 출력:

total | filesystem | objectstg
------+------------+-----------
 34   |          0 |        34

마지막으로 packages 디렉터리의 디스크에 파일이 없는지 확인합니다:

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

   sudo -u git find /home/git/gitlab/shared/packages -type f | grep -v tmp | wc -l

오브젝트 스토리지에서 로컬 스토리지로 마이그레이션#

오브젝트 스토리지로 이동할 때와 동일한 유형이 마이그레이션됩니다(패키지 파일, Helm 메타데이터 캐시, NPM 메타데이터 캐시, NuGet 기호).

오브젝트 스토리지에서 로컬 스토리지로 패키지를 마이그레이션합니다:

   sudo gitlab-rake "gitlab:packages:migrate[local]"

   RAILS_ENV=production sudo -u git -H bundle exec rake "gitlab:packages:migrate[local]"

PostgreSQL 콘솔을 사용하여 진행 상황을 추적하고 모든 패키지가 성공적으로 마이그레이션되었는지 확인합니다:

   sudo gitlab-rails dbconsole

   sudo gitlab-rails dbconsole --database main

   RAILS_ENV=production sudo -u git -H psql -d gitlabhq_production

다음 SQL 쿼리로 모든 패키지가 로컬 스토리지로 마이그레이션되었는지 확인합니다. filesystem 수는 total과 같아야 합니다:

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 packages_package_files;

예시 출력:

total | filesystem | objectstg
------+------------+-----------
 34   |         34 |         0

마지막으로 packages 디렉터리에 파일이 있는지 확인합니다:

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

   sudo -u git find /home/git/gitlab/shared/packages -type f | grep -v tmp | wc -l

GitLab 패키지 레지스트리 관리

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

원문 보기

번역일: 2026-05-22

요약

지원 형식#

패키지 레지스트리는 다음 형식을 지원합니다:

패키지 유형	GitLab 버전
Composer	13.2+
Conan 1	12.6+
Conan 2	18.1+
Go	13.1+
Maven	11.3+
npm	11.7+
NuGet	12.8+
PyPI	12.10+
Generic packages	13.5+
Helm Charts	14.1+

패키지 레지스트리는 모델 레지스트리 데이터 저장에도 사용됩니다.

기여 받기#

다음 표는 지원되지 않는 패키지 형식을 나열합니다. 이러한 형식에 대한 지원을 추가하기 위해 GitLab에 기여하는 것을 고려하세요.

형식	상태
Chef	#36889
CocoaPods	#36890
Conda	#36891
CRAN	#36892
Debian	Draft: Merge request
Opkg	#36894
P2	#36895
Puppet	#36897
RPM	#5932
RubyGems	#803
SBT	#36898
Terraform	Draft: Merge request
Vagrant	#36899

속도 제한#

패키지 레지스트리 활성화 또는 비활성화#

패키지 레지스트리는 기본적으로 활성화되어 있습니다. 비활성화하려면:

/etc/gitlab/gitlab.rb를 편집합니다:

# Change to true to enable packages - enabled by default if not defined
gitlab_rails['packages_enabled'] = false

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

Helm 값을 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집합니다:

global:
  appConfig:
    packages:
      enabled: false

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

docker-compose.yml을 편집합니다:

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['packages_enabled'] = false

파일을 저장하고 GitLab을 재시작합니다:
```
docker compose up -d
```

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  packages:
    enabled: false

파일을 저장하고 GitLab을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

스토리지 경로 변경#

기본적으로 패키지는 로컬에 저장되지만 기본 로컬 위치를 변경하거나 오브젝트 스토리지를 사용할 수 있습니다.

로컬 스토리지 경로 변경#

기본적으로 패키지는 GitLab 설치에 상대적인 로컬 경로에 저장됩니다:

Linux package (Omnibus): /var/opt/gitlab/gitlab-rails/shared/packages/
Self-compiled (source): /home/git/gitlab/shared/packages/

로컬 스토리지 경로를 변경하려면:

/etc/gitlab/gitlab.rb를 편집하고 다음 줄을 추가합니다:
```
gitlab_rails['packages_storage_path'] = "/mnt/packages"
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

/home/git/gitlab/config/gitlab.yml을 편집합니다:

production: &base
  packages:
    enabled: true
    storage_path: /mnt/packages

파일을 저장하고 GitLab을 재시작합니다:

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

이전 스토리지 경로에 이미 저장된 패키지가 있는 경우, 기존 패키지에 계속 액세스할 수 있도록 이전 위치에서 새 위치로 모든 것을 이동하세요:

mv /var/opt/gitlab/gitlab-rails/shared/packages/* /mnt/packages/

Docker와 Kubernetes는 로컬 스토리지를 사용하지 않습니다.

Helm 차트(Kubernetes)의 경우: 대신 오브젝트 스토리지를 사용하세요.
Docker의 경우: /var/opt/gitlab/ 디렉터리는 이미 호스트의 디렉터리에 마운트되어 있습니다. 컨테이너 내부의 로컬 스토리지 경로를 변경할 필요가 없습니다.

오브젝트 스토리지 사용#

로컬 스토리지에 의존하는 대신 오브젝트 스토리지를 사용하여 패키지를 저장할 수 있습니다.

자세한 내용은 통합 오브젝트 스토리지 설정 사용 방법을 참조하세요.

오브젝트 스토리지와 로컬 스토리지 간 패키지 마이그레이션#

오브젝트 스토리지로 마이그레이션#

패키지를 오브젝트 스토리지로 마이그레이션합니다:

   sudo gitlab-rake "gitlab:packages:migrate"

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

PostgreSQL 콘솔을 사용하여 진행 상황을 추적하고 모든 패키지가 성공적으로 마이그레이션되었는지 확인합니다:

   sudo gitlab-rails dbconsole

   sudo gitlab-rails dbconsole --database main

   RAILS_ENV=production sudo -u git -H psql -d gitlabhq_production

다음 SQL 쿼리로 모든 패키지가 오브젝트 스토리지로 마이그레이션되었는지 확인합니다. objectstg 수는 total과 같아야 합니다:

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 packages_package_files;

예시 출력:

total | filesystem | objectstg
------+------------+-----------
 34   |          0 |        34

마지막으로 packages 디렉터리의 디스크에 파일이 없는지 확인합니다:

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

   sudo -u git find /home/git/gitlab/shared/packages -type f | grep -v tmp | wc -l

오브젝트 스토리지에서 로컬 스토리지로 마이그레이션#

오브젝트 스토리지로 이동할 때와 동일한 유형이 마이그레이션됩니다(패키지 파일, Helm 메타데이터 캐시, NPM 메타데이터 캐시, NuGet 기호).

오브젝트 스토리지에서 로컬 스토리지로 패키지를 마이그레이션합니다:

   sudo gitlab-rake "gitlab:packages:migrate[local]"

   RAILS_ENV=production sudo -u git -H bundle exec rake "gitlab:packages:migrate[local]"

PostgreSQL 콘솔을 사용하여 진행 상황을 추적하고 모든 패키지가 성공적으로 마이그레이션되었는지 확인합니다:

   sudo gitlab-rails dbconsole

   sudo gitlab-rails dbconsole --database main

   RAILS_ENV=production sudo -u git -H psql -d gitlabhq_production

다음 SQL 쿼리로 모든 패키지가 로컬 스토리지로 마이그레이션되었는지 확인합니다. filesystem 수는 total과 같아야 합니다:

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 packages_package_files;

예시 출력:

total | filesystem | objectstg
------+------------+-----------
 34   |         34 |         0

마지막으로 packages 디렉터리에 파일이 있는지 확인합니다:

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

   sudo -u git find /home/git/gitlab/shared/packages -type f | grep -v tmp | wc -l