2020-06-23 00:09:42 +05:30
---
stage: Package
group: Package
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
---
2021-03-11 19:13:27 +05:30
# NuGet packages in the Package Registry **(FREE)**
2020-03-13 15:44:24 +05:30
2021-03-11 19:13:27 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20050) in GitLab Premium 12.8.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Free in 13.3.
2020-03-13 15:44:24 +05:30
2021-04-29 21:17:54 +05:30
Publish NuGet packages in your project's Package Registry. Then, install the
2021-01-29 00:20:46 +05:30
packages whenever you need to use them as a dependency.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
The Package Registry works with:
2020-04-08 14:13:33 +05:30
- [NuGet CLI ](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference )
- [.NET Core CLI ](https://docs.microsoft.com/en-us/dotnet/core/tools/ )
- [Visual Studio ](https://visualstudio.microsoft.com/vs/ )
2020-03-13 15:44:24 +05:30
2021-04-29 21:17:54 +05:30
For documentation of the specific API endpoints that these
clients use, see the [NuGet API documentation ](../../../api/packages/nuget.md ).
2021-01-29 00:20:46 +05:30
## Install NuGet
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
The required minimum versions are:
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
- [NuGet CLI 5.1 or later ](https://www.nuget.org/downloads ). If you have
[Visual Studio ](https://visualstudio.microsoft.com/vs/ ), the NuGet CLI is
probably already installed.
- Alternatively, you can use [.NET SDK 3.0 or later ](https://dotnet.microsoft.com/download/dotnet-core/3.0 ),
which installs the NuGet CLI.
- NuGet protocol version 3 or later.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
Verify that the [NuGet CLI ](https://www.nuget.org/ ) is installed by running:
2020-03-13 15:44:24 +05:30
```shell
nuget help
```
2021-01-29 00:20:46 +05:30
The output should be similar to:
2020-03-13 15:44:24 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2021-01-03 14:25:43 +05:30
NuGet Version: 5.1.0.6013
2020-03-13 15:44:24 +05:30
usage: NuGet < command > [args] [options]
Type 'NuGet help < command > ' for help on a specific command.
Available commands:
[output truncated]
```
2021-01-29 00:20:46 +05:30
### Install NuGet on macOS
2020-10-24 23:57:45 +05:30
2021-01-29 00:20:46 +05:30
For macOS, you can use [Mono ](https://www.mono-project.com/ ) to run the
NuGet CLI.
2020-04-22 19:07:51 +05:30
2021-01-29 00:20:46 +05:30
1. If you use Homebrew, to install Mono, run `brew install mono` .
1. Download the Windows C# binary `nuget.exe` from the [NuGet CLI page ](https://www.nuget.org/downloads ).
1. Run this command:
2020-04-22 19:07:51 +05:30
2021-01-29 00:20:46 +05:30
```shell
mono nuget.exe
```
2020-03-13 15:44:24 +05:30
2021-03-08 18:12:59 +05:30
## Use the GitLab endpoint for NuGet Packages
2021-03-11 19:13:27 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36423) group-level endpoint in GitLab 13.8.
2021-03-08 18:12:59 +05:30
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.
2021-03-11 19:13:27 +05:30
- **Group-level**: Use when you have many NuGet packages in different projects within the
2021-03-08 18:12:59 +05:30
same GitLab group.
Some features such as [publishing ](#publish-a-nuget-package ) a package are only available on the project-level endpoint.
WARNING:
Because of how NuGet handles credentials, the Package Registry rejects anonymous requests on the group-level endpoint.
To work around this limitation, set up [authentication ](#add-the-package-registry-as-a-source-for-nuget-packages ).
2021-01-29 00:20:46 +05:30
## Add the Package Registry as a source for NuGet packages
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
To publish and install packages to the Package Registry, you must add the
Package Registry as a source for your packages.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
Prerequisites:
2020-03-13 15:44:24 +05:30
- Your GitLab username.
2020-05-24 23:13:21 +05:30
- A personal access token or deploy token. For repository authentication:
2021-01-29 00:20:46 +05:30
- You can generate a [personal access token ](../../../user/profile/personal_access_tokens.md )
with the scope set to `api` .
- You can generate a [deploy token ](../../project/deploy_tokens/index.md )
with the scope set to `read_package_registry` , `write_package_registry` , or
both.
- A name for your source.
2021-03-08 18:12:59 +05:30
- Depending on the [endpoint level ](#use-the-gitlab-endpoint-for-nuget-packages ) 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.
2020-03-13 15:44:24 +05:30
2020-04-08 14:13:33 +05:30
You can now add a new source to NuGet with:
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
- [NuGet CLI ](#add-a-source-with-the-nuget-cli )
- [Visual Studio ](#add-a-source-with-visual-studio )
- [.NET CLI ](#add-a-source-with-the-net-cli )
2020-04-08 14:13:33 +05:30
2021-01-29 00:20:46 +05:30
### Add a source with the NuGet CLI
2020-03-13 15:44:24 +05:30
2021-03-08 18:12:59 +05:30
#### Project-level endpoint
2021-03-11 19:13:27 +05:30
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.
2021-03-08 18:12:59 +05:30
To use the [project-level ](#use-the-gitlab-endpoint-for-nuget-packages ) NuGet endpoint, add the Package Registry as a source with `nuget` :
2020-03-13 15:44:24 +05:30
```shell
2021-01-29 00:20:46 +05:30
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 >
2020-03-13 15:44:24 +05:30
```
2021-01-29 00:20:46 +05:30
- `<source_name>` is the desired source name.
2020-03-13 15:44:24 +05:30
For example:
```shell
2021-01-29 00:20:46 +05:30
nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf
2020-03-13 15:44:24 +05:30
```
2021-03-08 18:12:59 +05:30
#### Group-level endpoint
2021-03-11 19:13:27 +05:30
To install a NuGet package from a group, use a group-level endpoint.
2021-03-08 18:12:59 +05:30
To use the [group-level ](#use-the-gitlab-endpoint-for-nuget-packages ) NuGet endpoint, add the Package Registry as a source with `nuget` :
```shell
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:
```shell
nuget source Add -Name "GitLab" -Source "https://gitlab.example.com/api/v4/groups/23/-/packages/nuget/index.json" -UserName carol -Password 12345678asdf
```
2021-01-29 00:20:46 +05:30
### Add a source with Visual Studio
2021-03-08 18:12:59 +05:30
#### Project-level endpoint
2021-03-11 19:13:27 +05:30
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.
2021-03-08 18:12:59 +05:30
To use the [project-level ](#use-the-gitlab-endpoint-for-nuget-packages ) NuGet endpoint, add the Package Registry as a source with Visual Studio:
2020-03-13 15:44:24 +05:30
1. Open [Visual Studio ](https://visualstudio.microsoft.com/vs/ ).
2021-01-29 00:20:46 +05:30
1. In Windows, select **File > Options** . On macOS, select **Visual Studio > Preferences** .
1. In the **NuGet** section, select **Sources** to view a list of all your NuGet sources.
1. Select **Add** .
1. 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.
2020-03-13 15:44:24 +05:30
![Visual Studio Adding a NuGet source ](img/visual_studio_adding_nuget_source.png )
1. Click **Save** .
2021-01-29 00:20:46 +05:30
The source is displayed in your list.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
![Visual Studio NuGet source added ](img/visual_studio_nuget_source_added.png )
2020-04-08 14:13:33 +05:30
2021-01-29 00:20:46 +05:30
If you get a warning, ensure that the **Location** , **Username** , and
**Password** are correct.
2020-04-08 14:13:33 +05:30
2021-03-08 18:12:59 +05:30
#### Group-level endpoint
2021-03-11 19:13:27 +05:30
To install a package from a group, use a group-level endpoint.
2021-03-08 18:12:59 +05:30
To use the [group-level ](#use-the-gitlab-endpoint-for-nuget-packages ) NuGet endpoint, add the Package Registry as a source with Visual Studio:
1. Open [Visual Studio ](https://visualstudio.microsoft.com/vs/ ).
1. In Windows, select **File > Options** . On macOS, select **Visual Studio > Preferences** .
1. In the **NuGet** section, select **Sources** to view a list of all your NuGet sources.
1. Select **Add** .
1. 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.
![Visual Studio Adding a NuGet source ](img/visual_studio_adding_nuget_source.png )
1. Click **Save** .
The source is displayed in your list.
![Visual Studio NuGet source added ](img/visual_studio_nuget_source_added.png )
If you get a warning, ensure that the **Location** , **Username** , and
**Password** are correct.
2021-01-29 00:20:46 +05:30
### Add a source with the .NET CLI
2020-04-08 14:13:33 +05:30
2021-03-08 18:12:59 +05:30
#### Project-level endpoint
2021-03-11 19:13:27 +05:30
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.
2021-03-08 18:12:59 +05:30
To use the [project-level ](#use-the-gitlab-endpoint-for-nuget-packages ) Package Registry as a source for .NET:
2021-01-29 00:20:46 +05:30
1. In the root of your project, create a file named `nuget.config` .
1. Add this content:
```xml
<?xml version="1.0" encoding="utf-8"?>
< configuration >
2020-04-08 14:13:33 +05:30
< packageSources >
< clear / >
2021-04-17 20:07:23 +05:30
< add key = "gitlab" value = "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" / >
2021-03-08 18:12:59 +05:30
< / packageSources >
< packageSourceCredentials >
< gitlab >
< add key = "Username" value = "<gitlab_username or deploy_token_username>" / >
< add key = "ClearTextPassword" value = "<gitlab_personal_access_token or deploy_token>" / >
< / gitlab >
< / packageSourceCredentials >
< / configuration >
```
#### Group-level endpoint
2021-03-11 19:13:27 +05:30
To install a package from a group, use a group-level endpoint.
2021-03-08 18:12:59 +05:30
To use the [group-level ](#use-the-gitlab-endpoint-for-nuget-packages ) Package Registry as a source for .NET:
1. In the root of your project, create a file named `nuget.config` .
1. Add this content:
```xml
<?xml version="1.0" encoding="utf-8"?>
< configuration >
< packageSources >
< clear / >
< add key = "gitlab" value = "https://gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/nuget/index.json" / >
2020-04-08 14:13:33 +05:30
< / packageSources >
< packageSourceCredentials >
< gitlab >
2020-05-24 23:13:21 +05:30
< add key = "Username" value = "<gitlab_username or deploy_token_username>" / >
< add key = "ClearTextPassword" value = "<gitlab_personal_access_token or deploy_token>" / >
2020-04-08 14:13:33 +05:30
< / gitlab >
< / packageSourceCredentials >
2021-01-29 00:20:46 +05:30
< / configuration >
```
## Publish a NuGet package
2020-04-08 14:13:33 +05:30
2021-03-08 18:12:59 +05:30
Prerequisite:
- Set up the [source ](#https://docs.gitlab.com/ee/user/packages/nuget_repository/#add-the-package-registry-as-a-source-for-nuget-packages ) with a [project-level endpoint ](#use-the-gitlab-endpoint-for-nuget-packages ).
2021-01-29 00:20:46 +05:30
When publishing packages:
2020-04-08 14:13:33 +05:30
2021-03-11 19:13:27 +05:30
- The Package Registry on GitLab.com can store up to 5 GB of content.
2021-01-29 00:20:46 +05:30
This limit is [configurable for self-managed GitLab instances ](../../../administration/instance_limits.md#package-registry-limits ).
- If you publish the same package with the same version multiple times, each
consecutive upload is saved as a separate file. When installing a package,
GitLab serves the most recent file.
- When publishing packages to GitLab, they aren't displayed in the packages user
interface of your project immediately. It can take up to 10 minutes to process
a package.
2020-04-08 14:13:33 +05:30
2021-01-29 00:20:46 +05:30
### Publish a package with the NuGet CLI
2020-04-08 14:13:33 +05:30
2021-03-08 18:12:59 +05:30
Prerequisites:
2020-04-08 14:13:33 +05:30
2021-01-29 00:20:46 +05:30
- [A NuGet package created with NuGet CLI ](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package ).
2021-03-08 18:12:59 +05:30
- Set a [project-level endpoint ](#use-the-gitlab-endpoint-for-nuget-packages ).
2021-01-29 00:20:46 +05:30
Publish a package by running this command:
2020-04-08 14:13:33 +05:30
```shell
nuget push < package_file > -Source < source_name >
```
- `<package_file>` is your package filename, ending in `.nupkg` .
2021-01-29 00:20:46 +05:30
- `<source_name>` is the [source name used during setup ](#add-a-source-with-the-nuget-cli ).
### Publish a package with the .NET CLI
2021-03-08 18:12:59 +05:30
Prerequisites:
2020-04-08 14:13:33 +05:30
2021-02-22 17:27:13 +05:30
- [A NuGet package created with .NET CLI ](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package-dotnet-cli ).
2021-03-08 18:12:59 +05:30
- Set a [project-level endpoint ](#use-the-gitlab-endpoint-for-nuget-packages ).
2020-04-08 14:13:33 +05:30
2021-01-29 00:20:46 +05:30
Publish a package by running this command:
2020-04-08 14:13:33 +05:30
```shell
dotnet nuget push < package_file > --source < source_name >
```
- `<package_file>` is your package filename, ending in `.nupkg` .
2021-01-29 00:20:46 +05:30
- `<source_name>` is the [source name used during setup ](#add-a-source-with-the-net-cli ).
2020-04-08 14:13:33 +05:30
For example:
```shell
dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab
```
2021-01-29 00:20:46 +05:30
### Publish a NuGet package by using CI/CD
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36424) in GitLab 13.3.
2021-04-29 21:17:54 +05:30
If you're using NuGet with GitLab CI/CD, a CI job token can be used instead of a
2021-01-29 00:20:46 +05:30
personal access token or deploy token. The token inherits the permissions of the
user that generates the pipeline.
This example shows how to create a new package each time the `master` branch is
updated:
1. Add a `deploy` job to your `.gitlab-ci.yml` file:
```yaml
image: mcr.microsoft.com/dotnet/core/sdk:3.1
stages:
- deploy
deploy:
stage: deploy
script:
- dotnet pack -c Release
2021-09-04 01:27:46 +05:30
- dotnet nuget add source "${CI_API_V4_URL}/${CI_PROJECT_ID}/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
2021-01-29 00:20:46 +05:30
- dotnet nuget push "bin/Release/*.nupkg" --source gitlab
only:
- master
```
1. Commit the changes and push it to your GitLab repository to trigger a new CI/CD build.
2021-03-11 19:13:27 +05:30
### Publishing a package with the same name or version
When you publish a package with the same name or version as an existing package,
the existing package is overwritten.
2020-04-08 14:13:33 +05:30
## Install packages
2021-03-11 19:13:27 +05:30
To install a NuGet package from the Package Registry, you must first
[add a project-level or group-level endpoint ](#add-the-package-registry-as-a-source-for-nuget-packages ).
If multiple packages have the same name and version, when you install
a package, the most recently-published package is retrieved.
2021-01-29 00:20:46 +05:30
### Install a package with the NuGet CLI
2020-04-08 14:13:33 +05:30
2021-02-22 17:27:13 +05:30
WARNING:
2021-01-29 00:20:46 +05:30
By default, `nuget` checks the official source at `nuget.org` first. If you have
a NuGet package in the Package Registry with the same name as a package at
`nuget.org` , you must specify the source name to install the correct package.
2020-04-22 19:07:51 +05:30
2021-01-29 00:20:46 +05:30
Install the latest version of a package by running this command:
2020-04-08 14:13:33 +05:30
```shell
nuget install < package_id > -OutputDirectory < output_directory > \
-Version < package_version > \
-Source < source_name >
```
2020-05-24 23:13:21 +05:30
- `<package_id>` is the package ID.
2020-10-24 23:57:45 +05:30
- `<output_directory>` is the output directory, where the package is installed.
2021-01-29 00:20:46 +05:30
- `<package_version>` The package version. Optional.
- `<source_name>` The source name. Optional.
2020-04-08 14:13:33 +05:30
2021-01-29 00:20:46 +05:30
### Install a package with the .NET CLI
2020-04-08 14:13:33 +05:30
2021-02-22 17:27:13 +05:30
WARNING:
2021-01-29 00:20:46 +05:30
If you have a package in the Package Registry with the same name as a package at
a different source, verify the order in which `dotnet` checks sources during
install. This is defined in the `nuget.config` file.
2020-04-08 14:13:33 +05:30
2021-01-29 00:20:46 +05:30
Install the latest version of a package by running this command:
2020-04-08 14:13:33 +05:30
```shell
dotnet add package < package_id > \
-v < package_version >
```
2020-05-24 23:13:21 +05:30
- `<package_id>` is the package ID.
2021-01-29 00:20:46 +05:30
- `<package_version>` is the package version. Optional.
2021-04-29 21:17:54 +05:30
## Supported CLI commands
The GitLab NuGet repository supports the following commands for the NuGet CLI (`nuget`) and the .NET
CLI (`dotnet`):
- `nuget push` : Upload a package to the registry.
- `dotnet nuget push` : Upload a package to the registry.
- `nuget install` : Install a package from the registry.
- `dotnet add` : Install a package from the registry.