GitLab NuGet Repository

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]

Enabling the NuGet Repository

Note: This option is available only if your GitLab administrator has enabled support for the Package Registry.

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:

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

You should then be able to see the Packages 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. You can generate a personal access token with the scope set to api for repository authentication.
  • 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:

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> -Password <gitlab_personal_access_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

  1. Open Visual Studio.
  2. Open the FILE > OPTIONS (Windows) or Visual Studio > Preferences (Mac OS).
  3. In the NuGet section, open Sources. You will see a list of all your NuGet sources.
  4. Click Add.
  5. 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
    • Password: Your personal access token

    Visual Studio Adding a NuGet source

  6. Click Save.

    Visual Studio NuGet source added

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>" />
            <add key="ClearTextPassword" value="<gitlab_personal_access_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:

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:

For example:

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

Install packages

Install a package with NuGet CLI

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

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.