프로젝트의 패키지 레지스트리에 NuGet 패키지를 게시합니다. 그런 다음 의존성으로 사용해야 할 때마다 그 패키지를 설치합니다.

패키지 레지스트리는 다음과 함께 동작합니다:

• NuGet CLI
• .NET Core CLI
• Visual Studio

이 클라이언트들이 사용하는 구체적인 API 엔드포인트는 NuGet API 참조를 참고합니다.

NuGet 설치 방법을 참고합니다.

패키지 레지스트리 인증#

GitLab 패키지 레지스트리에 액세스하려면 인증 토큰이 필요합니다. 목적에 따라 사용할 수 있는 토큰이 다릅니다. 자세한 내용은 토큰 가이드를 참고합니다.

• 조직에서 이중 인증(2FA)을 사용한다면 범위를 api로 설정한 개인 액세스 토큰을 사용해야 합니다.
• CI/CD 파이프라인으로 패키지를 게시한다면 비공개 러너와 함께 CI/CD job 토큰을 사용할 수 있습니다. 인스턴스 러너에는 변수를 등록할 수도 있습니다.

NuGet 패키지에 GitLab 엔드포인트 사용#

프로젝트 엔드포인트나 그룹 엔드포인트로 GitLab 패키지 레지스트리와 상호 작용할 수 있습니다:

• 프로젝트 엔드포인트: 같은 그룹에 없는 NuGet 패키지가 몇 개뿐일 때 사용합니다.
• 그룹 엔드포인트: 같은 그룹 아래 여러 프로젝트에 NuGet 패키지가 많을 때 사용합니다.

패키지 게시처럼 일부 작업은 프로젝트 엔드포인트에서만 사용할 수 있습니다.

NuGet이 자격 증명을 처리하는 방식 때문에, 패키지 레지스트리는 공개 그룹에 대한 익명 요청을 거부합니다.

NuGet 패키지의 소스로 패키지 레지스트리 추가#

패키지 레지스트리에 패키지를 게시하고 설치하려면, 패키지의 소스로 패키지 레지스트리를 추가해야 합니다.

사전 요구 사항:

• GitLab 사용자 이름
• 인증 토큰(다음 섹션에서는 개인 액세스 토큰을 가정합니다)
• 소스 이름
• 프로젝트 또는 그룹 ID

프로젝트 엔드포인트 사용#

nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/index.json" -UserName <gitlab_username> -Password <personal_access_token>

nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password <your_access_token>

dotnet nuget add source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/index.json" --name <source_name> --username <gitlab_username> --password <personal_access_token>

dotnet nuget add source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" --name gitlab --username carol --password <your_access_token> --store-password-in-clear-text

choco source add -n=<source_name> -s "'https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/v2'" -u=<gitlab_username> -p=<personal_access_token>

choco source add -n=gitlab -s "'https://gitlab.example.com/api/v4/projects/10/packages/nuget/v2'" -u=carol -p=<your_access_token>

그룹 엔드포인트 사용#

nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/nuget/index.json" -UserName <gitlab_username> -Password <personal_access_token>

nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" -UserName carol -Password <your_access_token>

dotnet nuget add source "https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/nuget/index.json" --name <source_name> --username <gitlab_username> --password <personal_access_token>

dotnet nuget add source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" --name gitlab --username carol --password <your_access_token> --store-password-in-clear-text

패키지 게시#

사전 요구 사항:

• 소스로 패키지 레지스트리를 설정합니다.
• NuGet 패키지용 GitLab 프로젝트 엔드포인트를 구성합니다.

패키지를 게시할 때 유의할 사항은 다음과 같습니다:

• GitLab 인스턴스의 최대 파일 크기 제한을 확인합니다:
  • GitLab.com 인스턴스의 패키지 레지스트리 제한은 파일 형식마다 다르고, 구성할 수 없습니다.
  • GitLab Self-Managed 인스턴스의 패키지 레지스트리 제한은 파일 형식마다 다르고, 구성할 수 있습니다.
• 중복이 허용된 상태에서 같은 버전의 같은 패키지를 여러 번 게시하면, 연속된 업로드가 각각 별도의 파일로 저장됩니다. 패키지를 설치할 때 GitLab은 가장 최근 파일을 제공합니다.
• 업로드된 패키지는 대부분 Package registry 페이지에 즉시 표시됩니다. 백그라운드에서 처리해야 하는 일부 패키지는 표시되기까지 최대 10분이 걸릴 수 있습니다.

NuGet CLI 사용#

사전 요구 사항:

• NuGet CLI로 만든 NuGet 패키지.

패키지를 게시하려면 다음 명령을 실행합니다:

nuget push <package_file> -Source <source_name>

교체:

• <package_file>을 .nupkg로 끝나는 패키지 파일 이름으로.
• <source_name>을 소스 이름으로.

예시:

nuget push MyPackage.1.0.0.nupkg -Source gitlab

.NET CLI 사용#

사전 요구 사항:

• .NET CLI로 만든 NuGet 패키지.

패키지를 게시하려면 다음 명령을 실행합니다:

dotnet nuget push <package_file> --source <source_name>

교체:

• <package_file>을 .nupkg로 끝나는 패키지 파일 이름으로.
• <source_name>을 소스 이름으로.

예시:

dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab

username과 password 대신 --api-key 옵션으로 패키지를 게시할 수 있습니다:

dotnet nuget push <package_file> --source <source_url> --api-key <personal_access_token>

교체:

• <package_file>을 .nupkg로 끝나는 패키지 파일 이름으로.
• <source_url>을 NuGet 패키지 레지스트리의 URL로.

예시:

dotnet nuget push MyPackage.1.0.0.nupkg --source https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/index.json --api-key <personal_access_token>

Chocolatey CLI 사용#

사전 요구 사항:

• 프로젝트 엔드포인트를 사용하는 소스.

Chocolatey CLI로 패키지를 게시하려면 다음 명령을 실행합니다:

choco push <package_file> --source <source_url> --api-key <gitlab_personal_access_token, deploy_token or job token>

교체:

• <package_file>을 .nupkg로 끝나는 패키지 파일 이름으로.
• <source_url>을 NuGet v2 피드 패키지 레지스트리의 URL로.

예시:

choco push MyPackage.1.0.0.nupkg --source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/v2" --api-key <personal_access_token>

CI/CD 파이프라인 사용#

GitLab CI/CD로 NuGet 패키지를 게시한다면 개인 액세스 토큰이나 배포 토큰 대신 CI_JOB_TOKEN 사전 정의 변수를 사용할 수 있습니다. job 토큰은 파이프라인을 생성하는 사용자 또는 멤버의 권한을 상속합니다.

다음 섹션의 예시는 CI/CD 파이프라인을 사용할 때 흔히 쓰이는 NuGet 게시 워크플로를 다룹니다.

기본 브랜치가 업데이트될 때 패키지 게시#

main 브랜치가 업데이트될 때마다 새 패키지를 게시하는 방법은 다음과 같습니다:

1. 프로젝트의 .gitlab-ci.yml 파일에 다음 deploy job을 추가합니다:

   default:
     # Updated to a more current SDK version
     image: mcr.microsoft.com/dotnet/sdk:7.0
   
   stages:
     - deploy
   
   deploy:
     stage: deploy
     script:
       # Build the package in Release configuration
       - dotnet pack -c Release
       # Configure GitLab package registry as a NuGet source
       - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
       # Push the package to the project's package registry
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # Only run on the main branch
     environment: production
   

2. 변경 사항을 커밋하고 GitLab 리포지터리에 푸시해 새 CI/CD 빌드를 트리거합니다.

Git 태그로 버전이 지정된 패키지 게시#

Git 태그로 버전이 지정된 NuGet 패키지를 게시하는 방법은 다음과 같습니다:

1. 프로젝트의 .gitlab-ci.yml 파일에 다음 deploy job을 추가합니다:

   publish-tagged-version:
     stage: deploy
     script:
       # Use the Git tag as the package version
       - dotnet pack -c Release /p:Version=${CI_COMMIT_TAG} /p:PackageVersion=${CI_COMMIT_TAG}
       # Configure GitLab package registry as a NuGet source
       - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
       # Push the package to the project's package registry
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_TAG  # Only run when a tag is pushed
   

2. 변경 사항을 커밋하고 GitLab 리포지터리에 푸시합니다.

3. Git 태그를 푸시해 새 CI/CD 빌드를 트리거합니다.

환경별 조건부 게시#

사용 사례에 따라 서로 다른 환경에 NuGet 패키지를 조건부로 게시하도록 CI/CD 파이프라인을 구성할 수 있습니다.

development 환경과 production 환경에 NuGet 패키지를 조건부로 게시하는 방법은 다음과 같습니다:

1. 프로젝트의 .gitlab-ci.yml 파일에 다음 deploy job들을 추가합니다:

     # Publish development/preview packages
   publish-dev:
     stage: deploy
     script:
       # Create a development version with pipeline ID for uniqueness
       - VERSION="0.0.1-dev.${CI_PIPELINE_IID}"
       - dotnet pack -c Release /p:Version=$VERSION /p:PackageVersion=$VERSION
       # Configure GitLab package registry as a NuGet source
       - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
       # Push the package to the project's package registry
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_BRANCH == "develop"
     environment: development
   
     # Publish stable release packages
   publish-release:
     stage: deploy
     script:
       - dotnet pack -c Release
       # Configure GitLab package registry as a NuGet source
       - dotnet nuget add source "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
       # Push the package to the project's package registry
       - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
     rules:
       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
     environment: production
   

2. 변경 사항을 커밋하고 GitLab 리포지터리에 푸시합니다.

   이 CI/CD 구성에서는 다음과 같이 동작합니다:

   • develop 브랜치에 NuGet 패키지를 푸시하면 development 환경의 패키지 레지스트리에 패키지가 게시됩니다.
   • main 브랜치에 NuGet 패키지를 푸시하면 production 환경의 패키지 레지스트리에 NuGet 패키지가 게시됩니다.

중복 NuGet 패키지 비활성화#

같은 이름과 같은 버전의 패키지를 여러 개 게시할 수 있습니다.

그룹 멤버와 사용자가 중복 NuGet 패키지를 게시하지 못하게 하려면 Allow duplicates 설정을 끕니다:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Packages and registries를 선택합니다.
3. Duplicate packages 표의 NuGet 행에서 Allow duplicates 토글을 끕니다.
4. 선택 사항. Exceptions 텍스트 상자에 허용할 패키지의 이름과 버전에 일치하는 정규 표현식을 입력합니다.

GraphQL API의 nuget_duplicates_allowed 설정으로도 중복 NuGet 패키지를 끌 수 있습니다.

패키지 설치#

GitLab 패키지 레지스트리에는 같은 이름과 같은 버전의 패키지가 여러 개 있을 수 있습니다. 중복된 패키지를 설치하면 가장 최근에 게시된 패키지를 가져옵니다.

사전 요구 사항:

• 소스로 패키지 레지스트리를 설정합니다.
• NuGet 패키지용 GitLab 엔드포인트를 구성합니다.

명령줄에서#

nuget install <package_id> -OutputDirectory <output_directory> \
  -Version <package_version> \
  -Source <source_name>

dotnet add package <package_id> \
       -v <package_version>

NuGet v2 피드 사용#

사전 요구 사항:

• Chocolatey용 v2 피드 소스.
• NuGet v2 피드로 패키지를 설치하거나 업그레이드할 때는 패키지 버전을 지정해야 합니다.

Chocolatey CLI로 패키지를 설치하는 방법은 다음과 같습니다:

choco install <package_id> -Source <source_url> -Version <package_version>

• <package_id>: 패키지 ID입니다.
• <source_url>: NuGet v2 피드 패키지 레지스트리의 URL 또는 이름입니다.
• <package_version>: 패키지 버전입니다.

예시:

choco install MyPackage -Source gitlab -Version 1.0.2

# or

choco install MyPackage -Source "https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/v2" -u <username> -p <personal_access_token> -Version 1.0.2

Chocolatey CLI로 패키지를 업그레이드하는 방법은 다음과 같습니다:

choco upgrade <package_id> -Source <source_url> -Version <package_version>

• <package_id>: 패키지 ID입니다.
• <source_url>: NuGet v2 피드 패키지 레지스트리의 URL 또는 이름입니다.
• <package_version>: 패키지 버전입니다.

예시:

choco upgrade MyPackage -Source gitlab -Version 1.0.3

패키지 삭제#

사전 요구 사항:

• 프로젝트에서 최소 Maintainer 권한이 있어야 합니다.
• 패키지 이름과 버전을 모두 알고 있어야 합니다.

NuGet CLI로 패키지를 삭제하는 방법은 다음과 같습니다:

nuget delete <package_id> <package_version> -Source <source_name> -ApiKey <personal_access_token>

• <package_id>: 패키지 ID입니다.
• <package_version>: 패키지 버전입니다.
• <source_name>: 소스 이름입니다.

예시:

nuget delete MyPackage 1.0.0 -Source gitlab -ApiKey <personal_access_token>

심볼 패키지#

GitLab은 NuGet 패키지 레지스트리의 심볼 파일을 사용할 수 있습니다. GitLab 패키지 레지스트리를 심볼 서버로 사용해 NuGet 패키지를 디버그할 수 있습니다.

NuGet 패키지 파일(.nupkg)을 게시할 때마다 심볼 패키지 파일(.snupkg)이 NuGet 패키지 레지스트리에 자동으로 업로드됩니다.

수동으로 푸시할 수도 있습니다:

nuget push My.Package.snupkg -Source <source_name>

심볼 파일에 GitLab 엔드포인트 사용#

GitLab 패키지 레지스트리는 프로젝트 엔드포인트나 그룹 엔드포인트와 함께 구성할 수 있는 특수 symbolfiles 엔드포인트를 제공합니다:

• 프로젝트 엔드포인트:

  https://gitlab.example.com/api/v4/projects/<project_id>/packages/nuget/symbolfiles
  

  • <project_id>를 프로젝트 ID로 교체합니다.

• 그룹 엔드포인트:

  https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/nuget/symbolfiles
  

  • <group_id>를 그룹 ID로 교체합니다.

symbolfiles 엔드포인트는 구성된 디버거가 심볼 파일을 푸시할 수 있는 소스입니다.

심볼 서버로 패키지 레지스트리 사용#

심볼 서버를 사용하는 방법은 다음과 같습니다:

1. GraphQL API로 nuget_symbol_server_enabled 네임스페이스 설정을 활성화합니다.
2. 심볼 서버를 사용하도록 디버거를 구성합니다.

예를 들어 Visual Studio를 디버거로 구성하는 방법은 다음과 같습니다:

1. Tools > Preferences를 선택합니다.
2. Debugger > Symbol sources를 선택합니다.
3. Add를 선택합니다.
4. 심볼 서버 URL을 입력합니다.
5. Add Source를 선택합니다.

디버거를 구성한 다음에는 애플리케이션을 평소처럼 디버그할 수 있습니다. 심볼 PDB 파일을 사용할 수 있으면 디버거가 패키지 레지스트리에서 자동으로 내려받습니다.

심볼 패키지 사용#

디버거가 심볼 패키지를 사용하도록 구성되면, 디버거는 요청에 다음 정보를 보냅니다:

• Symbolchecksum 헤더: 심볼 파일의 SHA-256 체크섬입니다.
• file_name 요청 파라미터: 심볼 파일의 이름입니다. 예를 들어 mypackage.pdb입니다.
• signature 요청 파라미터: PDB 파일의 GUID와 age입니다.

GitLab 서버는 이 정보를 심볼 파일과 대조해 해당 파일을 반환합니다.

다음 사항에 유의합니다:

• 이식 가능한 PDB 파일만 지원됩니다.
• 디버거는 인증 토큰을 제공할 수 없으므로, 심볼 서버 엔드포인트는 일반적인 인증 방법을 지원하지 않습니다. GitLab 서버는 올바른 심볼 파일을 반환하기 위해 signature와 Symbolchecksum이 필요합니다.

지원되는 CLI 명령#

GitLab NuGet 리포지터리는 NuGet CLI(nuget)와 .NET CLI(dotnet)에서 다음 명령을 지원합니다:

문제 해결#

NuGet 패키지로 작업할 때 다음과 같은 문제가 발생할 수 있습니다.

NuGet 캐시 지우기#

성능을 높이기 위해 NuGet은 패키지 파일을 캐시합니다. 스토리지 문제가 발생하면 다음 명령으로 캐시를 지웁니다:

nuget locals all -clear

Docker 기반 GitLab 설치에서 NuGet 패키지 게시 시 오류#

NuGet 패키지를 게시할 때 다음과 같은 오류 메시지가 표시될 수 있습니다:

• Error publishing
• Invalid Package: Failed metadata extraction error

내부 웹 서비스가 악용되는 것을 방지하기 위해 로컬 네트워크 주소로 향하는 웹훅 요청은 차단됩니다.

이 오류를 해결하려면 웹훅과 통합에서 로컬 네트워크로의 요청을 허용하도록 네트워크 설정을 변경합니다.