NuGetレジストリの利用

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

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

GitHub Packagesは、GitHub Free、GitHub Pro、組織用GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0以降で利用できます。
GitHub Packagesは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。また、従来のリポジトリごとのプランを使用しているアカウントは、詳細なアクセス許可をサポートするレジストリにアクセスできません。これらのアカウントはリポジトリによって課金されるためです。Enterprise Managed Users には、アカウントの名前空間内でパッケージを発行するための個別のストレージ割り当てはありませんが、organizationの名前空間に発行できます。 Enterprise Managed Users の詳細については、「Enterprise Managed Users について」を参照してください。詳細なアクセス許可をサポートするレジストリの一覧については、「GitHub Packagesの権限について」を参照してください。詳しくは、「GitHub のプラン」をご覧ください。

この記事の内容

GitHub Packages への認証を行う

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

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

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

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

GITHUB_TOKEN では、ワークフローリポジトリに関連付けられているパッケージを発行します。
read:packages 以上のスコープが設定された personal access token (classic) では、他のプライベートリポジトリ (GITHUB_TOKEN ではアクセスできない) に関連付けられているパッケージがインストールされます。

GitHub Actions ワークフローにおける認証

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

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

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

GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。アクションでレジストリを使うときのベストプラクティスについて詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

リポジトリ内の nuget.config ファイルでpersonal access tokenをハードコーディングするのでなく、GITHUB_TOKEN を使用して GitHub Actions ワークフローで GitHub Packages に対して認証を行うには、以下のコマンドを使用してください。

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

GITHUB_TOKEN では、ワークフローリポジトリに関連付けられているパッケージを発行します。
read:packages 以上のスコープが設定された personal access token (classic) では、他のプライベートリポジトリ (GITHUB_TOKEN ではアクセスできない) に関連付けられているパッケージがインストールされます。

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

dotnet コマンドラインインターフェイス (CLI) で GitHub Packages に対して認証を行うには、dotnet CLI クライアントの packageSources に GitHub Packages をソースとして指定して、プロジェクトディレクトリに nuget.config ファイルを作成してください。

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

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.config ファイルを使用して認証を行うか、GitHub personal access token (classic) とともに --api-key コマンドラインオプションを使用するか、dotnet コマンドラインインターフェイスパッケージ (CLI) を用いたコマンドラインから直接実行できるコマンドを使うことで、GitHub Packages にパッケージを公開できます。

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 または個人のアカウント内にパッケージを格納し、パッケージをリポジトリに関連付けることができます。権限をリポジトリから継承するか、リポジトリとは別に細かい権限を設定するかを選ぶことができます。

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

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

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

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

新しいプロジェクトを作成します。 PROJECT_NAME は、プロジェクトに付ける名前に置き換えます。
```
dotnet new console --name PROJECT_NAME
```
プロジェクトをパッケージ化してください。
```
dotnet pack --configuration Release
```
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 ファイルを使用してパッケージを公開する

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

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

GitHub Packagesに認証を受けてください。詳細については、「GitHub Packages への認証」を参照してください。
新しいプロジェクトを作成します。 PROJECT_NAME は、プロジェクトに付ける名前に置き換えます。
```
dotnet new console --name PROJECT_NAME
```

プロジェクト固有の情報をプロジェクトファイル (末尾が .csproj のファイル) に追加します。必ず次のように置き換えてください。

1.0.0 をパッケージのバージョン番号に。
OWNER を、パッケージのリンク先にしたいリポジトリを所有している個人アカウントまたは Organization の名前に。
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>

プロジェクトをパッケージ化してください。
```
dotnet pack --configuration Release
```
nuget.config ファイルで指定した key を使用してパッケージを公開します。 PROJECT_NAME をプロジェクトの名前に、1.0.0 をパッケージのバージョン番号に置き換えます。
```
dotnet nuget push "bin/Release/PROJECT_NAME.1.0.0.nupkg" --source "github"
```

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

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

複数のパッケージを同じリポジトリに接続するには、同じ GitHub リポジトリの URL をすべての .csproj プロジェクトファイルの RepositoryURL フィールドで使います。 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 ファイルに追加してください。プロジェクトで .csproj ファイルを使う方法について詳しくは、NuGet パッケージの利用に関する Microsoft のドキュメントをご覧ください。

GitHub Packagesに認証を受けてください。詳細については、「GitHub Packages への認証」を参照してください。

パッケージを使用するには、 .csproj プロジェクトファイルで ItemGroup を追加し、PackageReference フィールドを構成します。 Include="PACKAGE_NAME" の PACKAGE_NAME 値をパッケージ依存関係に置き換え、Version="X.X.X" の 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>

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

トラブルシューティング

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

参考資料

パッケージを削除および復元する