NuGetレジストリの利用

dotnetに NuGet パッケージを発行し、.NET プロジェクトの依存関係としてGitHub Packagesに格納されているパッケージを使用するように、GitHub Packagesコマンド ライン インターフェイス (CLI) を構成できます。

この機能を使用できるユーザーについて

Enterprise Managed Users は、組織の名前空間に発行できます。 個人用ストレージの割り当てがないため、これらのユーザーは自分のアカウントの名前空間にパッケージを公開できません。 Enterprise Managed Usersの詳細については、「Enterprise Managed Users の概要」を参照してください。

この記事で

NuGet レジストリの URL

GitHubでGitHub.comにアクセスする場合は、https://nuget.pkg.github.comにパッケージを発行します。 この記事の例では、この URL を使用しています。

GitHubなど、別のドメインoctocorp.ghe.comにアクセスする場合は、"https://nuget.pkg.github.com" をhttps://nuget.SUBDOMAIN.ghe.comに置き換えます。ここで、SUBDOMAINは企業の一意のサブドメインです。

GitHub Packages に認証を行う

メモ

GitHub Packages では、 personal access token (classic)を使用した認証のみがサポートされます。 詳しくは、「個人用アクセス トークンを管理する」をご覧ください。

非公開パッケージ、内部パッケージ、公開パッケージを発行、インストール、削除するには、アクセス トークンが必要です。

personal access token (classic)、あるいは GitHub Packages API で認証を受けるのに、GitHub を利用できます。 personal access token (classic) を作成するときは、必要に応じてさまざまなスコープをトークンに割り当てることができます。 personal access token (classic) のパッケージ関連のスコープについては、「GitHub Packagesの権限について」を参照してください。

GitHub Packagesワークフロー内でGitHub Actionsレジストリに認証を受けるには、以下の方法が使えます。

  • GITHUB_TOKEN では、ワークフロー リポジトリに関連付けられているパッケージを発行します。
  • 他のプライベート リポジトリに関連付けられたパッケージをインストールするために、少なくとも read:packages スコープが設定された personal access token (classic) (リポジトリにパッケージへの読み取りアクセス権が付与されている場合は、GITHUB_TOKEN を使用できます)。 「パッケージのアクセス制御と可視性の設定」を参照してください)。

GitHub Actions ワークフローでの認証

このレジストリでは、詳細なアクセス許可がサポートされています。 詳細なアクセス許可をサポートするレジストリの場合、 GitHub Actions ワークフローがレジストリに対する認証に personal access token を使用している場合は、 GITHUB_TOKENを使用するようにワークフローを更新することを強くお勧めします。 personal access tokenを使用してレジストリに対して認証を行うワークフローの更新に関するガイダンスについては、GitHub Actionsでのパッケージの公開とインストール を参照してください。

メモ

REST API を使ってパッケージを削除および復元する GitHub Actions ワークフローの機能は、現在 パブリック プレビュー 段階であり、変更される可能性があります。

トークンにパッケージへのアクセス許可がGITHUB_TOKENされている場合は、GitHub Actions ワークフローのadminを使用して、REST API を使用してパッケージを削除または復元できます。 ワークフローを使ってパッケージを発行するリポジトリと、パッケージに明示的に接続したリポジトリには、リポジトリ内のパッケージに対する admin アクセス許可が自動的に付与されます。

GITHUB_TOKEN の詳細については、「ワークフローでの認証に GITHUB_TOKEN を使用する」を参照してください。 アクションでレジストリを使うときのベスト プラクティスについて詳しくは、「危険にさらされたランナー」をご覧ください。

GitHub Packages ワークフローで GitHub Actions に認証するには、リポジトリ内の nuget.config ファイルに personal access token をハードコーディングする代わりに、GITHUB_TOKEN を使用して次のコマンドを実行します。

dotnet nuget add source --username USERNAME --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "https://nuget.pkg.github.com/NAMESPACE/index.json"

NAMESPACE を、パッケージのスコープ先であり、個人アカウントまたは組織の名前に置き換えてください。

USERNAME を認証済みソースに接続するときに使用されるユーザー名で置き換えます。

また、GitHub Codespaces と GitHub Actions に対して、パッケージにアクセス許可を個別に付与することもできます。 詳細については、「パッケージのアクセス制御と可視性の設定」および「パッケージのアクセス制御と可視性の設定」を参照してください。

personal access tokenを使用した認証の実行

メモ

GitHub Packages では、 personal access token (classic)を使用した認証のみがサポートされます。 詳しくは、「個人用アクセス トークンを管理する」をご覧ください。

非公開パッケージ、内部パッケージ、公開パッケージを発行、インストール、削除するには、アクセス トークンが必要です。

personal access token (classic)、あるいは GitHub Packages API で認証を受けるのに、GitHub を利用できます。 personal access token (classic) を作成するときは、必要に応じてさまざまなスコープをトークンに割り当てることができます。 personal access token (classic) のパッケージ関連のスコープについては、「GitHub Packagesの権限について」を参照してください。

GitHub Packagesワークフロー内でGitHub Actionsレジストリに認証を受けるには、以下の方法が使えます。

  • GITHUB_TOKEN では、ワークフロー リポジトリに関連付けられているパッケージを発行します。
  • 他のプライベート リポジトリに関連付けられたパッケージをインストールするために、少なくとも read:packages スコープが設定された personal access token (classic) (リポジトリにパッケージへの読み取りアクセス権が付与されている場合は、GITHUB_TOKEN を使用できます)。 「パッケージのアクセス制御と可視性の設定」を参照してください)。

personal access token (classic) でパッケージを発行およびインストールするには、適切なスコープで GitHub Packages を使う必要があります。 詳しくは、「GitHub Packages の概要」をご覧ください。

dotnet コマンドライン インターフェイス (CLI) を使用して GitHub Packages に認証するには、プロジェクト ディレクトリに nuget.config ファイルを作成し、dotnet CLI クライアントの packageSources の下で、GitHub Packages をソースとして指定します。

以下のように置き換えてください。

  • USERNAME GitHubの個人用アカウントの名前を指定します。
  • TOKEN を personal access token (classic)します。
  • NAMESPACEパッケージのスコープ先となっている個人アカウントまたは組織の名前で、。
<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://nuget.pkg.github.com/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

パッケージの公開

メモ

NuGet パッケージ バージョンの nupkg アーカイブのサイズは、2.147 GB 未満である必要があります。

パッケージをGitHub Packagesに発行するには、nuget.configファイルを使用して認証するか、GitHubでpersonal access token (classic)コマンド ライン オプションを使用するか、dotnetコマンド ライン インターフェイス (CLI) を使用してコマンド ラインから直接実行できるコマンドを使用します。

OWNERをユーザー名または会社名に置き換え、YOUR_GITHUB_PATをpersonal access tokenに置き換えます。

dotnet nuget add source --username OWNER --password YOUR_GITHUB_PAT --store-password-in-clear-text --name github "https://nuget.pkg.github.com/OWNER/index.json"

NuGet レジストリを使用すると、Organization または個人のアカウント内にパッケージを格納し、パッケージをリポジトリに関連付けることができます。 権限をリポジトリから継承するか、リポジトリとは別に細かい権限を設定するかを選ぶことができます。

パッケージを最初に公開する際のデフォルトの可視性はプライベートです。 可視性の変更やアクセス許可の設定については、「パッケージのアクセス制御と可視性の設定」を参照してください。 発行済みパッケージとリポジトリのリンクの詳細については、 リポジトリのパッケージへの接続 を参照してください。

projectの RepositoryURL ファイルで __ を指定すると、発行されたパッケージは指定されたリポジトリに自動的に接続されます。 詳細については、「NuGetレジストリの利用」を参照してください。 既に公開されているパッケージをリポジトリにリンクする方法については、リポジトリのパッケージへの接続 を参照してください。

GitHub personal access tokenを API キーとして使用してパッケージを発行する

personal access token のアカウントで使用する GitHub をまだお持ちでない場合は、「個人用アクセス トークンを管理する」を参照してください。

  1. 新しいprojectを作成します。 PROJECT_NAME を、projectに付ける名前に置き換えます。

    dotnet new console --name PROJECT_NAME

  2. projectをパッケージ化します。

    dotnet pack --configuration Release

  3. personal access tokenを API キーとして使用してパッケージを発行します。 PROJECT_NAMEをプロジェクト名に、1.0.0をパッケージのバージョン番号に、YOUR_GITHUB_PATをお使いのpersonal access tokenに置き換えます。

    dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --api-key YOUR_GITHUB_PAT --source "github"

パッケージを公開した後は、GitHub上でそのパッケージを見ることができます。 詳しくは、「パッケージの表示」をご覧ください。

nuget.config ファイルを使用してパッケージを公開する

発行時にパッケージをリポジトリにリンクする場合はOWNER ファイルで指定されたリポジトリの__ が、NAMESPACE 認証ファイルで使用する__ と一致している必要があります。 .csproj ファイルでバージョン番号を指定もしくはインクリメントし、dotnet pack コマンドを使用してそのバージョンのための .nuspec ファイルを作成してください。 パッケージの作成の詳細については、Microsoft ドキュメントの「パッケージの作成と公開」を参照してください。

メモ

リポジトリにリンクされているパッケージを公開した場合、organization でアクセス許可の自動継承が無効にされていない限り、パッケージはリンクされたリポジトリのアクセス許可を自動的に継承し、リンクされたリポジトリ内の GitHub Actions ワークフローは自動的にパッケージにアクセスできるようになります。 詳しくは、「パッケージのアクセス制御と可視性の設定」をご覧ください。

  1. GitHub Packagesに認証を受けてください。 詳しくは、「GitHub Packages への認証」をご覧ください。

  2. 新しいprojectを作成します。 PROJECT_NAME を、projectに付ける名前に置き換えます。

    dotnet new console --name PROJECT_NAME

  3. あなたのプロジェクトの特定の情報を、末尾が _.csproj_で終わるプロジェクトファイルに追加します。 必ず次のように置き換えてください。

    • 1.0.0 をパッケージのバージョン番号に。
    • OWNER パッケージをリンクする先のリポジトリを所有する個人アカウントまたは組織の名前を指定して
    • REPOSITORY パッケージを接続するリポジトリの名前を指定します。
    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>PROJECT_NAME</PackageId>
    <Version>1.0.0</Version>
    <Authors>AUTHORS</Authors>
    <Company>COMPANY_NAME</Company>
    <PackageDescription>PACKAGE_DESCRIPTION</PackageDescription>
    <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

  4. projectをパッケージ化します。

    dotnet pack --configuration Release

  5. 指定した key を nuget.config ファイルで使用してパッケージを公開します。 PROJECT_NAMEをprojectの名前に置き換え、1.0.0 をパッケージのバージョン番号に置き換えます。

    dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --source "github"

パッケージを公開した後は、GitHub上でそのパッケージを見ることができます。 詳しくは、「パッケージの表示」をご覧ください。

同じリポジトリへの複数パッケージの公開

複数のパッケージを同じリポジトリに接続するには、すべての GitHub プロジェクト ファイルの RepositoryURL フィールドで同じ__ リポジトリ URL を使用します。 GitHub は、そのフィールドに基づいてリポジトリと一致します。

次の例では、プロジェクト MY_APP とプロジェクト MY_OTHER_APP が同じリポジトリに公開されます。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a singing Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>MY_OTHER_APP</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds a dancing Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

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

プロジェクトで GitHub のパッケージを使用することは、 nuget.org のパッケージの使用と似ています。パッケージ名とバージョンを指定して、パッケージの依存関係を .csproj ファイルに追加します。 projectで .csproj ファイルを使用する方法の詳細については、Microsoft ドキュメントの「Working with NuGet packages」を参照してください。

  1. GitHub Packagesに認証を受けてください。 詳しくは、「GitHub Packages への認証」をご覧ください。

  2. パッケージを使用するには、ItemGroup を追加し、PackageReference project ファイルの __ フィールドを構成します。 PACKAGE_NAME の Include="PACKAGE_NAME" 値をパッケージ依存関係に置き換え、X.X.X の Version="X.X.X" 値を、使うパッケージのバージョンに置き換えます。

    <Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>My-app</PackageId>
    <Version>1.0.0</Version>
   <Authors>Octocat</Authors>
    <Company>GitHub</Company>
   <PackageDescription>This package adds an Octocat!</PackageDescription>
    <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PACKAGE_NAME" Version="X.X.X" />
  </ItemGroup>

</Project>

  3. restore コマンドを使用してパッケージをインストールします。

    dotnet restore

トラブルシューティング

GITHUB_TOKENを使用してGitHub Packages ワークフロー内のGitHub Actions レジストリに対する認証を行う場合、トークンは、ワークフローが実行されている場所以外の別のリポジトリ内のプライベート リポジトリ ベースのパッケージにアクセスできません。 他のリポジトリに関連付けられているパッケージにアクセスするには、代わりにpersonal access token (classic) スコープを持つread:packagesを生成し、このトークンをシークレットとして渡します。

パブリック パッケージを復元するときの断続的な 403 エラー

_ GitHub Packagesを nuget.org_ と共に使用していて、標準のパブリック パッケージ (Microsoft.Extensions.* など) を復元するときに断続的な 403 Forbidden エラーが発生する場合は、NuGet がすべてのパッケージに対して構成されているすべてのパッケージ ソースに対してクエリを実行するためです。 GitHub Packages認証が一時的に失敗すると、GitHub Packagesに存在しないパッケージであっても、復元全体がブロックされる可能性があります。

これを回避するには、 NuGet パッケージ ソース マッピング を使用して、パッケージを特定のソースにルーティングします。

置換前のコード:

  • NAMESPACE GitHub Packages NuGet フィードを所有する個人アカウントまたは組織の名前を指定します。
  • PACKAGE-ID-PREFIX には、 GitHub Packagesでホストされているパッケージに使用する NuGet パッケージ ID プレフィックスが付いています。 複数のプレフィックスを使用する場合は、各プレフィックスに <package> エントリを追加します。
<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://nuget.pkg.github.com/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="github">
            <package pattern="PACKAGE-ID-PREFIX.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

NuGet では 最も具体的な照合パターンが使用されるため、 PACKAGE-ID-PREFIX.* に一致するパッケージは GitHub Packagesからのみフェッチされ、他のすべてのパッケージは nuget.org からフェッチされます。これにより、プライベート パッケージが GitHub Packages フィードからのみ取得できるようにすることで、依存関係の混乱攻撃を防ぐのにも役立ちます。

参考資料