Skip to content

Latest commit

 

History

History
294 lines (207 loc) · 14.2 KB

working-with-the-nuget-registry.md

File metadata and controls

294 lines (207 loc) · 14.2 KB
Raw
title intro product redirect_from versions shortTitle
Working with the NuGet registry
You can configure the `dotnet` command-line interface (CLI) to publish NuGet packages to {% data variables.product.prodname_registry %} and to use packages stored on {% data variables.product.prodname_registry %} as dependencies in a .NET project.
{% data reusables.gated-features.packages %}
/articles/configuring-nuget-for-use-with-github-package-registry
/github/managing-packages-with-github-package-registry/configuring-nuget-for-use-with-github-package-registry
/github/managing-packages-with-github-packages/configuring-nuget-for-use-with-github-packages
/github/managing-packages-with-github-packages/configuring-dotnet-cli-for-use-with-github-packages
/packages/using-github-packages-with-your-projects-ecosystem/configuring-dotnet-cli-for-use-with-github-packages
/packages/guides/configuring-dotnet-cli-for-use-with-github-packages
fpt ghes ghec
*
*
*
NuGet registry

{% data reusables.package_registry.packages-ghes-release-stage %}

{% data reusables.package_registry.admins-can-configure-package-types %}

{% ifversion ghec %}

URL for the NuGet registry

If you access {% data variables.product.github %} at {% data variables.product.prodname_dotcom_the_website %}, you will publish packages to https://nuget.pkg.github.com. Examples in this article use this URL.

If you access {% data variables.product.github %} at another domain, such as octocorp.ghe.com, replace "https://nuget.pkg.github.com" with https://nuget.SUBDOMAIN.ghe.com, where SUBDOMAIN is your enterprise's unique subdomain.

{% endif %}

Authenticating to {% data variables.product.prodname_registry %}

{% data reusables.package_registry.authenticate-packages %}

Authenticating in a {% data variables.product.prodname_actions %} workflow

{% ifversion packages-nuget-v2 %} This registry supports granular permissions. {% data reusables.package_registry.authenticate_with_pat_for_v2_registry %} {% endif %}

Use the following command to authenticate to {% data variables.product.prodname_registry %} in a {% data variables.product.prodname_actions %} workflow using the GITHUB_TOKEN instead of hardcoding a {% data variables.product.pat_generic %} in a nuget.config file in the repository:

dotnet nuget add source --username USERNAME --password {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %} --store-password-in-clear-text --name github "https://{% ifversion fpt or ghec %}nuget.pkg.github.com{% else %}nuget.HOSTNAME{% endif %}/NAMESPACE/index.json"

Replace NAMESPACE with the name of the personal account or organization {% ifversion packages-nuget-v2 %}to which your packages are scoped{% else %}that owns the repository where your packages are hosted{% endif %}.

Replace USERNAME with the username to be used when connecting to an authenticated source.

{% ifversion packages-nuget-v2 %}{% else %}{% data reusables.package_registry.authenticate-packages-github-token %}{% endif %}

{% ifversion packages-nuget-v2 %}

{% data reusables.package_registry.v2-actions-codespaces %}

{% endif %}

Authenticating with a {% data variables.product.pat_generic %}

{% data reusables.package_registry.authenticate-packages %}

{% data reusables.package_registry.required-scopes %}

To authenticate to {% data variables.product.prodname_registry %} with the dotnet command-line interface (CLI), create a nuget.config file in your project directory specifying {% data variables.product.prodname_registry %} as a source under packageSources for the dotnet CLI client.

You must replace:

  • USERNAME with the name of your personal account on {% data variables.product.prodname_dotcom %}.
  • TOKEN with your {% data variables.product.pat_v1 %}.
  • NAMESPACE with the name of the personal account or organization {% ifversion packages-nuget-v2 %}to which your packages are scoped{% else %}that owns the repository where your packages are hosted{% endif %}.{% ifversion ghes %}
  • HOSTNAME with the host name for {% data variables.location.product_location %}.{% endif %}

{% ifversion ghes %}If your instance has subdomain isolation enabled: {% endif %}

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="github" value="https://{% ifversion fpt or ghec %}nuget.pkg.github.com{% else %}nuget.HOSTNAME{% endif %}/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

{% ifversion ghes %} 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/NAMESPACE/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <github>
            <add key="Username" value="USERNAME" />
            <add key="ClearTextPassword" value="TOKEN" />
        </github>
    </packageSourceCredentials>
</configuration>

{% endif %}

Publishing a package

You can publish a package to {% data variables.product.prodname_registry %} by authenticating with a nuget.config file, using the --api-key command line option with your {% data variables.product.prodname_dotcom %} {% data variables.product.pat_v1 %} or by using command that can be run directly from the command line using the dotnet command-line interface (CLI).

Replace OWNER with your username or company name, and YOUR_GITHUB_PAT with your {% data variables.product.pat_generic %}.

dotnet nuget add source --username OWNER --password {% raw %}YOUR_GITHUB_PAT{% endraw %} --store-password-in-clear-text --name github "https://{% ifversion fpt or ghec %}nuget.pkg.github.com{% else %}nuget.HOSTNAME{% endif %}/OWNER/index.json"

{% ifversion packages-nuget-v2 %}

The 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.

{% data reusables.package_registry.publishing-user-scoped-packages %} For more information on linking a published package with a repository, see "AUTOTITLE."

If 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 "AUTOTITLE." For information on linking an already-published package to a repository, see "AUTOTITLE."

{% endif %}

Publishing a package using a GitHub {% data variables.product.pat_generic %} as your API key

If you don't already have a {% data variables.product.pat_generic %} to use for your account on {% data variables.product.github %}, see "AUTOTITLE."

  1. Create a new project. Replace PROJECT_NAME with the name you'd like to give the project.

    dotnet new console --name PROJECT_NAME

  2. Package the project.

    dotnet pack --configuration Release

  3. Publish the package using your {% data variables.product.pat_generic %} 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 {% data variables.product.pat_generic %}.

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

{% data reusables.package_registry.viewing-packages %}

Publishing a package using a nuget.config file

When publishing, {% ifversion packages-nuget-v2 %}if you are linking your package to a repository, {% endif %}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" in the Microsoft documentation.

{% data reusables.package_registry.auto-inherit-permissions-note %}

{% data reusables.package_registry.authenticate-step %}

  1. Create a new project. Replace PROJECT_NAME with the name you'd like to give the project.

    dotnet new console --name PROJECT_NAME

  2. Add your project's specific information to your project's file, which ends in .csproj. Make sure to replace:

    • 1.0.0 with the version number of the package.
    • OWNER with the name of the personal account or organization that owns the repository to which you want to {% ifversion packages-nuget-v2 %}link your package{% else %}publish your package{% endif %}.
    • REPOSITORY with the name of the repository to which you want to connect your package.{% ifversion ghes %}
    • HOSTNAME with the host name for {% data variables.location.product_location %}.{% endif %}
    <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://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

</Project>

  3. Package the project.

    dotnet pack --configuration Release

  4. 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.

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

{% data reusables.package_registry.viewing-packages %}

Publishing multiple packages to the same repository

To connect multiple packages to the same repository, use the same {% data variables.product.prodname_dotcom %} repository URL in the RepositoryURL fields in all .csproj project files. {% data variables.product.prodname_dotcom %} matches the repository based on that field.

The following example publishes the projects MY_APP and MY_OTHER_APP to the same repository:

<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://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/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://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/my-org/my-repo</RepositoryUrl>
  </PropertyGroup>

</Project>

Installing a package

Using packages from {% data variables.product.prodname_dotcom %} 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.

{% data reusables.package_registry.authenticate-step %}

  1. 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:

    <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://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/OWNER/REPOSITORY</RepositoryUrl>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="PACKAGE_NAME" Version="X.X.X" />
  </ItemGroup>

</Project>

  2. Install the packages with the restore command.

    dotnet restore

Troubleshooting

{% ifversion packages-nuget-v2 %}{% else %}Your NuGet package may fail to push if the RepositoryUrl in .csproj is not set to the expected repository.

If you're using a nuspec file, ensure that it has a repository element with the required type and url attributes.{% endif %}

If you're using a GITHUB_TOKEN to authenticate to a {% data variables.product.prodname_registry %} registry within a {% data variables.product.prodname_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 {% data variables.product.pat_v1 %} with the read:packages scope and pass this token in as a secret.

Further reading