パッケージレジストリ内のNuGetパッケージ

プロジェクトのパッケージレジストリにNuGetパッケージを公開します。すると、依存関係として使用する必要がある場合に、いつでもパッケージをインストールできるようになります。

パッケージレジストリは以下と連携します:

• NuGet CLI
• .NET Core CLI
• Visual Studio

これらのクライアントが使用する特定のAPIエンドポイントの詳細については、NuGet APIリファレンスを参照してください。

NuGetをインストールする方法を説明します。

パッケージレジストリに対して認証する

GitLabパッケージレジストリにアクセスするには、認証トークンが必要です。実現しようとしていることに応じて、さまざまなトークンを利用できます。詳細については、トークンに関するガイダンス参照してください。

• 組織で2要素認証（2FA）を使用している場合、スコープがapiに設定されたパーソナルアクセストークンを使用する必要があります。
• CI/CDパイプラインでパッケージを公開する場合は、プライベートRunnerでCI/CDジョブトークンを使用できます。インスタンスRunnerの変数を登録することもできます。

GitLabエンドポイントをNuGetパッケージに使用する

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

パッケージを削除する

前提要件:

• プロジェクトでメンテナー以上のロールを持っている必要があります。
• パッケージ名とバージョンの両方を持っている必要があります。

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. GraphiQLでnuget_symbol_server_enabledネームスペース設定nuget_symbol_server_enabledを有効にします。
2. シンボルサーバーを使用するようにデバッガーを設定します。

たとえば、Visual Studioをデバッガとして設定するには:

1. ツール > 設定を選択します。
2. Debugger（デバッガ） > Symbol sources（シンボルソース）を選択します。
3. 追加を選択します。
4. シンボルサーバーのURLを入力します。
5. Add Source（Add Source）を選択します。

デバッガーを設定したら、通常どおりにアプリケーションをデバッグできます。デバッガは、シンボル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

ローカルネットワークアドレスへのWebhookリクエストは、内部Webサービスの悪用を防ぐためにブロックされます。

これらのエラーを解決するには、ローカルネットワークへのWebhookおよびインテグレーションのリクエストを許可するようにネットワーク設定を変更します。