NuGetレジストリの利用

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

この記事で

メモ

サイト管理者はサポートされている各パッケージの種類を有効または無効にできるので、このパッケージの種類はインスタンスで利用できない可能性があります。 詳しくは、「Enterprise 向けのパッケージエコシステムサポートを設定する」をご覧ください。

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 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.HOSTNAME/NAMESPACE/index.json"

NAMESPACE を、パッケージがホストされているリポジトリを所有する個人アカウントまたは組織の名前に置き換えてください。

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

GitHub Actions ワークフローで使われる GITHUB_TOKEN の詳細については、「ワークフローでの認証に GITHUB_TOKEN を使用する」を参照してください。

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パッケージのスコープ先となっている個人アカウントまたは組織の名前パッケージがホストされているリポジトリを所有している。
  • HOSTNAME お使いの GitHub Enterprise Server インスタンスのホスト名を指定します。

インスタンスでサブドメイン分離が有効になっている場合:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://nuget.HOSTNAME/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

インスタンスのサブドメイン分離が無効になっている場合:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://HOSTNAME/_registry/nuget/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

パッケージの公開

パッケージを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.HOSTNAME/OWNER/index.json"

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 ドキュメントの「パッケージの作成と公開」を参照してください。

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

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

    dotnet new console --name PROJECT_NAME

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

    • 1.0.0 をパッケージのバージョン番号に。
    • OWNER パッケージを公開する先のリポジトリを所有する個人アカウントまたは組織の名前を指定して
    • REPOSITORY パッケージを接続するリポジトリの名前を指定します。
    • HOSTNAME お使いの GitHub Enterprise Server インスタンスのホスト名を指定します。
    <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://HOSTNAME/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://HOSTNAME/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://HOSTNAME/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://HOSTNAME/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

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

</Project>

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

    dotnet restore

トラブルシューティング

RepositoryUrl の__ が予想されるリポジトリに設定されていない場合、NuGet パッケージがプッシュに失敗する可能性があります。

nuspec ファイルを使用している場合は、必要なrepository属性とtype属性を持つurl要素があることを確認します。

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> エントリを追加します。
  • HOSTNAME お使いの GitHub Enterprise Server インスタンスのホスト名を指定します。

インスタンスでサブドメイン分離が有効になっている場合:

<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://nuget.HOSTNAME/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceMapping>
        <packageSource key="nuget.org">
            <package pattern="*" />
        </packageSource>
        <packageSource key="github">
            <package pattern="PACKAGE-ID-PREFIX.*" />
        </packageSource>
    </packageSourceMapping>
</configuration>

インスタンスのサブドメイン分離が無効になっている場合:

<configuration>
    <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="github" value="https://HOSTNAME/_registry/nuget/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 フィードからのみ取得できるようにすることで、依存関係の混乱攻撃を防ぐのにも役立ちます。

参考資料