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

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

• NuGet CLI
• .NET Core CLI
• Visual Studio

이 클라이언트가 사용하는 특정 API 엔드포인트에 대해서는 NuGet API 참조를 참조하세요.

NuGet 설치 방법에 대해 알아보세요.

패키지 레지스트리 인증#

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

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

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은 가장 최근 파일을 제공합니다.
• 업로드된 대부분의 패키지는 패키지 레지스트리 페이지에 즉시 표시되어야 합니다. 일부 패키지는 백그라운드에서 처리해야 하는 경우 최대 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 사전 정의 변수를 사용할 수 있습니다. 작업 토큰은 파이프라인을 생성하는 사용자 또는 멤버의 권한을 상속합니다.

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

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

main 브랜치가 업데이트될 때마다 새 패키지를 게시하려면:

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

   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 작업을 추가합니다:

   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. 새 CI/CD 빌드를 트리거하려면 Git 태그를 푸시합니다.

다른 환경에 대한 조건부 게시#

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

development 및 production 환경에 대해 조건부로 NuGet 패키지를 게시하려면:

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

     # 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 패키지를 게시하지 못하도록 중복 허용 설정을 끕니다:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 패키지 및 레지스트리를 선택합니다.
3. 중복 패키지 테이블의 NuGet 행에서 중복 허용 토글을 끕니다.
4. 선택 사항. 예외 텍스트 상자에 허용할 패키지의 이름과 버전과 일치하는 정규 표현식을 입력합니다.

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. 도구 > 환경 설정을 선택합니다.
2. 디버거 > 심볼 소스를 선택합니다.
3. 추가를 선택합니다.
4. 심볼 서버 URL을 입력합니다.
5. 소스 추가를 선택합니다.

디버거를 구성한 후 평소대로 애플리케이션을 디버그할 수 있습니다. 디버거는 가능한 경우 패키지 레지스트리에서 심볼 PDB 파일을 자동으로 다운로드합니다.

심볼 패키지 사용#

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

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

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

내부 웹 서비스 악용을 방지하기 위해 로컬 네트워크 주소에 대한 웹훅 요청이 차단됩니다.

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