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. For more information, see "About GitHub Package Registry."

In this article

Authenticating to GitHub Package Registry

You must use a personal access token with the read:packages and 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 nuget client. Replace the OWNER in the scope parameter with the GitHub user or organization name that contains the repository where you will publish the package.

nuget source Add -Name "GitHub nuget registry" \
     -Source "https://nuget.pkg.github.com/OWNER/index.json" \
     -UserName USERNAME -Password TOKEN

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 GitHub nuget registry as the package source:

$ nuget push  -Source "GitHub nuget registry"

You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

https://github.com/OWNER/REPOSITORY/packages

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. A GitHub release and associated Git tag will be automatically created for the version of the package, if it doesn't already exist.

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 projectUrl field of the package's .nuspec file. GitHub will match the repository based on that field, instead of the package name.

<?xml version="1.0" encoding="utf-8"?>
<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>
    <projectUrl>https://github.com/my-org/my-custom-repo</projectUrl>
    </metadata>
</package>

For more information on creating your package, see "Create and publish a package" in the nuget documentation.

Receiving package registry events

You can receive webhook events when a package is published or 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.

  1. Authenticate to GitHub Package Registry with nuget source Add. For more information, see "Authenticating to GitHub Package Registry."

  2. Configure package.config to use the package & add GitHub Package Registry as a PackageSource. For example, this package.config uses the octo-app package as a dependency.

      <?xml version="1.0" encoding="utf-8"?>
        <packages>
          <package id="octo-app" version="3.1.1"/>
        </packages>
        <packageSources>
          <add key="GitHub nuget registry" value="https://nuget.pkg.github.com/OWNER/index.json" protocolVersion="3" />
        </packageSources>
      </xml>
  3. Install the package.

    $ nuget install

For more information on using a package.config in your project, see "Working with nuget packages" in the MSDN nuget documentation.

Deleting a package

You can delete packages from GitHub Package Registry by using a http client like curl.

Caution: Deleting a package is irreversible.

To delete a single version of a package:

$ curl -v -XDELETE -u"USERNAME:TOKEN" \
  "https://nuget.pkg.github.com/OWNER/PACKAGE_NAME/PACKAGE_VERSION"

Ask a human

Can't find what you're looking for?

Contact us