Supported Formats

NuGet Feed

Cloudsmith provides public & private feeds for NuGet.

NuGet is an open-source package manager designed for the Microsoft development technologies.

The NuGet repository support at Cloudsmith is compatible with Chocolatey, so if you're looking to manage packages on Windows, that's our recommended approach.

NuGet Symbol Server

Visit the NuGet Symbol Server documentation page for more information about NuGet debugging symbols (PDB files) and source files for packages published.

For more information on NuGet, please see:

• NuGet: The official website for NuGet
• NuGet Packages: The official package repository guide for NuGet
• Introduction to NuGet: Official guide to getting started with NuGet

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy and paste snippets (with your namespace/repo/rsa-key pre-configured).

In the following examples:

Upload a Package

Before you can upload, you need to create your NuGet package using the NuGet CLI or the .NET Core CLI:

Required project file

This assumes that you've created a compatible project.csproj file for your project.

nuget pack

dotnet pack

This generates a nupkg (.nupkg) file like your-package-1.2.3.nupkg that you can upload.

Upload via native NuGet Tooling

The endpoint for the native NuGet API is:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/

You can upload your package using the NuGet CLI or the .NET Core CLI.

NuGet CLI
You can publish a nupkg file that you've generated from your project, using nuget.
As a shortcut, you can set up the source (upstream) ahead of time, using nuget source:

nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Then you can publish your package using:

nuget push PACKAGE_NAME-PACKAGE_VERSION.nupkg -Source example-repo -ApiKey API-KEY

.NET Core CLI
You can publish a nupkg file that you've generated from your project, using dotnet:

dotnet nuget push PACKAGE_NAME-VERSION.nupkg -k API-KEY -s https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a NuGet package via the Cloudsmith CLI is:

cloudsmith push nuget OWNER/REPOSITORY PACKAGE_NAME-PACKAGE_VERSION.nupkg

Example:

cloudsmith push nuget your-account/your-repo your-package-1.0.0.nupkg

Upload via Cloudsmith web app

Please see Upload a Package for details of how to upload via the Cloudsmith web app.

Example Project

For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub). We'll supplement these with more detailed guidance later, but otherwise just ask, we're here to help.

Download / Install a Package

Setup

To consume packages in NuGet from a Cloudsmith NuGet Feed , you'll need to configure it as a source:

Public Repositories

NuGet CLI

nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

.NET Core CLI
When specifying the source in commands via -s, use the following URL:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Paket CLI
You can add the source to your paket.dependencies file:

source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

If you don't want to check your username into source control, you can use environment variables instead

VS Package Manager (PM)
When specifying the source in commands via -Source, use the following URL:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Private Repositories

Private Repositories

Private Cloudsmith repositories require authentication. You can choose between two types of authentication, Entitlement Token Authentication or HTTP Basic Authentication. The setup method will differ depending on what authentication type you choose to use.

Warning

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code, or expose them in any logs.

NuGet CLI

nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username token -Password TOKEN -StorePasswordInClearText

nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username USERNAME -Password PASSWORD -StorePasswordInClearText

nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username USERNAME -Password API-KEY -StorePasswordInClearText

nuget sources add -Name example-repo -Source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json -Username token -Password TOKEN -StorePasswordInClearText

.NET Core CLI
When specifying the source in commands via -s, use the following URL:

https://token:TOKEN@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

https://USERNAME:PASSWORD@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

https://USERNAME:API-KEY@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

https://token:TOKEN@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Paket CLI
You can add the source to your paket.dependencies file:

source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "token" password: "TOKEN" authtype: "basic"

source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "USERNAME" password: "PASSWORD" authtype: "basic"

source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "USERNAME" password: "API-KEY" authtype: "basic"

source https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json username: "token" password: "TOKEN" authtype: "basic"

If you don't want to check your username into source control, you can use environment variables instead.

VS Package Manager (PM)
When specifying the source in commands via -Source, use the following URL:

https://nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

https://USERNAME:PASSWORD@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

https://USERNAME:API-KEY@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

https://token:TOKEN@nuget.cloudsmith.io/OWNER/REPOSITORY/v3/index.json

Install a Package

To install the latest version of a package you would use:

NuGet CLI

nuget install PACKAGE_NAME -Source example-repo -DependencyVersion Highest

.NET Core CLI

dotnet add package PACKAGE_NAME -s https://nuget.cloudsmith.io/OWNER/REPOSITOY/v3/index.json

Paket CLI

paket add nuget PACKAGE_NAME

VS Package Manager (PM)

Install-Package PACKAGE_NAME -Source example-repo

Current Limitations

The Cloudsmith NuGet feed implementation has the following limitations:

• The maximum size per-package file is limited to 200MiB (~210 megabytes), but only when utilising the native nuget-cli for publishing. If uploading using the cloudsmith-cli, then the absolute maximum size per-package file limit will be the standard 5GiB.

Security Scanning

Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

You can configure upstream NuGet feeds that you wish to use for packages that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.

Please see our Upstream Proxying documentation for further instructions.

Signing NuGet Packages

Cloudsmith supports natively signing all NuGet packages using an X.509 certificate, enabling consumers to verify package repository signatures in native tooling or the NuGet CLI command, ensuring the integrity and authenticity of the packages.

To get started, navigate to Repository Settings >> Miscellaneous, and check the box "NuGet Native Signing Enabled?":

Signing of existing packages

Packages uploaded prior to enabling NuGet Native Signing will not be signed or have a certificate in the index. Once this setting is enabled, you will need to resync existing NuGet packages to sign them.

How it works

When native NuGet signing is enabled for a Cloudsmith repository, a unique X.509 certificate is issued for that repository.

When a NuGet package is uploaded or resynced to that repository, Cloudsmith will create a repository signature. The certificate will be available in the RepositorySignatures resource in the service index. If a NuGet package contains an author signature, Cloudsmith will countersign the package.

If the repository upstream NuGet repositories configured, Cloudsmith will index the RepositorySignature endpoint from the Nuget service index. The upstream repository's signing certificates will then be available for client-side verification as well.

Client-side verification

To enable client-side verification, the trusted certificates need to be added to the consumer's machine. Cloudsmith issues signing certificates using our own Certificate Authority. The Certificate Authority chain will need to be added to NuGet's trusted roots bundle.

Linux and MacOS

For Linux and MacOS, this is located at: /usr/local/share/dotnet/sdk/\<NUGET_SDK_VERSION>/trustedroots/codesignctl.pem

Windows

For Windows, this is managed by the operating system. Please reference Microsoft's Trusted Root Certification Authorities Certificate Store for more information.

You can download Cloudsmith’s root Certificate Authority chain by going to the Key Management tab in your repository or by calling the x509-rsa API endpoint.

Troubleshooting

Q. I'm unable to authenticate using HTTP Basic Authentication with a password or with an entitlement token. I'm using dotnet core SDK 2.2

This is the error:

Unable to get repository signature information for source
https://nuget.cloudsmith.io/YOUR-ACCOUNT/YOUR-REPO/v3-index/repository-signatures/X.X.X/index.json
error : Response status code does not indicate success: 401 (Unauthorized)

It looks like this (not being able to use username/password directly on a source) might be an accepted bug in dotnet 2.2, possibly fixed later, as referenced in the following GitHub issues:

• https://github.com/dotnet/cli/issues/10356
• https://github.com/NuGet/Home/issues/4668

SOLUTION
Add the source using nuget sources as follows first::

nuget sources add -Name NAME -source https://nuget.cloudsmith.io/YOUR-ACCOUNT/YOUR-REPO/v3/index.json -Username YOUR-USERNAME -Password YOUR-API-KEY-OR-PASSWORD -StorePasswordInClearText

Then do dotnet restore like:

dotnet restore -s https://nuget.cloudsmith.io/YOUR-ACCOUNT/YOUR-REPO/v3/index.json --configfile ~/config/NuGet/NuGet.Config

If you want to use an Entitlement Token instead of a username and password/API-Key, use "token" for the username and an Entitlement Token as the password.

Still Need Help?

Contact us here. We're always happy to help.

Updated 4 weeks ago