- Install NuGet
- Use the GitLab endpoint for NuGet Packages
- Add the Package Registry as a source for NuGet packages
- Publish a NuGet package
- Install packages
- Symbol packages
- Supported CLI commands
- Example project
- Troubleshooting
NuGet packages in the Package Registry
- Introduced in GitLab 12.8.
- Moved from GitLab Premium to GitLab Free in 13.3.
- Symbol package support added in GitLab 14.1.
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:
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.
- If you use Homebrew, to install Mono, run
brew install mono
. - Download the Windows C# binary
nuget.exe
from the NuGet CLI page. -
Run this command:
mono nuget.exe
Use the GitLab endpoint for NuGet Packages
Introduced group-level endpoint in GitLab 13.8.
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.
- You can generate a personal access token
with the scope set to
- 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:
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:
- Open Visual Studio.
- In Windows, select File > Options. On macOS, select Visual Studio > Preferences.
- In the NuGet section, select Sources to view a list of all your NuGet sources.
- Select Add.
- 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, andgitlab.example.com
is your domain name. - Username: Your GitLab username or deploy token username.
- Password: Your personal access token or deploy token.
- 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:
- Open Visual Studio.
- In Windows, select File > Options. On macOS, select Visual Studio > Preferences.
- In the NuGet section, select Sources to view a list of all your NuGet sources.
- Select Add.
- 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, andgitlab.example.com
is your domain name. - Username: Your GitLab username or deploy token username.
- Password: Your personal access token or deploy token.
- 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:
- In the root of your project, create a file named
nuget.config
. -
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>
-
Configure the necessary environment variables: