• Install NuGet
  • Install NuGet on macOS
• Use the GitLab endpoint for NuGet Packages
• Add the Package Registry as a source for NuGet packages
  • Add a source with the NuGet CLI
    • Project-level endpoint
    • Group-level endpoint
  • Add a source with Visual Studio
    • Project-level endpoint
    • Group-level endpoint
  • Add a source with the .NET CLI
    • Project-level endpoint
    • Group-level endpoint
  • Add a source with a configuration file
    • Project-level endpoint
    • Group-level endpoint
• Publish a NuGet package
  • Publish a package with the NuGet CLI
  • Publish a package with the .NET CLI
  • Publish a NuGet package by using CI/CD
  • Publishing a package with the same name or version
• Install packages
  • Install a package with the NuGet CLI
  • Install a package with the .NET CLI
• Symbol packages
• Supported CLI commands
• Example project
• Troubleshooting

NuGet packages in the Package Registry

Publish NuGet packages in your project’s Package Registry. Then, install the packages whenever you need to use them as a dependency.

The Package Registry works with:

• NuGet CLI
• .NET Core CLI
• Visual Studio

For documentation of the specific API endpoints that these clients use, see the NuGet API documentation.

Install NuGet

The required minimum versions are:

• NuGet CLI 5.1 or later. If you have Visual Studio, the NuGet CLI is probably already installed.
• Alternatively, you can use .NET SDK 3.0 or later, which installs the NuGet CLI.
• NuGet protocol version 3 or later.

Verify that the NuGet CLI is installed by running:

nuget help

The output should be similar to:

NuGet Version: 5.1.0.6013
usage: NuGet <command> [args] [options]
Type 'NuGet help <command>' for help on a specific command.

Available commands:

[output truncated]

Install NuGet on macOS

For macOS, you can use Mono to run the NuGet CLI.

1. If you use Homebrew, to install Mono, run brew install mono.
2. Download the Windows C# binary nuget.exe from the NuGet CLI page.

3. Run this command:

   mono nuget.exe
   

Use the GitLab endpoint for NuGet Packages

To use the GitLab endpoint for NuGet Packages, choose an option:

• Project-level: Use when you have few NuGet packages and they are not in the same GitLab group.
• Group-level: Use when you have many NuGet packages in different projects within the same GitLab group.

Some features such as publishing a package are only available on the project-level endpoint.

When asking for versions of a given NuGet package name, the GitLab Package Registry returns a maximum of 300 most recent versions.

Add the Package Registry as a source for NuGet packages

To publish and install packages to the Package Registry, you must add the Package Registry as a source for your packages.

Prerequisites:

• Your GitLab username.
• A personal access token or deploy token. For repository authentication:
  • You can generate a personal access token with the scope set to api.
  • You can generate a deploy token with the scope set to read_package_registry, write_package_registry, or both.
• A name for your source.
• Depending on the endpoint level you use, either:
  • Your project ID, which is found on your project’s home page.
  • Your group ID, which is found on your group’s home page.

You can now add a new source to NuGet with:

• NuGet CLI
• Visual Studio
• .NET CLI
• Configuration file

Add a source with the NuGet CLI

Project-level endpoint

A project-level endpoint is required to publish NuGet packages to the Package Registry. A project-level endpoint is also required to install NuGet packages from a project.

To use the project-level NuGet endpoint, add the Package Registry as a source with nuget:

nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token>

• <source_name> is the desired source name.

For example:

nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf

Group-level endpoint

To install a NuGet package from a group, use a group-level endpoint.

To use the group-level NuGet endpoint, add the Package Registry as a source with nuget:

nuget source Add -Name <source_name> -Source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" -UserName <gitlab_username or deploy_token_username> -Password <gitlab_personal_access_token or deploy_token>

• <source_name> is the desired source name.

For example:

nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" -UserName carol -Password 12345678asdf

Add a source with Visual Studio

Project-level endpoint

A project-level endpoint is required to publish NuGet packages to the Package Registry. A project-level endpoint is also required to install NuGet packages from a project.

To use the project-level NuGet endpoint, add the Package Registry as a source with Visual Studio:

1. Open Visual Studio.
2. In Windows, select File > Options. On macOS, select Visual Studio > Preferences.
3. In the NuGet section, select Sources to view a list of all your NuGet sources.
4. Select Add.
5. Complete the following fields:
   • Name: Name for the source.
   • Location: https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json, where <your_project_id> is your project ID, and gitlab.example.com is your domain name.
   • Username: Your GitLab username or deploy token username.
   • Password: Your personal access token or deploy token.

   

6. Select Save.

The source is displayed in your list.

If you get a warning, ensure that the Location, Username, and Password are correct.

Group-level endpoint

To install a package from a group, use a group-level endpoint.

To use the group-level NuGet endpoint, add the Package Registry as a source with Visual Studio:

1. Open Visual Studio.
2. In Windows, select File > Options. On macOS, select Visual Studio > Preferences.
3. In the NuGet section, select Sources to view a list of all your NuGet sources.
4. Select Add.
5. Complete the following fields:
   • Name: Name for the source.
   • Location: https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json, where <your_group_id> is your group ID, and gitlab.example.com is your domain name.
   • Username: Your GitLab username or deploy token username.
   • Password: Your personal access token or deploy token.

   

6. Select Save.

The source is displayed in your list.

If you get a warning, ensure that the Location, Username, and Password are correct.

Add a source with the .NET CLI

Project-level endpoint

A project-level endpoint is required to publish NuGet packages to the Package Registry. A project-level endpoint is also required to install NuGet packages from a project.

To use the project-level NuGet endpoint, add the Package Registry as a source with nuget:

dotnet nuget add source "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token>

• <source_name> is the desired source name.
• --store-password-in-clear-text might be necessary depending on your operating system.

For example:

dotnet nuget add source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" --name gitlab --username carol --password 12345678asdf

Group-level endpoint

To install a NuGet package from a group, use a group-level endpoint.

To use the group-level NuGet endpoint, add the Package Registry as a source with nuget:

dotnet nuget add source "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" --name <source_name> --username <gitlab_username or deploy_token_username> --password <gitlab_personal_access_token or deploy_token>

• <source_name> is the desired source name.
• --store-password-in-clear-text might be necessary depending on your operating system.

For example:

dotnet nuget add source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" --name gitlab --username carol --password 12345678asdf

Add a source with a configuration file

Project-level endpoint

A project-level endpoint is required to:

• Publish NuGet packages to the Package Registry.
• Install NuGet packages from a project.

To use the project-level Package Registry as a source for .NET:

1. In the root of your project, create a file named nuget.config.

2. Add this content:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
    <packageSources>
        <clear />
        <add key="gitlab" value="https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" />
    </packageSources>
    <packageSourceCredentials>
        <gitlab>
            <add key="Username" value="%GITLAB_PACKAGE_REGISTRY_USERNAME%" />
            <add key="ClearTextPassword" value="%GITLAB_PACKAGE_REGISTRY_PASSWORD%" />
        </gitlab>
    </packageSourceCredentials>
   </configuration>
   

3. Configure the necessary environment variables: