NuGet

Publish a package

The following subsections describe the processes in the code boxes above, serving the following use cases:

• Single command (Quick start section)—for rapid NuGet package publishing, using a temporary token.
• Ongoing publishing (Setup section)—implements configurations for a more permanent NuGet package publishing solution.

Single command

The first code box provides a quick mechanism for uploading a NuGet package to your NuGet registry.

dotnet nuget push *.nupkg --api-key "temporary-write-token-that-expires-after-5-minutes" \
  --source "https://packages.buildkite.com/{org.slug}/{registry.slug}/nuget/package"

where:

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the slug of your NuGet source registry, which is the kebab-case version of your NuGet registry name, and can be obtained after accessing Package Registries in the global navigation > your NuGet source registry from the Registries page.

Since the temporary-write-token-that-expires-after-5-minutes expires quickly, it is recommended that you just copy this command directly from the Publish Instructions page.

Ongoing publishing

The remaining code boxes on the Publish Instructions page provide configurations for a more permanent solution for ongoing NuGet uploads to your NuGet registry.

1. Create a nuget.config file in your project (if one doesn't already exist):

   dotnet new nugetconfig
   

2. Copy the following command, paste it and modify as required before running to add the NuGet registry to your nuget.config file:

   dotnet nuget add source https://packages.buildkite.com/{org.slug}/{registry.slug}/nuget/index.json \
     --name {org.slug}_{registry.slug} \
     --username _ \
     --password $TOKEN \
     --store-password-in-clear-text \
     --configfile ./nuget.config \
   

   where:

   • {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.
   • {registry.slug} is the slug of your NuGet source registry, which is the kebab-case version of your NuGet registry name, and can be obtained after accessing Package Registries in the global navigation > your NuGet source registry from the Registries page.
   • $TOKEN is your API access token used to publish/upload packages to your NuGet source registry. Ensure this access token has the Read Packages and Write Packages REST API scopes, which allows this token to publish packages to any source registry your user account has access to within your Buildkite organization.

   Note: This step only needs to be conducted once for the life of your NuGet source registry.

3. Publish your NuGet package:

   dotnet nuget push *.nupkg --source {org.slug}_{registry.slug} --api-key $TOKEN
   

Access a package's details

A NuGet package's details can be accessed from its source registry through the Releases (tab) section of your NuGet source registry page. To do this:

1. Select Package Registries in the global navigation to access the Registries page.
2. Select your NuGet source registry on this page.
3. On your NuGet source registry page, select the package within the Releases (tab) section. The package's details page is displayed.

The package's details page provides the following information in the following sections:

• Installation (tab): the installation instructions.
• Contents (tab, where available): a list of directories and files contained within the package.
• Details (tab): a list of checksum values for this package—MD5, SHA1, SHA256, and SHA512.
• About this version: a brief (metadata) description about the package.

• Details: details about:

  • the name of the package (typically the file name excluding any version details and extension).
  • the package version.
  • the source registry the package is located in.
  • the package's visibility (based on its registry's visibility)—whether the package is Private and requires authentication to access, or is publicly accessible.
  • the distribution name / version.
  • additional optional metadata contained within the package, such as a homepage, licenses, etc.

• Pushed: the date when the last package was uploaded to the source registry.

• Total files: the total number of files (and directories) within the package.

• Dependencies: the number of dependency packages required by this package.

• Package size: the storage size (in bytes) of this package.

• Downloads: the number of times this package has been downloaded.

Downloading a package

A NuGet package can be downloaded from the package's details page.

To download a package:

1. Access the package's details.
2. Select Download.

Installing a package

A NuGet package can be installed using code snippet details provided on the package's details page.

To install a package:

1. Access the package's details.
2. Ensure the Installation tab is displayed.
3. Follow the relevant section to install the NuGet package, based on your requirements:
   • Single command (Quick install section)—for rapid NuGet package installation, using a temporary token.
   • Ongoing publishing (Setup section)—implements configurations for a more permanent NuGet package installation solution.

Package installation with a single command

The Quick install code snippet is based on this format:

dotnet add package package-name -v version.number \
  --source "https://buildkite:temporary-read-token-that-expires-after-5-minutes@packages.buildkite.com/{org.slug}/{registry.slug}/nuget/index.json"

where:

• package-name is the name of your NuGet package.

• version.number is the version of your NuGet package.

• {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.

• {registry.slug} is the name of your NuGet registry.

Since the temporary-read-token-that-expires-after-5-minutes expires quickly, it is recommended that you just copy this command directly from the Installation page.

Ongoing package installation

The Setup section's instructions are as follows:

1. Create a nuget.config file in your project (if one doesn't already exist):

   dotnet new nugetconfig
   

2. Copy the following command, paste it and modify as required before running to add the NuGet registry to your nuget.config file:

   dotnet nuget add source https://packages.buildkite.com/{org.slug}/{registry.slug}/nuget/index.json \
     --name {registry.slug} \
     --username _ \
     --password $TOKEN \
     --store-password-in-clear-text \
     --configfile ./nuget.config \
     --valid-authentication-types basic
   

   where:

   • $TOKEN is your API access token or registry token used to download packages to your NuGet registry. Ensure this access token has the Read Packages REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This command option and value are not required for registries that are publicly accessible.
   • {org.slug} can be obtained from the end of your Buildkite URL, after accessing Package Registries or Pipelines in the global navigation of your organization in Buildkite.
   • {registry.slug} is the slug of your NuGet source registry, which is the kebab-case version of your NuGet registry name, and can be obtained after accessing Package Registries in the global navigation > your NuGet source registry from the Registries page.

   Note: This step only needs to be conducted once for the life of your NuGet source registry.

3. Publish your NuGet package:

   dotnet nuget push *.nupkg --source {registry.slug} --api-key $TOKEN