{"meta":{"title":"Working with the NuGet registry","intro":"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.","product":"GitHub Packages","breadcrumbs":[{"href":"/en/packages","title":"GitHub Packages"},{"href":"/en/packages/working-with-a-github-packages-registry","title":"Working with a GitHub Packages registry"},{"href":"/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry","title":"NuGet registry"}],"documentType":"article"},"body":"# Working with the NuGet registry\n\nYou 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.\n\n<!-- 2148AF7B-5FF8-4B28-A808-D692FEE2225A -->\n\n## Authenticating to GitHub Packages\n\n> \\[!NOTE]\n> GitHub Packages only supports authentication using a personal access token (classic). For more information, see [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).\n\nYou need an access token to publish, install, and delete private, internal, and public packages.\n\nYou can use a personal access token (classic) to authenticate to GitHub Packages or the GitHub API. When you create a personal access token (classic), you can assign the token different scopes depending on your needs. For more information about packages-related scopes for a personal access token (classic), see [About permissions for GitHub Packages](/en/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries).\n\nTo authenticate to a GitHub Packages registry within a GitHub Actions workflow, you can use:\n\n* `GITHUB_TOKEN` to publish packages associated with the workflow repository.\n* A personal access token (classic) with at least `read:packages` scope to install packages associated with other private repositories (`GITHUB_TOKEN` can be used if the repository is granted read access to the package. See [Configuring a package's access control and visibility](/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility)).\n\n### Authenticating in a GitHub Actions workflow\n\nThis registry supports granular permissions. For registries that support granular permissions, if your GitHub Actions workflow is using a personal access token to authenticate to a registry, we highly recommend you update your workflow to use the `GITHUB_TOKEN`. For guidance on updating your workflows that authenticate to a registry with a personal access token, see [Publishing and installing a package with GitHub Actions](/en/packages/managing-github-packages-using-github-actions-workflows/publishing-and-installing-a-package-with-github-actions#upgrading-a-workflow-that-accesses-a-registry-using-a-personal-access-token).\n\n> \\[!NOTE]\n> The ability for GitHub Actions workflows to delete and restore packages using the REST API is currently in public preview and subject to change.\n\nYou can use a `GITHUB_TOKEN` in a GitHub Actions workflow to delete or restore a package using the REST API, if the token has `admin` permission to the package. Repositories that publish packages using a workflow, and repositories that you have explicitly connected to packages, are automatically granted `admin` permission to packages in the repository.\n\nFor more information about the `GITHUB_TOKEN`, see [Use GITHUB\\_TOKEN for authentication in workflows](/en/actions/tutorials/authenticate-with-github_token#using-the-github_token-in-a-workflow). For more information about the best practices when using a registry in actions, see [Compromised runners](/en/actions/concepts/security/compromised-runners#cross-repository-access).\n\nUse the following command to authenticate to GitHub Packages in a GitHub Actions workflow using the `GITHUB_TOKEN` instead of hardcoding a personal access token in a nuget.config file in the repository:\n\n```shell\ndotnet nuget add source --username USERNAME --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github \"https://nuget.pkg.github.com/NAMESPACE/index.json\"\n```\n\nReplace `NAMESPACE` with the name of the personal account or organization to which your packages are scoped.\n\nReplace `USERNAME` with the username to be used when connecting to an authenticated source.\n\nYou can also choose to give access permissions to packages independently for GitHub Codespaces and GitHub Actions. For more information, see [Configuring a package's access control and visibility](/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-github-codespaces-access-to-your-package) and [Configuring a package's access control and visibility](/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package).\n\n### Authenticating with a personal access token\n\n> \\[!NOTE]\n> GitHub Packages only supports authentication using a personal access token (classic). For more information, see [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).\n\nYou need an access token to publish, install, and delete private, internal, and public packages.\n\nYou can use a personal access token (classic) to authenticate to GitHub Packages or the GitHub API. When you create a personal access token (classic), you can assign the token different scopes depending on your needs. For more information about packages-related scopes for a personal access token (classic), see [About permissions for GitHub Packages](/en/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries).\n\nTo authenticate to a GitHub Packages registry within a GitHub Actions workflow, you can use:\n\n* `GITHUB_TOKEN` to publish packages associated with the workflow repository.\n* A personal access token (classic) with at least `read:packages` scope to install packages associated with other private repositories (`GITHUB_TOKEN` can be used if the repository is granted read access to the package. See [Configuring a package's access control and visibility](/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility)).\n\nYou must use a personal access token (classic) with the appropriate scopes to publish and install packages in GitHub Packages. For more information, see [Introduction to GitHub Packages](/en/packages/learn-github-packages/introduction-to-github-packages#authenticating-to-github-packages).\n\nTo 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.\n\nYou must replace:\n\n* `USERNAME` with the name of your personal account on GitHub.\n* `TOKEN` with your personal access token (classic).\n* `NAMESPACE` with the name of the personal account or organization to which your packages are scoped.\n\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<configuration>\n    <packageSources>\n        <clear />\n        <add key=\"github\" value=\"https://nuget.pkg.github.com/NAMESPACE/index.json\" />\n    </packageSources>\n    <packageSourceCredentials>\n        <github>\n            <add key=\"Username\" value=\"USERNAME\" />\n            <add key=\"ClearTextPassword\" value=\"TOKEN\" />\n        </github>\n    </packageSourceCredentials>\n</configuration>\n```\n\n## Publishing a package\n\n> \\[!NOTE]\n> The `nupkg` archive for a NuGet package version must be smaller than 2.147 GB in size.\n\nYou can publish a package to GitHub Packages by authenticating with a *nuget.config* file, using the `--api-key` command line option with your GitHub personal access token (classic) or by using command that can be run directly from the command line using the `dotnet` command-line interface (CLI).\n\nReplace `OWNER` with your username or company name, and `YOUR_GITHUB_PAT` with your personal access token.\n\n```shell\ndotnet nuget add source --username OWNER --password YOUR_GITHUB_PAT --store-password-in-clear-text --name github \"https://nuget.pkg.github.com/OWNER/index.json\"\n```\n\nThe NuGet registry stores packages within your organization or personal account, and allows you to associate packages with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository.\n\nWhen you first publish a package, the default visibility is private. To change the visibility or set access permissions, see [Configuring a package's access control and visibility](/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility). For more information on linking a published package with a repository, see [Connecting a repository to a package](/en/packages/learn-github-packages/connecting-a-repository-to-a-package).\n\nIf you specify a `RepositoryURL` in your project's *.csproj* file, the published package will automatically be connected to the specified repository. For more information, see [Working with the NuGet registry](/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#publishing-a-package-using-a-nugetconfig-file). For information on linking an already-published package to a repository, see [Connecting a repository to a package](/en/packages/learn-github-packages/connecting-a-repository-to-a-package).\n\n### Publishing a package using a GitHub personal access token as your API key\n\nIf you don't already have a personal access token to use for your account on GitHub, see [Managing your personal access tokens](/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).\n\n1. Create a new project. Replace `PROJECT_NAME` with the name you'd like to give the project.\n\n   ```shell\n   dotnet new console --name PROJECT_NAME\n   ```\n\n2. Package the project.\n\n   ```shell\n   dotnet pack --configuration Release\n   ```\n\n3. Publish the package using your personal access token as the API key. Replace `PROJECT_NAME` with the name of the project, `1.0.0` with the version number of the package, and `YOUR_GITHUB_PAT` with your personal access token.\n\n   ```shell\n   dotnet nuget push \"bin/Release/PROJECT_NAME.1.0.0.nupkg\" --api-key YOUR_GITHUB_PAT --source \"github\"\n   ```\n\nAfter you publish a package, you can view the package on GitHub. For more information, see [Viewing packages](/en/packages/learn-github-packages/viewing-packages).\n\n### Publishing a package using a *nuget.config* file\n\nWhen publishing, if you are linking your package to a repository, the `OWNER` of the repository specified in your *.csproj* file must match the `NAMESPACE` 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](https://docs.microsoft.com/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli) in the Microsoft documentation.\n\n> \\[!NOTE]\n> If you publish a package that is linked to a repository, the package automatically inherits the access permissions of the linked repository, and GitHub Actions workflows in the linked repository automatically get access to the package, unless your organization has disabled automatic inheritance of access permissions. For more information, see [Configuring a package's access control and visibility](/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#about-inheritance-of-access-permissions).\n\n1. Authenticate to GitHub Packages. For more information, see [Authenticating to GitHub Packages](#authenticating-to-github-packages).\n\n2. Create a new project. Replace `PROJECT_NAME` with the name you'd like to give the project.\n\n   ```shell\n   dotnet new console --name PROJECT_NAME\n   ```\n\n3. Add your project's specific information to your project's file, which ends in *.csproj*. Make sure to replace:\n\n   * `1.0.0` with the version number of the package.\n   * `OWNER` with the name of the personal account or organization that owns the repository to which you want to link your package.\n   * `REPOSITORY` with the name of the repository to which you want to connect your package.\n\n   ```xml\n   <Project Sdk=\"Microsoft.NET.Sdk\">\n\n     <PropertyGroup>\n       <OutputType>Exe</OutputType>\n       <TargetFramework>netcoreapp3.0</TargetFramework>\n       <PackageId>PROJECT_NAME</PackageId>\n       <Version>1.0.0</Version>\n       <Authors>AUTHORS</Authors>\n       <Company>COMPANY_NAME</Company>\n       <PackageDescription>PACKAGE_DESCRIPTION</PackageDescription>\n       <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>\n     </PropertyGroup>\n\n   </Project>\n   ```\n\n4. Package the project.\n\n   ```shell\n   dotnet pack --configuration Release\n   ```\n\n5. Publish the package using the `key` you specified in the *nuget.config* file. Replace `PROJECT_NAME` with the name of the project, and replace `1.0.0` with the version number of the package.\n\n   ```shell\n   dotnet nuget push \"bin/Release/PROJECT_NAME.1.0.0.nupkg\" --source \"github\"\n   ```\n\nAfter you publish a package, you can view the package on GitHub. For more information, see [Viewing packages](/en/packages/learn-github-packages/viewing-packages).\n\n## Publishing multiple packages to the same repository\n\nTo connect multiple packages to the same repository, use the same GitHub repository URL in the `RepositoryURL` fields in all *.csproj* project files. GitHub matches the repository based on that field.\n\nThe following example publishes the projects MY\\_APP and MY\\_OTHER\\_APP to the same repository:\n\n```xml\n<Project Sdk=\"Microsoft.NET.Sdk\">\n\n  <PropertyGroup>\n    <OutputType>Exe</OutputType>\n    <TargetFramework>netcoreapp3.0</TargetFramework>\n    <PackageId>MY_APP</PackageId>\n    <Version>1.0.0</Version>\n    <Authors>Octocat</Authors>\n    <Company>GitHub</Company>\n    <PackageDescription>This package adds a singing Octocat!</PackageDescription>\n    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>\n  </PropertyGroup>\n\n</Project>\n```\n\n```xml\n<Project Sdk=\"Microsoft.NET.Sdk\">\n\n  <PropertyGroup>\n    <OutputType>Exe</OutputType>\n    <TargetFramework>netcoreapp3.0</TargetFramework>\n    <PackageId>MY_OTHER_APP</PackageId>\n    <Version>1.0.0</Version>\n    <Authors>Octocat</Authors>\n    <Company>GitHub</Company>\n    <PackageDescription>This package adds a dancing Octocat!</PackageDescription>\n    <RepositoryUrl>https://github.com/my-org/my-repo</RepositoryUrl>\n  </PropertyGroup>\n\n</Project>\n```\n\n## Installing a package\n\nUsing 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](https://docs.microsoft.com/nuget/consume-packages/overview-and-workflow) in the Microsoft documentation.\n\n1. Authenticate to GitHub Packages. For more information, see [Authenticating to GitHub Packages](#authenticating-to-github-packages).\n\n2. To use a package, add `ItemGroup` and configure the `PackageReference` field in the *.csproj* project file. Replace the `PACKAGE_NAME` value in `Include=\"PACKAGE_NAME\"` with your package dependency, and replace the `X.X.X` value in `Version=\"X.X.X\"` with the version of the package you want to use:\n\n   ```xml\n   <Project Sdk=\"Microsoft.NET.Sdk\">\n\n     <PropertyGroup>\n       <OutputType>Exe</OutputType>\n       <TargetFramework>netcoreapp3.0</TargetFramework>\n       <PackageId>My-app</PackageId>\n       <Version>1.0.0</Version>\n      <Authors>Octocat</Authors>\n       <Company>GitHub</Company>\n      <PackageDescription>This package adds an Octocat!</PackageDescription>\n       <RepositoryUrl>https://github.com/OWNER/REPOSITORY</RepositoryUrl>\n     </PropertyGroup>\n\n     <ItemGroup>\n       <PackageReference Include=\"PACKAGE_NAME\" Version=\"X.X.X\" />\n     </ItemGroup>\n\n   </Project>\n   ```\n\n3. Install the packages with the `restore` command.\n\n   ```shell\n   dotnet restore\n   ```\n\n## Troubleshooting\n\nIf you're using a `GITHUB_TOKEN` to authenticate to a GitHub Packages registry within a GitHub Actions workflow, the token cannot access private repository-based packages in a different repository other than where the workflow is running in. To access packages associated with other repositories, instead generate a personal access token (classic) with the `read:packages` scope and pass this token in as a secret.\n\n### Intermittent 403 errors when restoring public packages\n\nIf you're using GitHub Packages alongside *nuget.org* and experiencing intermittent 403 Forbidden errors when restoring standard public packages (like `Microsoft.Extensions.*`), this may occur because NuGet queries all configured package sources for every package. If GitHub Packages authentication fails temporarily, it can block the entire restore—even for packages that don't exist on GitHub Packages.\n\nTo avoid this, use [NuGet Package Source Mapping](https://learn.microsoft.com/nuget/consume-packages/package-source-mapping) to route packages to specific sources.\n\nReplace:\n\n* `NAMESPACE` with the name of the personal account or organization that owns your GitHub Packages NuGet feed.\n* `PACKAGE-ID-PREFIX` with the NuGet package ID prefix that you use for packages hosted on GitHub Packages. If you use multiple prefixes, add additional `<package>` entries for each prefix.\n\n```xml\n<configuration>\n    <packageSources>\n        <add key=\"nuget.org\" value=\"https://api.nuget.org/v3/index.json\" />\n        <add key=\"github\" value=\"https://nuget.pkg.github.com/NAMESPACE/index.json\" />\n    </packageSources>\n    <packageSourceMapping>\n        <packageSource key=\"nuget.org\">\n            <package pattern=\"*\" />\n        </packageSource>\n        <packageSource key=\"github\">\n            <package pattern=\"PACKAGE-ID-PREFIX.*\" />\n        </packageSource>\n    </packageSourceMapping>\n</configuration>\n```\n\nNuGet uses the [most specific matching pattern](https://learn.microsoft.com/nuget/consume-packages/package-source-mapping#package-pattern-precedence), so packages matching `PACKAGE-ID-PREFIX.*` are fetched only from GitHub Packages, while all other packages are fetched from *nuget.org*. This also helps prevent dependency confusion attacks by ensuring your private packages can only come from your GitHub Packages feed.\n\n## Further reading\n\n* [Deleting and restoring a package](/en/packages/learn-github-packages/deleting-and-restoring-a-package)"}