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

プロジェクトのパッケージレジストリでNuGetパッケージを公開します。そして、依存関係として使用する必要があるときはいつでもパッケージをインストールしてください。

パッケージ・レジストリは次のように動作します：

これらのクライアントが使用する特定の API エンドポイントのドキュメントについては、NuGet API ドキュメントを参照してください。

NuGetのインストール方法をご覧ください。

NuGetパッケージのGitLabエンドポイントを使用します。

GitLab 13.8 でグループレベルのエンドポイントを導入しました。

NuGetパッケージにGitLabエンドポイントを使用するには、オプションを選択してください：

  • プロジェクトレベル：NuGetパッケージが少なく、それらが同じGitLabグループにない場合に使用します。
  • グループレベル：同じGitLabグループ内の異なるプロジェクトに多くのNuGetパッケージがある場合に使用します。

パッケージの公開など、いくつかの機能はプロジェクトレベルのエンドポイントでのみ利用できます。

指定されたNuGetパッケージ名のバージョンを問い合わせると、GitLabパッケージレジストリは最大300の最新バージョンを返します。

ここで説明されている以外の認証方法は使用しないでください。文書化されていない認証方法は、将来削除される可能性があります。

caution
NuGet が認証情報を処理する方法のため、パッケージレジストリはグループレベルのエンドポイントでの匿名リクエストを拒否します。この制限を回避するには、認証を設定してください。

NuGet パッケージのソースとしてパッケージレジストリを追加します。

パッケージ・レジストリにパッケージを公開してインストールするには、パッケージ・レジストリをパッケージのソースとして追加する必要があります。

前提条件：

  • GitLab ユーザー名。
  • 個人アクセストークンまたはデプロイトークン。リポジトリ認証用：
  • ソースの名前。
  • 使用するエンドポイント・レベルに応じて、以下のいずれかを指定します：
    • プロジェクトのホームページにあるプロジェクトID。
    • あなたのグループIDは、あなたのグループのホームページにあります。

これでNuGetに新しいソースを追加できます：

NuGet CLIを使ったソースの追加

プロジェクトレベルのエンドポイント

NuGetパッケージをパッケージレジストリに公開するには、プロジェクトレベルのエンドポイントが必要です。プロジェクトから NuGet パッケージをインストールするには、プロジェクトレベルのエンドポイントも必要です。

プロジェクトレベルのNuGet エンドポイントを使用するには、nugetでパッケージ・レジストリをソースとして追加します：

nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token>
  • <source_name> は必要なソース名です。

使用例：

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

グループ・レベルのエンドポイント

グループからNuGetパッケージをインストールするには、グループレベルのエンドポイントを使用します。

グループレベルのNuGet エンドポイントを使用するには、パッケージ・レジストリをソースとしてnuget：

nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token>
  • <source_name> は必要なソース名です。

使用例：

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

Visual Studioでソースを追加

プロジェクトレベルのエンドポイント

NuGetパッケージをパッケージレジストリに公開するには、プロジェクトレベルのエンドポイントが必要です。プロジェクトから NuGet パッケージをインストールするには、プロジェクトレベルのエンドポイントも必要です。

プロジェクトレベルの NuGet エンドポイントを使用するには、Visual Studio でパッケージ・レジストリをソースとして追加します：

  1. Visual Studioを開きます。
  2. Windows では、[ツール] > [オプション] を選択します。MacOSでは、Visual Studio > Preferencesを選択します。
  3. NuGet]セクションで、[Sources] を選択してすべての NuGet ソースのリストを表示します。
  4. Add（追加）を選択します。

  5. 以下のフィールドを入力します：

    • 名前：ソースの名前。
    • ソース：https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json<your_project_id> はプロジェクトID、gitlab.example.com はドメイン名です。
  6. Save を選択します。

  7. パッケージにアクセスする際、ユーザー名と パスワードを入力する必要があります：

    • ユーザー名：GitLabユーザー名またはデプロイトークンユーザー名。
    • パスワード：あなたの個人アクセストークンまたはデプロイトークン。

ソースがリストに表示されます。

警告が表示された場合は、ソース、ユーザー名、パスワードが正しいことを確認してください。

グループ・レベルのエンドポイント

グループからパッケージをインストールするには、グループレベルのエンドポイントを使用します。

グループレベルのNuGet エンドポイントを使用するには、Visual Studio でパッケージ・レジストリをソースとして追加します：

  1. Visual Studioを開きます。
  2. Windows では、[ツール] > [オプション] を選択します。MacOSでは、Visual Studio > Preferencesを選択します。
  3. NuGet]セクションで、[Sources] を選択してすべての NuGet ソースのリストを表示します。
  4. Add（追加）を選択します。

  5. 以下のフィールドを入力します：

    • 名前：ソースの名前。
    • ソース：https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json<your_group_id> はグループID、gitlab.example.com はドメイン名です。
  6. Save を選択します。

  7. パッケージにアクセスする際、ユーザー名と パスワードを入力する必要があります。

    • ユーザー名：GitLabユーザー名またはデプロイトークンユーザー名。
    • パスワード：あなたの個人アクセストークンまたはデプロイトークン。

ソースがリストに表示されます。

警告が表示された場合は、ソース、ユーザー名、パスワードが正しいことを確認してください。

.NET CLI を使用したソースの追加

プロジェクトレベルのエンドポイント

NuGetパッケージをパッケージレジストリに公開するには、プロジェクトレベルのエンドポイントが必要です。プロジェクトから NuGet パッケージをインストールするには、プロジェクトレベルのエンドポイントも必要です。

プロジェクトレベルのNuGet エンドポイントを使用するには、nugetでパッケージ・レジストリをソースとして追加します：

dotnet nuget add source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token>
  • <source_name> は必要なソース名です。
  • --store-password-in-clear-text お使いのオペレーション・システムによっては必要な場合があります。

使用例：

dotnet nuget add source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" --name gitlab --username carol --password 12345678asdf

グループ・レベルのエンドポイント

グループからNuGetパッケージをインストールするには、グループレベルのエンドポイントを使用します。

グループレベルのNuGet エンドポイントを使用するには、パッケージ・レジストリをソースとしてnuget：

dotnet nuget add source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token>
  • <source_name> は必要なソース名です。
  • --store-password-in-clear-text お使いのオペレーション・システムによっては必要な場合があります。

使用例：

dotnet nuget add source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" --name gitlab --username carol --password 12345678asdf

設定ファイルを持つソースの追加

プロジェクトレベルのエンドポイント

プロジェクトレベルのエンドポイントは、以下のことを行うために必要です：

  • NuGet パッケージをパッケージ・レジストリに公開します。
  • プロジェクトからNuGetパッケージをインストールします。

.NETのソースとしてプロジェクトレベルのパッケージレジストリを使用するには：

  1. プロジェクトのルートに、nuget.config.

  2. 次の内容を追加します：

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
 <packageSources>
     <clear />
     <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" />
 </packageSources>
 <packageSourceCredentials>
     <gitlab>
         <add key="Username" value="%GITLAB_PACKAGE_REGISTRY_USERNAME%" />
         <add key="ClearTextPassword" value="%GITLAB_PACKAGE_REGISTRY_PASSWORD%" />
     </gitlab>
 </packageSourceCredentials>
</configuration>

  3. 必要な環境変数を設定します：

    export GITLAB_PACKAGE_REGISTRY_USERNAME=<gitlab_username or deploy_token_username>
export GITLAB_PACKAGE_REGISTRY_PASSWORD=<gitlab_personal_access_token or deploy_token>

グループ・レベルのエンドポイント

グループからパッケージをインストールするには、グループレベルのエンドポイントを使用します。

.NETのソースとしてグループレベルのパッケージレジストリを使用するには、グループレベルのエンドポイントを使用します：

  1. プロジェクトのルートに、nuget.config.

  2. 次の内容を追加します：

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
 <packageSources>
     <clear />
     <add key="gitlab" value="https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" />
 </packageSources>
 <packageSourceCredentials>
     <gitlab>
         <add key="Username" value="%GITLAB_PACKAGE_REGISTRY_USERNAME%" />
         <add key="ClearTextPassword" value="%GITLAB_PACKAGE_REGISTRY_PASSWORD%" />
     </gitlab>
 </packageSourceCredentials>
</configuration>

  3. 必要な環境変数を設定します：

    export GITLAB_PACKAGE_REGISTRY_USERNAME=<gitlab_username or deploy_token_username>
export GITLAB_PACKAGE_REGISTRY_PASSWORD=<gitlab_personal_access_token or deploy_token>

Chocolatey CLIでソースを追加

Chocolatey CLIでソースフィードを追加できます。Chocolatey CLI v1.xを使用している場合は、NuGet v2のソースフィードのみを追加できます。

プロジェクトレベルのエンドポイントの設定

NuGet パッケージをパッケージ・レジストリに公開するには、プロジェクト・レベルのエンドポイントが必要です。

Chocolateyのソースとしてプロジェクトレベルのパッケージレジストリを使用するには、次のようにします：

  • choco でパッケージレジストリをソースとして追加します：

     choco source add -n=gitlab -s "'https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/v2'" -u=<gitlab_username or deploy_token_username> -p=<gitlab_personal_access_token or deploy_token>

NuGetパッケージの公開

前提条件

パッケージを公開する場合

  • GitLab.comのパッケージレジストリには5GBまでのコンテンツを保存できます。この制限は、セルフマネージドGitLabインスタンスに対して設定可能です。
  • 同じパッケージを同じバージョンで複数回公開する場合、連続したアップロードはそれぞれ別のファイルとして保存されます。パッケージをインストールする際、GitLabは最新のファイルを提供します。
  • GitLab にパッケージを公開しても、プロジェクトのパッケージユーザーインターフェイスにはすぐに表示されません。パッケージの処理には最大10分かかることがあります。

NuGet CLI を使ったパッケージの公開

前提条件：

このコマンドを実行してパッケージを発行します：

nuget push <package_file> -Source <source_name>

.NET CLIを使用したパッケージの発行

GitLab 16.1 で導入された --api-key を使ったパッケージの公開。

前提条件：

このコマンドを実行してパッケージを発行します：

dotnet nuget push <package_file> --source <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 <gitlab_personal_access_token, deploy_token or job token>
  • <package_file> はパッケージのファイル名で、.nupkg で内部終了します。
  • <source_url> はNuGetパッケージレジストリのURLです。

使用例：

dotnet nuget push MyPackage.1.0.0.nupkg --source https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json --api-key <gitlab_personal_access_token, deploy_token or job token>

CI/CDを使用したNuGetパッケージの発行

GitLab 13.3 で導入されました。

GitLab CI/CDでNuGetを使っている場合、個人アクセストークンやデプロイトークンの代わりにCIジョブトークンを使うことができます。トークンはパイプラインを生成するユーザーの権限を継承します。

この例では、main ブランチが更新されるたびに新しいパッケージを作成する方法を示しています：

  1. .gitlab-ci.yml ファイルにdeploy ジョブを追加してください：

    image: mcr.microsoft.com/dotnet/core/sdk:3.1
   
stages:
  - deploy
   
deploy:
  stage: deploy
  script:
    - dotnet pack -c Release
    - 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
    - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
  only:
    - main
  environment: production

  2. 変更をコミットしてGitLabリポジトリにプッシュし、新しいCI/CDビルドをトリガーします。

Chocolatey CLI で NuGet パッケージを発行します。

GitLab 16.2 で導入されました。

前提条件

  • プロジェクトレベルのパッケージレジストリはChocolateyのソースです。

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/<your_project_id>/packages/nuget/v2" --api-key <gitlab_personal_access_token, deploy_token or job token>

同じ名前またはバージョンのパッケージの公開

既存のパッケージと同じ名前やバージョンのパッケージを公開すると、既存のパッケージは上書きされます。

NuGet パッケージの重複を許可しないようにします。

GitLab 16.3 でnuget_duplicates_option というフラグで導入されました。デフォルトでは無効です。

フラグ: セルフマネジメントのGitLabでは、デフォルトではこの機能は利用できません。利用可能にするには、管理者がnuget_duplicates_optionという機能フラグを有効にします。この機能はまだ本番環境では使用できません。

ユーザーが重複したNuGetパッケージを公開しないようにするには、GraphQl APIを使用します。

caution
.nuspec ファイルがパッケージのルートに配置されていない場合、パッケージは重複として認識されない可能性があります。

パッケージのインストール

複数のパッケージが同じ名前とバージョンである場合、パッケージをインストールすると、最近公開されたパッケージが取得されます。

パッケージ・レジストリから NuGet パッケージをインストールするには、最初にプロジェクト・レベルまたはグループ・レベルのエンドポイントを追加する必要があります。

NuGet CLI を使用してパッケージをインストールします。

caution
デフォルトでは、nuget はnuget.org 最初に nuget.org公式ソースをチェックします。のnuget.org パッケージと同じ名前のNuGetパッケージがパッケージ・レジストリにある場合 nuget.org、正しいパッケージをインストールするにはソース名を指定する必要があります。

このコマンドを実行して、最新バージョンのパッケージをインストールします：

nuget install <package_id> -OutputDirectory <output_directory> \
  -Version <package_version> \
  -Source <source_name>
  • <package_id> はパッケージIDです。
  • <output_directory> はパッケージがインストールされている出力ディレクトリです。
  • <package_version> パッケージのバージョン。オプション。
  • <source_name> ソース名。オプション。

.NET CLIを使用したパッケージのインストール

caution
パッケージレジストリに別のソースのパッケージと同じ名前のパッケージがある場合、インストール中にdotnet がソースをチェックする順序を確認してください。これはnuget.config ファイルで定義されています。

このコマンドを実行して、最新バージョンのパッケージをインストールします：

dotnet add package <package_id> \
       -v <package_version>
  • <package_id> はパッケージIDです。
  • <package_version> はパッケージのバージョンです。オプション。

シンボルパッケージ

GitLab 14.1 で導入されました。

.nupkg をプッシュすると、.snupkg フォーマットのシンボルパッケージファイルが自動的にアップロードされます。手動でプッシュすることもできます：

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

Visual Studio や dotnet-symbol などのクライアントを使ったシンボルパッケージの消費はまだ保証されていません。.snupkg ファイルは UI またはAPI からダウンロードできます。

さらなるアップデートについてはNuGetシンボルパッケージのイシューに従ってください。

サポートされているCLIコマンド

GitLab NuGetリポジトリは、NuGet CLI (nuget) と .NET CLI (dotnet) の以下のコマンドをサポートしています：

  • nuget push:レジストリにパッケージをアップロード。
  • dotnet nuget push:レジストリにパッケージをアップロード。
  • nuget install:レジストリからパッケージをインストール。
  • dotnet add:レジストリからパッケージをインストール。

プロジェクトの例

例としては、Guided Exploration プロジェクトのUtterly Automated Software and Artifact Versioning with GitVersion をご覧ください。このプロジェクト

  • msbuild メソッドで NuGet パッケージを生成します。
  • nuget.exe メソッドで NuGet パッケージを生成します。
  • NuGetパッケージに関連してGitLabリリースとrelease-cli 。
  • GitVersionというツールを使用して、複雑なリポジトリ内のNuGetパッケージのバージョンを自動的に決定し、インクリメントします。

このサンプルプロジェクトを自分のグループやインスタンスにコピーしてテストすることができます。他にどのようなGitLab CIパターンが実証されているかについては、プロジェクトのページを参照してください。

トラブルシューティング

NuGetキャッシュのクリア

パフォーマンスを向上させるために、NuGetはパッケージに関連するファイルをキャッシュします。イシューが発生した場合は、このコマンドでキャッシュをクリアします：

nuget locals all -clear

Error publishing または、DockerベースのGitLabインストールでNuGetパッケージを公開しようとすると、Invalid Package: Failed metadata extraction error メッセージが表示されます。

内部 Web サービスの悪用を防ぐため、ローカルネットワークアドレスへの Webhook リクエストはブロックされています。NuGet パッケージを公開しようとしたときにError publishing またはInvalid Package メッセージが表示される場合は、ローカルネットワークへの Webhook リクエストとインテグレーションリクエストを許可するようにネットワーク設定を変更してください。