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

다음을 원할 때 이 접근 방식을 사용합니다:

• 전용 정책 및 설정으로 유형별로 패키지를 구성.
• 모든 조직 패키지에 대한 단일 소비 엔드포인트 제공.
• 서드파티 레지스트리에서 구조화된 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. 상단 표시줄에서 새로 만들기 (+)를 선택하고 새 그룹을 선택합니다.
2. 그룹 생성을 선택합니다.
3. 그룹 이름 텍스트 상자에 Artifact Management 또는 유사한 이름을 입력합니다.
4. 그룹 URL에서 생성된 경로를 유지합니다.
5. 그룹의 공개 수준을 선택합니다.
6. 그룹 생성을 선택합니다.

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

1. 상단 표시줄에서 검색 또는 이동을 선택하고 아티팩트 관리 그룹을 찾습니다.
2. 왼쪽 사이드바에서 새로 만들기 (+)를 선택하고 새 프로젝트/저장소를 선택합니다.
3. 빈 프로젝트 만들기를 선택합니다.
4. 원하는 패키지 유형에 대한 프로젝트 이름을 입력합니다. 예: java-packages 또는 node-packages.
5. 적절한 공개 수준을 설정합니다.
6. 프로젝트 생성을 선택합니다.

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

그룹 설정을 구성합니다:

1. 아티팩트 관리 그룹의 왼쪽 사이드바에서 설정 > 패키지 및 레지스트리를 선택합니다.
2. 중복 패키지 또는 패키지 전달과 같이 필요한 그룹 정책을 구성합니다.
3. 필요에 따라 그룹 접근 제어를 설정합니다.

인증 및 접근 구성#

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

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

• 개별 개발자를 위한 개인 액세스 토큰
• 공유 팀 자격 증명을 위한 그룹 액세스 토큰

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

• CI/CD 작업 토큰(선호) - 자동 인증
• 특별한 경우를 위한 프로젝트 액세스 토큰

외부 시스템의 경우:

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

최상위 그룹 접근 설정#

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

1. 아티팩트 관리 그룹의 왼쪽 사이드바에서 설정 > 저장소를 선택합니다.
2. 배포 토큰을 펼칩니다.
3. 토큰 추가를 선택하고 필드를 완성합니다:
   • 이름에 package-consumption을 입력합니다.
   • 범위에서 read_package_registry를 선택합니다.
4. 배포 토큰 생성을 선택합니다.

토큰을 안전하게 저장합니다.

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

1. 각 패키지별 프로젝트의 왼쪽 사이드바에서 설정 > CI/CD를 선택합니다.
2. 토큰 접근을 펼칩니다.
3. 이 패키지 레지스트리에 패키지를 게시할 수 있어야 하는 프로젝트를 추가합니다.

프로젝트 설정 구성#

각 패키지 유형 프로젝트에 대해 다음을 구성합니다:

• 해당 패키지 유형에 적합한 수명 주기 정책
• 필요한 경우 보호된 패키지 규칙
• 필요한 경우 보호된 컨테이너 태그 규칙
• 특정 사용 사례를 위한 프로젝트 액세스 토큰

패키지 게시#

팀은 적절한 유형별 프로젝트 레지스트리에 패키지를 게시해야 합니다. 지원되는 각 패키지 형식에 대한 다음 예제를 참조하세요.

<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 그룹에서 배포 > 가상 레지스트리로 이동합니다.
   • 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 작업 토큰을 포함한 여러 토큰 유형을 지원합니다. 각 토큰 유형은 서로 다른 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/

소스 코드와 함께 게시#

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

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

아티팩트 관리 접근 방식은 다음 경우에 더 잘 작동합니다:

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

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