Working with the NuGet registry

You can configure the dotnet command-line interface (CLI) to publish NuGet packages to GitHub Packages and to use packages stored on GitHub Packages as dependencies in a .NET project.

GitHub Packages 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 和 GitHub AE。

注:这种包类型可能不适用于您的实例,因为站点管理员可以启用或禁用每种支持的包类型。 更多信息请参阅“为企业配置软件包支持”。

Authenticating to GitHub Packages

您需要访问令牌才能发布、安装和删除 GitHub Packages 中的包。

You can use a personal access token (PAT) to authenticate to GitHub Packages or the GitHub Enterprise Server API. 创建个人访问令牌时,可根据需要为令牌分配不同的作用域。 有关 PAT 与包相关的域的更多信息,请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证,您可以使用:

  • GITHUB_TOKEN 来发布与工作流程仓库相关联的包。
  • PAT 来安装与其他私有仓库(GITHUB_TOKEN 无法访问)相关联的包。

Authenticating with GITHUB_TOKEN in GitHub Actions

Use the following command to authenticate to GitHub Packages in a GitHub Actions workflow using the GITHUB_TOKEN instead of hardcoding a token in a nuget.config file in the repository:

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

有关 GitHub Actions 工作流程中使用的 GITHUB_TOKEN 的更多信息,请参阅“工作流程中的身份验证”。

Authenticating with a personal access token

您必须使用具有适当范围的个人访问令牌才可在 GitHub Packages 中发布和安装。 更多信息请参阅“关于 GitHub Packages”。

To authenticate to GitHub Packages with the dotnet command-line interface (CLI), create a nuget.config file in your project directory specifying GitHub Packages as a source under packageSources for the dotnet CLI client.

You must replace:

  • USERNAME with the name of your user account on GitHub.
  • TOKEN with your personal access token.
  • OWNER with the name of the user or organization account that owns the repository containing your project.
  • HOSTNAME with the host name for your GitHub Enterprise Server instance.

If your instance has subdomain isolation enabled:

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

If your instance has subdomain isolation disabled:

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

Publishing a package

You can publish a package to GitHub Packages by authenticating with a nuget.config file, or by using the --api-key command line option with your GitHub personal access token (PAT).

Publishing a package using a GitHub PAT as your API key

If you don't already have a PAT to use for your account on your GitHub Enterprise Server instance, see "Creating a personal access token."

  1. Create a new project.

    dotnet new console --name OctocatApp
  2. Package the project.

    dotnet pack --configuration Release
  3. Publish the package using your PAT as the API key.

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

在发布包后,您可以在 GitHub 上查看该包。 更多信息请参阅“查看包”。

Publishing a package using a nuget.config file

When publishing, you need to use the same value for OWNER in your csproj file that you use in your nuget.config authentication file. Specify or increment the version number in your .csproj file, then use the dotnet pack command to create a .nuspec file for that version. For more information on creating your package, see "Create and publish a package" in the Microsoft documentation.

  1. 向 GitHub Packages 验证。 更多信息请参阅“向 GitHub Packages 验证”。

  2. Create a new project.

    dotnet new console --name OctocatApp
  3. Add your project's specific information to your project's file, which ends in .csproj. You must replace:

    • OWNER with the name of the user or organization account that owns the repository containing your project.
    • REPOSITORY with the name of the repository containing the package you want to publish.
    • 1.0.0 with the version number of the package.
    • HOSTNAME with the host name for your GitHub Enterprise Server instance.
    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <PackageId>OctocatApp</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>
    
    </Project>
    
  4. Package the project.

    dotnet pack --configuration Release
  5. Publish the package using the key you specified in the nuget.config file.

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

在发布包后,您可以在 GitHub 上查看该包。 更多信息请参阅“查看包”。

Publishing multiple packages to the same repository

To publish multiple packages to the same repository, you can include the same GitHub repository URL in the RepositoryURL fields in all .csproj project files. GitHub matches the repository based on that field.

For example, the OctodogApp and OctocatApp projects will publish to the same repository:

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>OctodogApp</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octodog</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds an Octodog!</PackageDescription>
    <RepositoryUrl>https://HOSTNAME/octo-org/octo-cats-and-dogs</RepositoryUrl>
  </PropertyGroup>

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <PackageId>OctocatApp</PackageId>
    <Version>1.0.0</Version>
    <Authors>Octocat</Authors>
    <Company>GitHub</Company>
    <PackageDescription>This package adds an Octocat!</PackageDescription>
    <RepositoryUrl>https://HOSTNAME/octo-org/octo-cats-and-dogs</RepositoryUrl>
  </PropertyGroup>

</Project>

Installing a package

Using packages from GitHub in your project is similar to using packages from nuget.org. Add your package dependencies to your .csproj file, specifying the package name and version. For more information on using a .csproj file in your project, see "Working with NuGet packages" in the Microsoft documentation.

  1. 向 GitHub Packages 验证。 更多信息请参阅“向 GitHub Packages 验证”。

  2. To use a package, add ItemGroup and configure the PackageReference field in the .csproj project file, replacing the OctokittenApp package with your package dependency and 1.0.0 with the version you want to use:

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <PackageId>OctocatApp</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="OctokittenApp" Version="12.0.2" />
      </ItemGroup>
    
    </Project>
    
  3. Install the packages with the restore command.

    dotnet restore

Troubleshooting

Your NuGet package may fail to push if the RepositoryUrl in .csproj is not set to the expected repository .

Further reading

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。