최상위 아티팩트 관리 그룹 안의 전용 프로젝트에서 패키지를 유형별로 구성합니다. 이 방식은 명확한 소유권과 유형별 정책을 제공합니다.

다음과 같은 경우에 이 방식을 사용합니다:

• 전용 정책과 설정으로 패키지를 유형별로 구성하려는 경우.
• 조직의 모든 패키지에 단일 소비 엔드포인트를 제공하려는 경우.
• 서드파티 레지스트리의 패키지를 체계적으로 구성된 GitLab 환경으로 마이그레이션하려는 경우.
• 패키지 관리 업무를 애플리케이션 소스 코드와 분리하려는 경우.
• 패키지 유형별로 서로 다른 거버넌스 정책을 적용하려는 경우.
• 조직 전체의 액세스를 허용하면서 소유권은 명확하게 유지하려는 경우.

예제 안내#

이 방식으로 패키지를 효과적으로 구성하고 관리하려면 다음을 수행합니다:

• 패키지 유형별로 프로젝트를 구성한 아티팩트 관리 전용 최상위 그룹을 만듭니다.
• 패키지를 소비할 때의 성능을 높이기 위해 최상위 그룹에는 아티팩트가 있는 프로젝트만 둡니다.

권장 구조#

다음 예제는 최상위 그룹과 프로젝트를 어떻게 구성해야 하는지 개요로 보여 줍니다:

company_namespace/artifact_management/ # top-level group
├── java-packages/           # Maven packages
├── node-packages/           # npm packages
├── python-packages/         # PyPI packages
├── docker-images/           # Container registry
├── terraform-modules/       # Terraform modules
├── nuget-packages/          # NuGet packages
└── generic-packages/        # Generic file packages

그룹 및 프로젝트 생성#

아티팩트 관리를 위한 새 최상위 그룹을 만듭니다:

1. 상단 바에서 Create new (+) 와 New group 을 선택합니다.
2. Create group 을 선택합니다.
3. Group name 텍스트 박스에 Artifact Management 또는 비슷한 이름을 입력합니다.
4. Group URL 에서는 생성된 경로를 그대로 둡니다.
5. 그룹의 Visibility level을 선택합니다.
6. Create group 을 선택합니다.

필요한 패키지 유형마다 프로젝트를 만듭니다:

1. 상단 바에서 Search or go to 를 선택하고 아티팩트 관리 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Create new (+) 와 New project/repository 를 선택합니다.
3. Create blank project 를 선택합니다.
4. 원하는 패키지 유형에 맞는 Project name 을 입력합니다. 예를 들어 java-packages 나 node-packages 입니다.
5. 적절한 공개 수준을 설정합니다.
6. Create project 를 선택합니다.

조직에서 가장 많이 쓰는 패키지 유형부터 시작하고, 패키지 형식을 추가로 도입하면서 구조를 확장합니다. 이 방식은 보안과 사용 편의성을 유지하면서 자연스럽게 확장됩니다.

그룹 설정을 구성합니다:

1. 아티팩트 관리 그룹의 왼쪽 사이드바에서 Settings > Packages and registries 를 선택합니다.
2. Duplicate packages 나 Package forwarding 처럼 필요한 그룹 정책을 구성합니다.
3. 필요에 따라 그룹 액세스 제어를 설정합니다.

인증 및 액세스 구성#

인증 방식은 사용 사례에 따라 다릅니다. 아래 제안을 참고합니다. 인증에 대한 자세한 내용은 레지스트리 인증을 참고합니다

로컬 개발(개발자)의 경우:

• 개별 개발자용 개인 액세스 토큰
• 팀이 공유하는 자격 증명용 그룹 액세스 토큰

CI/CD 파이프라인의 경우:

• CI/CD job 토큰(권장) - 자동으로 인증됩니다
• 특수한 경우를 위한 프로젝트 액세스 토큰

외부 시스템의 경우:

• 읽기 전용 소비를 위한 배포 토큰
• 더 세밀하게 제어하기 위한 프로젝트 및 그룹 액세스 토큰

최상위 그룹 액세스 설정#

조직 전체의 패키지 소비를 위해 그룹 배포 토큰을 만듭니다:

1. 아티팩트 관리 그룹의 왼쪽 사이드바에서 Settings > Repository 를 선택합니다.
2. Deploy tokens 를 확장합니다.
3. Add token 을 선택하고 필드를 입력합니다:
   • Name 에는 package-consumption 을 입력합니다.
   • Scopes 에서는 read_package_registry 를 선택합니다.
4. Create deploy token 을 선택합니다.

토큰은 안전하게 보관합니다.

게시에 CI/CD job 토큰을 사용하려면 job 토큰 허용 목록을 구성합니다:

1. 각 패키지별 프로젝트의 왼쪽 사이드바에서 Settings > CI/CD 를 선택합니다.
2. Token Access 를 확장합니다.
3. 이 패키지 레지스트리에 패키지를 게시할 수 있게 허용할 프로젝트를 추가합니다.

프로젝트 설정 구성#

패키지 유형별 프로젝트마다 다음을 구성합니다:

• 해당 패키지 유형에 맞는 Lifecycle policies
• 필요한 경우 Protected packages 규칙
• 필요한 경우 Protected container tag 규칙
• 특정 사용 사례를 위한 Project access tokens

패키지 게시#

팀은 해당 유형에 맞는 프로젝트 레지스트리에 패키지를 게시합니다. 지원되는 패키지 형식별 예제는 다음과 같습니다.

<distributionManagement>
    <repository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/JAVA_PACKAGES_PROJECT_ID/packages/maven</url>
    </repository>
    <snapshotRepository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/JAVA_PACKAGES_PROJECT_ID/packages/maven</url>
    </snapshotRepository>
</distributionManagement>

<servers>
    <server>
        <id>gitlab-maven</id>
        <configuration>
            <httpHeaders>
                <property>
                    <name>Job-Token</name>
                    <value>${CI_JOB_TOKEN}</value>
                </property>
            </httpHeaders>
        </configuration>
    </server>
</servers>

mvn deploy

{
  "name": "@company/my-package",
  "publishConfig": {
    "registry": "${CI_API_V4_URL}/projects/NODE_PACKAGES_PROJECT_ID/packages/npm/"
  }
}

publish:
  script:
    - npm publish

npm config set @company:registry https://gitlab.example.com/api/v4/projects/NODE_PACKAGES_PROJECT_ID/packages/npm/
npm config set //gitlab.example.com/api/v4/projects/NODE_PACKAGES_PROJECT_ID/packages/npm/:_authToken ${PERSONAL_ACCESS_TOKEN}

publish:
  script:
    - pip install build twine
    - python -m build
    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token twine upload --repository-url ${CI_API_V4_URL}/projects/PYTHON_PACKAGES_PROJECT_ID/packages/pypi dist/*

twine upload --repository-url https://gitlab.example.com/api/v4/projects/PYTHON_PACKAGES_PROJECT_ID/packages/pypi --username __token__ --password ${PERSONAL_ACCESS_TOKEN} dist/*

build-image:
  script:
    - docker build -t $CI_REGISTRY/artifact-management/docker-images/my-app:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY/artifact-management/docker-images/my-app:$CI_COMMIT_SHA

docker login gitlab.example.com -u ${USERNAME} -p ${PERSONAL_ACCESS_TOKEN}
docker push gitlab.example.com/artifact-management/docker-images/my-app:latest

publish-module:
  script:
    - tar -czf module.tar.gz *.tf
    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file module.tar.gz "${CI_API_V4_URL}/projects/TERRAFORM_PACKAGES_PROJECT_ID/packages/terraform/modules/my-module/my-provider/1.0.0/file"'

publish:
  script:
    - dotnet pack
    - dotnet nuget push "bin/Release/*.nupkg" --source ${CI_API_V4_URL}/projects/NUGET_PACKAGES_PROJECT_ID/packages/nuget/index.json --api-key ${CI_JOB_TOKEN}

dotnet nuget push package.nupkg --source https://gitlab.example.com/api/v4/projects/NUGET_PACKAGES_PROJECT_ID/packages/nuget/index.json --api-key ${PERSONAL_ACCESS_TOKEN}

upload-package:
  script:
    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file my-package.zip "${CI_API_V4_URL}/projects/GENERIC_PACKAGES_PROJECT_ID/packages/generic/my-package/1.0.0/my-package.zip"'

패키지 소비#

패키지를 소비할 때는 다음 중 하나를 사용할 수 있습니다:

• Maven 가상 레지스트리를 사용합니다.
• 최상위 그룹 엔드포인트를 사용합니다.

Maven 가상 레지스트리 사용(베타)#

Maven 가상 레지스트리는 여러 소스의 패키지를 집계해 아티팩트 관리 환경을 개선할 수 있습니다. 다음을 수행할 수 있습니다:

• Maven 용 최상위 그룹 엔드포인트를 업스트림으로 사용해 내부 패키지를 추가합니다. 예를 들어 https://gitlab.example.com/api/v4/groups/artifact-management/-/packages/maven 입니다.
• Maven Central 이나 사설 레지스트리 같은 외부 업스트림 레지스트리를 추가합니다.
• 다른 GitLab 프로젝트나 그룹을 추가합니다.

이 방식은 내부 의존성과 외부 의존성을 결합한 단일 엔드포인트를 제공하며, 지능적인 캐싱과 업스트림 우선순위 지정을 함께 제공합니다.

다음과 같은 경우에 Maven 가상 레지스트리를 사용합니다:

• 내부 GitLab 패키지와 외부 업스트림 레지스트리를 집계해야 하는 경우
• 안정성을 높이기 위해 외부 의존성을 캐시하려는 경우
• 공개 레지스트리보다 사설 레지스트리를 우선해야 하는 경우
• 내부 의존성과 외부 의존성을 모두 처리하는 단일 엔드포인트를 원하는 경우

Maven 가상 레지스트리는 게시를 지원하지 않습니다.

자세한 내용은 Maven 가상 레지스트리를 참고합니다.

최상위 아티팩트 관리 그룹에서 Maven 가상 레지스트리 구성#

1. 최상위 그룹에서 가상 레지스트리를 만듭니다:
   • artifact-management 그룹에서 Deploy > Virtual registry 로 이동합니다.
   • Maven 가상 레지스트리를 만듭니다(예: "Company Maven Registry").
2. 업스트림 레지스트리를 구성합니다:
   • 내부 java-packages 프로젝트를 업스트림으로 추가합니다.
   • Maven Central 이나 사설 리포지터리 같은 외부 레지스트리를 추가합니다.
   • 사설 레지스트리를 앞에, 공개 레지스트리를 뒤에 두도록 업스트림 순서를 정합니다.
3. 가상 레지스트리를 사용하도록 Maven 클라이언트를 구성합니다:

   <mirrors>
     <mirror>
       <id>central-proxy</id>
       <name>GitLab virtual registry</name>
       <url>https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id></url>
       <mirrorOf>central</mirrorOf>
     </mirror>
   </mirrors>

가상 레지스트리는 개인 액세스 토큰, 그룹 배포 토큰, 그룹 액세스 토큰, CI/CD job 토큰 등 여러 토큰 유형을 지원합니다. 토큰 유형마다 서로 다른 HTTP 헤더 이름을 사용합니다. 자세한 내용은 가상 레지스트리 인증을 참고합니다.

다음 예제는 개인 액세스 토큰을 사용합니다:

   <servers>
     <server>
       <id>gitlab-maven</id>
       <configuration>
         <httpHeaders>
           <property>
             <name>Private-Token</name>
             <value>${PERSONAL_ACCESS_TOKEN}</value>
           </property>
         </httpHeaders>
       </configuration>
     </server>
   </servers>

최상위 그룹 엔드포인트 구성#

최상위 그룹 엔드포인트에서 패키지를 소비하도록 프로젝트를 구성합니다. 이 방식은 단일 구성으로 모든 패키지 유형에 액세스할 수 있게 합니다:

<repositories>
    <repository>
        <id>gitlab-maven</id>
        <url>https://gitlab.example.com/api/v4/groups/artifact-management/-/packages/maven</url>
    </repository>
</repositories>

<settings>
    <servers>
        <server>
            <id>gitlab-maven</id>
            <username>deploy-token-username</username>
            <password>deploy-token-password</password>
        </server>
    </servers>
</settings>

@company:registry=https://gitlab.example.com/api/v4/groups/artifact-management/-/packages/npm/
//gitlab.example.com/api/v4/groups/artifact-management/-/packages/npm/:_authToken=${DEPLOY_TOKEN}

# pip.conf or ~/.pip/pip.conf
[global]
extra-index-url = https://deploy-token-username:deploy-token-password@gitlab.example.com/api/v4/groups/artifact-management/-/packages/pypi/simple/

pip install --index-url https://deploy-token-username:deploy-token-password@gitlab.example.com/api/v4/groups/artifact-management/-/packages/pypi/simple/ --no-index my-package

docker login gitlab.example.com -u deploy-token-username -p deploy-token-password
docker pull gitlab.example.com/artifact-management/docker-images/my-app:latest

export TF_TOKEN_gitlab_example_com="deploy-token-password"

module "example" {
  source = "gitlab.example.com/artifact-management/terraform-modules//my-module"
  version = "1.0.0"
}

module "example" {
  source = "https://gitlab.example.com/api/v4/projects/TERRAFORM_PACKAGES_PROJECT_ID/packages/terraform/modules/my-module/my-provider/1.0.0"
}

<!-- nuget.config -->
<configuration>
  <packageSources>
    <add key="GitLab" value="https://gitlab.example.com/api/v4/groups/artifact-management/-/packages/nuget/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <GitLab>
      <add key="Username" value="deploy-token-username" />
      <add key="ClearTextPassword" value="deploy-token-password" />
    </GitLab>
  </packageSourceCredentials>
</configuration>

curl --header "DEPLOY-TOKEN: ${DEPLOY_TOKEN}" "https://gitlab.example.com/api/v4/groups/artifact-management/-/packages/generic/my-package/1.0.0/my-package.zip" --output my-package.zip

CI/CD 구성 예제#

다음 예제는 프로젝트가 여러 패키지 유형의 패키지를 소비하는 방법을 보여 줍니다:

stages:
  - build
  - test

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=${CI_PROJECT_DIR}/.m2/repository"

before_script:
  # Configure npm registry
  - echo "@company:registry=${CI_API_V4_URL}/groups/artifact-management/-/packages/npm/" >> .npmrc
  - echo "//${CI_SERVER_HOST}/api/v4/groups/artifact-management/-/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc

build:
  stage: build
  script:
    # Install npm dependencies from group registry
    - npm install
    # Build with Maven dependencies from group registry
    - mvn compile
  cache:
    paths:
      - .m2/repository/
      - node_modules/

소스 코드와 함께 게시#

일부 조직은 엔터프라이즈 규모 튜토리얼에 설명된 대로 애플리케이션 소스 코드와 함께 패키지를 게시하는 방식을 선호합니다. 이 방식은 다음과 같은 경우에 잘 맞습니다:

• 패키지가 특정 애플리케이션과 밀접하게 결합되어 있는 경우.
• 패키지 소유권을 소스 코드 소유권과 일치시키려는 경우.
• 팀이 코드와 패키지를 함께 관리하는 경우.

아티팩트 관리 방식은 다음과 같은 경우에 더 잘 맞습니다:

• 패키지 거버넌스를 간소화하려는 경우.
• 패키지를 여러 프로젝트에서 공유하는 경우.
• 유형별 정책과 제어가 필요한 경우.
• 기존 아티팩트 리포지터리에서 마이그레이션하는 경우.

조직에서 가장 많이 쓰는 패키지 유형부터 시작하고, 패키지 형식을 추가로 도입하면서 구조를 확장합니다. 이 방식은 보안과 사용 편의성을 유지하면서 자연스럽게 확장됩니다.