Skip to main content

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は、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 また、従来のリポジトリごとのプランを利用しているアカウントは、リポジトリごとに課金されるため、詳細なアクセス許可をサポートしているレジストリにはアクセスできません。 詳細なアクセス許可をサポートするレジストリの一覧については、「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 を、パッケージがホストされているリポジトリを所有しており、パッケージのスコープ指定先となっている。

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

personal access token で認証を行う

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 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 ファイルを使用して認証を行うか、コマンド ライン オプションの --api-key と GitHub personal access token (classic) を使うことで、パッケージを GitHub Packages に公開できます。

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

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

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

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

GitHub.com のアカウントで使う personal access token がまだない場合は、「個人用アクセス トークンを管理する」をご覧ください。

  1. 新しいプロジェクトを作成します。 PROJECT_NAME は、プロジェクトに付ける名前に置き換えます。

    dotnet new console --name PROJECT_NAME
    
  2. プロジェクトをパッケージ化してください。

    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 ファイルを使用してパッケージを公開する

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

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

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

  2. 新しいプロジェクトを作成します。 PROJECT_NAME は、プロジェクトに付ける名前に置き換えます。

    dotnet new console --name PROJECT_NAME
    
  3. プロジェクト固有の情報をプロジェクト ファイル (末尾が .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>
    
  4. プロジェクトをパッケージ化してください。

    dotnet pack --configuration Release
    
  5. 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 のドキュメントをご覧ください。

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

  2. パッケージを使用するには、 .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>
    
  3. restore コマンドを使用してパッケージをインストールします。

    dotnet restore
    

トラブルシューティング

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

参考資料