GitLab NuGet Repository

Version history

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

NuGet CLI 5.2 or later is required. 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]
Note: GitLab currently only supports NuGet v3. Earlier versions are not supported.

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: This option is available only if your GitLab administrator has enabled support for the Package Registry.

When the NuGet Repository is enabled, it is 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 > Visibility, project features, 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 & Registries section on the left sidebar.

Adding the GitLab NuGet Repository as a source to NuGet

You 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:

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

  1. Open Visual Studio.
  2. Open the FILE > OPTIONS (Windows) or Visual Studio > Preferences (Mac OS).
  3. In the NuGet section, open Sources to 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 or deploy token username
    • Password: Your personal access token or deploy 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 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 serves the most recent file.
  • When uploading packages to GitLab, they are not 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 to install the correct package.

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 is 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.

Publishing a NuGet package with CI/CD

Introduced in GitLab 13.3.

If you’re using NuGet with GitLab CI/CD, a CI job token can be used instead of a 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: 

     image: mcr.microsoft.com/dotnet/core/sdk:3.1

 stages:
   - deploy

 deploy:
   stage: deploy
   script:
     - dotnet restore -p:Configuration=Release
     - dotnet build -c Release
     - dotnet pack -c Release
     - dotnet nuget add source "$CI_SERVER_URL/api/v4/projects/$CI_PROJECT_ID/packages/nuget/index.json" --name gitlab --username gitlab-ci-token --password $CI_JOB_TOKEN --store-password-in-clear-text
     - dotnet nuget push "bin/Release/*.nupkg" --source gitlab
   only:
     - master

  2. Commit the changes and push it to your GitLab repository to trigger a new CI build.