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+

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

기여 받기#

다음 표는 지원되지 않는 패키지 형식을 정리한 것입니다. 이러한 형식에 대한 지원을 추가하는 기여를 검토해 볼 수 있습니다.

형식	상태
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

속도 제한#

다운스트림 프로젝트에서 패키지를 의존성으로 내려받을 때 Packages API를 통해 많은 요청이 발생합니다. 그 결과 사용자 및 IP에 적용되는 속도 제한에 도달할 수 있습니다. 이 문제를 해결하려면 Packages 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 chart (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 패키지 레지스트리 관리

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

지원 형식#

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

패키지 유형	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+

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

기여 받기#

다음 표는 지원되지 않는 패키지 형식을 정리한 것입니다. 이러한 형식에 대한 지원을 추가하는 기여를 검토해 볼 수 있습니다.

형식	상태
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 chart (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