GitLab NuGet Repository (PREMIUM)

Introduced in GitLab Premium 12.8.

With the GitLab NuGet Repository, every project can have its own space to store NuGet packages.

The GitLab NuGet Repository works with:

Setting up your development environment

You will need NuGet CLI 5.2 or later. Earlier versions have not been tested against the GitLab NuGet Repository and might not work. If you have Visual Studio, NuGet CLI is probably already installed.

Alternatively, you can use .NET SDK 3.0 or later, which installs NuGet CLI.

You can confirm that NuGet CLI is properly installed with:

nuget help

You should see something similar to:

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

Available commands:

[output truncated]

macOS support

For macOS, you can also use Mono to run the NuGet CLI. For Homebrew users, run brew install mono to install Mono. Then you should be able to download the Windows C# binary nuget.exe from the NuGet CLI page and run:

mono nuget.exe

Enabling the NuGet Repository

NOTE: Note: This option is available only if your GitLab administrator has enabled support for the Package Registry. (PREMIUM ONLY)

After the NuGet Repository is enabled, it will be available for all new projects by default. To enable it for existing projects, or if you want to disable it:

Navigate to your project's Settings > General > Permissions.
Find the Packages feature and enable or disable it.
Click on Save changes for the changes to take effect.

You should then be able to see the Packages & Registries section on the left sidebar.

Adding the GitLab NuGet Repository as a source to NuGet

You will need the following:

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 suitable name for your source.
Your project ID which can be found on the home page of your project.

You can now add a new source to NuGet with:

NuGet CLI
Visual Studio.
.NET CLI

Add NuGet Repository source with NuGet CLI

To add the GitLab NuGet Repository as a source with nuget:

nuget source Add -Name <source_name> -Source "https://gitlab-instance.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>

Where:

<source_name> is your desired source name.

For example:

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

Add NuGet Repository source with Visual Studio

Open Visual Studio.
Open the FILE > OPTIONS (Windows) or Visual Studio > Preferences (Mac OS).
In the NuGet section, open Sources. You will see a list of all your NuGet sources.
Click Add.
Fill the fields with:
- Name: Desired name for the source
- Location: https://gitlab.com/api/v4/projects/<your_project_id>/packages/nuget/index.json
  - Replace <your_project_id> with your project ID.
  - If you have a self-managed GitLab installation, replace gitlab.com with your domain name.
- Username: Your GitLab username or deploy token username
- Password: Your personal access token or deploy token
Click Save.

In case of any warning, please make sure that the Location, Username, and Password are correct.

Add NuGet Repository source with .NET CLI

To add the GitLab NuGet Repository as a source for .NET, create a file named nuget.config in the root of your project with the following content:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <packageSources>
        <clear />
        <add key="gitlab" value="https://gitlab-instance.example.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" />
    </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>

Uploading packages

When uploading packages, note that:

The maximum allowed size is 50 Megabytes.
If you upload the same package with the same version multiple times, each consecutive upload is saved as a separate file. When installing a package, GitLab will serve the most recent file.
When uploading packages to GitLab, they will not be displayed in the packages UI of your project immediately. It can take up to 10 minutes to process a package.

Upload packages with NuGet CLI

This section assumes that your project is properly built and you already created a NuGet package with NuGet CLI. Upload your package using the following command:

nuget push <package_file> -Source <source_name>

Where:

<package_file> is your package filename, ending in .nupkg.
<source_name> is the source name used during setup.

Upload packages with .NET CLI

This section assumes that your project is properly built and you already created a NuGet package with .NET CLI. Upload your package using the following command:

dotnet nuget push <package_file> --source <source_name>

Where:

<package_file> is your package filename, ending in .nupkg.
<source_name> is the source name used during setup.

For example:

dotnet nuget push MyPackage.1.0.0.nupkg --source gitlab

Install packages

Install a package with NuGet CLI

CAUTION: Warning: By default, nuget checks the official source at nuget.org first. If you have a package in the GitLab NuGet Repository with the same name as a package at nuget.org, you must specify the source name or the wrong package will be installed.

Install the latest version of a package using the following command:

nuget install <package_id> -OutputDirectory <output_directory> \
  -Version <package_version> \
  -Source <source_name>

Where:

<package_id> is the package ID.
<output_directory> is the output directory, where the package will be installed.
<package_version> (Optional) is the package version.
<source_name> (Optional) is the source name.

Install a package with .NET CLI

CAUTION: Warning: If you have a package in the GitLab NuGet Repository with the same name as a package at a different source, you should verify the order in which dotnet checks sources during install. This is defined in the nuget.config file.

Install the latest version of a package using the following command:

dotnet add package <package_id> \
       -v <package_version>

Where:

<package_id> is the package ID.
<package_version> (Optional) is the package version.