Configuring NuGet for use with GitHub Package Registry
You can configure NuGet to publish packages to GitHub Package Registry and to use packages stored on GitHub Package Registry as dependencies in a .Net project.
GitHub Package Registry is currently available in limited public beta. You should avoid using GitHub Package Registry for high-value workflows and content during the beta period. For more information, see "About GitHub Package Registry."
In this article
- Authenticating to GitHub Package Registry
- Publishing a package
- Receiving package registry events
- Installing a package
- Deleting a package
Authenticating to GitHub Package Registry
You must use a personal access token with the
write:packages scopes to publish and delete public packages in the GitHub Package Registry with NuGet. Your personal access token must also have the
repo scope when the repository is private. For more information, see "Creating a personal access token for the command line."
You can configure
nuget to use your token when pushing new packages by adding GitHub Package Registry as a
Source to the
OWNER in the scope parameter with the GitHub user or organization name that contains the repository where you will publish the package.
nuget sources Add -Name "GPR" \ -Source "https://nuget.pkg.github.com/OWNER/index.json" \ -UserName USERNAME -Password TOKEN
If you are using a GitHub Actions workflow, you can use a
GITHUB_TOKEN to publish and consume packages in the GitHub Package Registry without needing to store and manage a personal access token. For more information about
GITHUB_TOKEN, see "
You can use a script to inject your
GITHUB_TOKEN into the appropriate configuration file for GitHub Package Registry. Add GitHub Package Registry as an alternative registry or repository in the configuration file for the package client, as well as your GitHub username and a personal access token with the appropriate scopes. The exact steps for creating a configuration file vary by package type.
Publishing a package
You can publish a NuGet package to GitHub Package Registry under the
OWNER using the
nuget CLI to specify the
Source. Using the previous example, specify
GPR as the package source and replace YOUR-PACKAGE with the name of your package.
$ nuget push YOUR-PACKAGE.nupkg -Source "GPR"
You can access your packages from this URL by replacing
OWNER with your GitHub user or organization name and
REPOSITORY with your repository name:
Publishing multiple packages to the same GitHub repository
When you publish a package, by default GitHub Package Registry uses the package name to determine the GitHub repository where it will be published. For example, a package named
odata-client would be published to the
OWNER/odata-client GitHub repository.
If you would like to change the repository where the package is published, or publish multiple packages to the same repository, you can include the URL to the GitHub repository in the
repository field of the package's .nuspec file. GitHub will match the repository based on that field, instead of the package name.
Add the URL of the GitHub repository in the
repositoryfield of the package's .nuspec file.
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd"> <metadata> <id>sample</id> <version>1.2.3</version> <authors>Kim Abercrombie, Franck Halmaert</authors> <description>Sample exists only to show a sample .nuspec file.</description> <language>en-US</language> <repository type="git" url="https://github.com/my-org/my-custom-repo"/> </metadata> </package>
Note: If you have a
.csprojfile created by Visual Studio, the version you use in your .nuspec file must match the version in your
Create the package using the configuration in the package's .nuspec file.
$ dotnet pack --configuration Release
Publish the new package to GitHub, replacing YOUR-PACKAGE with the name of your package.
$ nuget push YOUR-PACKAGE.nupkg -Source "GPR"
For more information on creating your package, see "Create and publish a package" in the Microsoft documentation.
Receiving package registry events
You can receive webhook events when a package is
updated. For more information, see "RegistryPackageEvent" in the GitHub Developer documentation.
Installing a package
Using packages from GitHub in your projects is similar to using packages from nuget.org. Add your package dependencies to your package.config specifying the package name & version.
- Authenticate to GitHub Package Registry with
nuget source Add. For more information, see "Authenticating to GitHub Package Registry."
Configure packages.config to use the package. For example, this packages.config uses the
octo-apppackage as a dependency.
<packages> <package id="octo-app" version="3.1.1" /> </packages> </xml>
Restore all packages.
$ nuget restore
For more information on using a packages.config in your project, see "Working with NuGet packages" in the Microsoft documentation.
Deleting a package
To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support deleting published versions of a package or an entire published package for public repositories. Under special circumstances, such as for legal reasons or to conform with GDPR standards, you can request deleting a package through GitHub Support. Contact GitHub Support using our contact form and the subject line "GitHub Package Registry."
You can delete private packages via GitHub's API. For more information, see "Access to package version deletion" in the GitHub Developer documentation.