GitLab Package Registry
GitLab Package Registry
1. 개요
GitLab Package Registry는 소프트웨어 개발 과정에서 생성되는 바이너리 패키지를 저장, 관리 및 배포할 수 있는 통합 패키지 저장소 서비스이다.
현대적인 CI/CD(지속적 통합/지속적 배포) 파이프라인에서 패키지 관리의 중요성은 매우 높다. 소스 코드를 매번 다시 빌드하는 대신, 이미 빌드된 불변(Immutable)의 패키지를 저장소에 보관하고 이를 참조함으로써 빌드 시간을 단축하고, 환경 간의 일관성을 보장하며, 의존성 관리를 체계화할 수 있기 때문이다.
💡 참고: Container Registry와의 차이점 GitLab은 Container Registry(Docker 이미지 저장소)와 Package Registry(바이너리 패키지 저장소)를 별도로 제공합니다. Container Registry가 레이어 기반의 컨테이너 이미지를 관리한다면, Package Registry는 라이브러리 파일(
.jar,.<a href="/doc/%EA%B8%B0%EC%88%A0/%EC%86%8C%ED%94%84%ED%8A%B8%EC%9B%A8%EC%96%B4%20%EA%B0%9C%EB%B0%9C/%EB%B9%8C%EB%93%9C%20%EB%B0%8F%20%EC%9D%98%EC%A1%B4%EC%84%B1%20%EA%B4%80%EB%A6%AC/npm" class="wiki-link">npm</a>,.whl등)과 같은 언어별 바이너리 패키지를 관리하는 데 특화되어 있습니다.
2. 지원하는 패키지 형식
GitLab Package Registry는 업계 표준 프로토콜을 준수하여 다양한 언어와 생태계의 패키지 매니저를 지원한다.
| 패키지 형식 | 관련 언어 | 표준 프로토콜 / 매핑 | 특징 |
|---|---|---|---|
| Maven | Java, Kotlin, Scala | Maven Repository | .jar 파일 저장, pom.xml 기반 의존성 관리 |
| npm | JavaScript, TypeScript | npm Registry | .tgz 파일 저장, package.json 기반 관리 |
| PyPI | Python | PyPI (PEP 503) | .whl, .tar.gz 파일 저장, pip 설치 지원 |
| NuGet | .NET (C#, F#) | NuGet API | .nupkg 파일 저장, Visual Studio 연동 |
| Composer | PHP | Packagist | composer.json 기반의 PHP 라이브러리 관리 |
| Generic | 공통 | REST API | 특정 형식에 구애받지 않는 임의의 바이너리 파일 저장 |
3. 작동 원리 및 아키텍처
3.1 프로젝트 단위 저장소 구조
GitLab Package Registry는 프로젝트(Project) 단위로 격리된 저장소 구조를 가진다. 각 프로젝트는 고유의 패키지 네임스페이스를 가지며, 이를 통해 조직 내 여러 팀이 서로 간섭 없이 독립적인 패키지 생태계를 구축할 수 있다.
3.2 인증 방식
패키지에 접근하거나 업로드하기 위해서는 적절한 권한 인증이 필요하며, 주로 다음 세 가지 토큰이 사용된다.
- Personal Access Token (PAT): 사용자 개인의 권한을 부여받은 토큰으로, 로컬 개발 환경에서 주로 사용된다.
- CI Job Token (CI_JOB_TOKEN): GitLab CI/CD 파이프라인 실행 시 자동으로 생성되는 단기 토큰으로, 파이프라인 내에서 패키지를 배포하거나 가져올 때 사용된다.
- Deploy Token: 특정 프로젝트에 대해 읽기/쓰기 권한을 부여하는 토큰으로, 외부 서버나 다른 프로젝트에서 접근할 때 사용된다.
3.3 버전 관리 메커니즘
패키지는 시맨틱 버저닝(Semantic Versioning, SemVer) 원칙에 따라 버전별로 저장된다. 동일한 버전의 패키지를 중복 업로드할 경우, 설정에 따라 덮어쓰기가 제한되거나 새로운 버전 태그를 요구하여 배포의 안정성을 확보한다.
4. 패키지 배포 및 설치 방법
4.1 로컬 환경 설정 및 배포
각 언어별 패키지 매니저 설정 파일에 GitLab Registry 주소를 등록해야 한다.
npm 설정 예시 (.npmrc):
${NPM_TOKEN}은 GitLab에서 생성한 Personal Access Token 또는 Deploy Token 환경 변수입니다.
@scope:registry=https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/
//gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/:${NPM_TOKEN}
PyPI 설정 예시 (~/.pypirc):
[distutils]
index-servers = gitlab
[gitlab]
repository = https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/pypi
username = <USERNAME>
password = <PERSONAL_ACCESS_TOKEN>
Maven 설정 예시 (settings.xml):
<settings>
<servers>
<server>
<id>gitlab-maven</id>
<configuration>
<httpHeaders>
<property>
<name>Private-Token</name>
<value>${GITLAB_PRIVATE_TOKEN}</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
NuGet 설정 예시 (NuGet.Config):
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="GitLab" value="https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/nuget/index.json" />
</packageSources>
<packageSourceCredentials>
<nugetDataSource>GitLab</nugetDataSource>
<username> <USERNAME> </username>
<password> <PERSONAL_ACCESS_TOKEN> </password>
</packageSourceCredentials>
</configuration>
4.2 GitLab CI/CD 파이프라인 배포 (.gitlab-ci.yml)
CI/CD 파이프라인을 통해 자동으로 패키지를 빌드하고 업로드하는 과정은 다음과 같다.
Generic Package API를 이용한 curl 업로드 예제:
CI_API_V4_URL은 GitLab 인스턴스의 API 기본 주소(예: https://gitlab.com/api/v4)를 나타내는 사전 정의된 변수입니다.
upload_package:
stage: deploy
script:
- curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
--upload-file bin/my-app.zip \
"${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my-app/${CI_COMMIT_TAG}/my-app.zip"
rules:
- if: $CI_COMMIT_TAG
5. 권한 관리 및 보안
5.1 접근 제어 (RBAC)
GitLab의 프로젝트 멤버십 권한 모델을 그대로 따른다. - Guest: 패키지 목록 조회 가능 (설정에 따라 제한됨) - Reporter: 패키지 다운로드(Read) 가능 - Developer: 패키지 업로드(Write) 및 다운로드 가능 - Maintainer/Owner: 패키지 삭제 및 설정 변경 가능
5.2 보안 취약점 스캔 연동
GitLab은 Dependency Scanning 기능을 통해 Package Registry에 등록된 패키지의 의존성을 분석한다. 알려진 CVE(Common Vulnerabilities and Exposures) 취약점이 발견될 경우, 파이프라인 결과에 경고를 표시하거나 배포를 차단하는 게이트웨이 역할을 수행한다.
6. 패키지 정리 정책 (Cleanup Policy)
저장 공간의 효율적인 관리와 오래된 버전의 제거를 위해 패키지 정리 정책을 설정할 수 있다.
- 자동 삭제 설정: 특정 기간 동안 사용되지 않았거나, 최신 버전으로부터 N개 이상의 이전 버전인 경우 자동으로 삭제하도록 설정 가능하다. 이를 통해 개발 단계에서 생성된 수많은 스냅샷 버전이 저장소를 점유하는 것을 방지한다.
- 보존 정책:
Stable태그가 붙은 버전이나 특정 릴리스 버전은 정리 대상에서 제외하여 하위 호환성을 유지한다. 이는 운영 환경에서 사용 중인 특정 버전이 실수로 삭제되는 것을 막기 위함이다. - 수동 정리: API 또는 UI를 통해 불필요한 패키지 버전을 선택적으로 삭제할 수 있다. 특히 Generic 패키지의 경우 명확한 버전 규칙이 없는 경우가 많으므로 관리자의 수동 정리가 권장된다.
7. 타 레지스트리와의 프록시 설정
GitLab Package Registry는 내부 패키지 저장뿐만 아니라, 외부 공용 레지스트리(예: Maven Central, npmjs.org)의 프록시 역할을 수행할 수 있다.
- 작동 방식: 사용자가 GitLab Registry에 패키지를 요청했을 때, 내부 저장소에 해당 패키지가 없으면 설정된 외부 업스트림(Upstream) 레지스트리에서 패키지를 가져와 캐싱한 후 제공한다.
- 장점:
- 외부 네트워크 장애 시에도 캐싱된 패키지를 통해 빌드 가능
- 외부 패키지 다운로드 트래픽 중앙 집중 관리 및 모니터링 가능
- 승인된 외부 패키지만 사용하도록 제한하는 거버넌스 구축 가능
8. 활용 사례 및 모범 사례
8.1 MSA에서의 공통 라이브러리 관리
마이크로서비스 아키텍처(MSA)에서는 여러 서비스가 공유하는 DTO(Data Transfer Object)나 유틸리티 클래스를 별도의 라이브러리 프로젝트로 분리한다. 이를 GitLab Package Registry에 배포하고 각 서비스에서 의존성으로 추가함으로써 코드 중복을 방지하고 변경 사항을 일괄 적용할 수 있다.
8.2 Generic 패키지 활용 사례
특정 언어의 패키지 매니저를 사용하지 않는 바이너리 파일의 경우 Generic Package Registry를 활용한다.
- Terraform Provider/Module: 커스텀 테라폼 모듈을 버전별로 저장하여 인프라 배포 시 참조.
- CLI 도구 배포: OS별로 빌드된 실행 파일(예: my-cli-linux-amd64, my-cli-win-x64)을 저장하여 설치 스크립트에서 다운로드.
- ML 모델 가중치: 학습이 완료된 딥러닝 모델 파일(.bin, .pth)을 버전별로 관리하여 추론 서버에서 배포.
8.3 버전 태깅 전략
- Snapshot/Beta 버전: 개발 단계에서는
1.0.0-SNAPSHOT또는1.0.0-beta.1과 같은 태그를 사용하여 빈번한 업데이트를 수행한다. - Release 버전: 검증이 완료된 코드는
1.0.0과 같이 정식 버전을 부여하며, 한 번 배포된 정식 버전은 절대 수정하지 않고 새로운 버전을 배포하는 불변성(Immutability) 원칙을 준수한다.
9. 버전별 호환성 매트릭스
GitLab 버전 및 라이선스에 따른 Package Registry 지원 범위는 다음과 같다.
| GitLab 버전 | Community Edition (CE) | Premium / Ultimate (EE) | 주요 지원 기능 |
|---|---|---|---|
| 14.x | ✓ | ✓ | 기본 패키지 형식 지원, CI Job Token 인증 |
| 15.x | ✓ | ✓ | Generic Packages 강화, 패키지 삭제 API 개선 |
| 16.x | ✓ | ✓ | 업스트림 프록시 기능 강화, 고급 정리 정책 |
| 17.x (Latest) | ✓ | ✓ | 보안 스캔 통합 심화, 성능 최적화 |
참고: 고급 보안 스캔 및 일부 세부 업스트림 프록시 설정은 Premium 이상의 라이선스에서만 제공됩니다.
이 문서는 AI 모델(gemma-4-31b)에 의해 생성된 콘텐츠입니다.
주의사항: AI가 생성한 내용은 부정확하거나 편향된 정보를 포함할 수 있습니다. 중요한 결정을 내리기 전에 반드시 신뢰할 수 있는 출처를 통해 정보를 확인하시기 바랍니다.