Supported package managers and functionality

The GitLab package registry supports different functionalities for each package type. This support includes publishing and pulling packages, request forwarding, managing duplicates, and authentication.

Supported package managers

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< alert type=”warning” >}}

Not all package manager formats are ready for production use.

{{< /alert >}}

The package registry supports the following package manager types:

Package type Status
Composer Beta
Conan Experiment
Debian Experiment
Generic packages Generally available
Go Experiment
Helm Beta
Maven Generally available
npm Generally available
NuGet Generally available
PyPI Generally available
Ruby gems Experiment

View what each status means.

You can also use the API to administer the package registry.

Publishing packages

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Packages can be published to your project, group, or instance.

Package type Project Group Instance
Maven (with mvn) Y N N
Maven (with gradle) Y N N
Maven (with sbt) N N N
npm Y N N
NuGet Y N N
PyPI Y N N
Generic packages Y N N
Terraform Y N N
Composer N Y N
Conan Y N Y
Helm Y N N
Debian Y N N
Go Y N N
Ruby gems Y N N

Pulling packages

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Packages can be pulled from your project, group, or instance.

Package type Project Group Instance
Maven (with mvn) Y Y Y
Maven (with gradle) Y Y Y
Maven (with sbt) Y Y Y
npm Y Y Y
NuGet Y Y N
PyPI Y Y N
Generic packages Y N N
Terraform N Y N
Composer Y Y N
Conan Y N Y
Helm Y N N
Debian Y N N
Go Y N Y
Ruby gems Y N N

Forwarding requests

{{< details >}}

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

When a package is not found in your project’s package registry, GitLab can forward the request to the corresponding public registry. For example, Maven Central, npmjs, or PyPI.

The default forwarding behavior varies by package type and can introduce a dependency confusion vulnerability.

To reduce the associated security risks:

  • Verify the package is not being actively used.
  • Disable request forwarding:
    • Instance administrators can disable forwarding in the Continuous Integration section of the Admin area.
    • Group owners can disable forwarding in the Packages and Registries section of the group settings.
  • Implement a version control tool, like Git, to track changes to packages.
Package type Supports request forwarding Security considerations
Maven (with mvn) Yes (disabled by default) Requires explicit opt-in for security.
Maven (with gradle) Yes (disabled by default) Requires explicit opt-in for security.
Maven (with sbt) Yes (disabled by default) Requires explicit opt-in for security.
npm Yes Consider disabling for private packages.
NuGet N N
PyPI Yes Consider disabling for private packages.
Generic packages N N
Terraform N N
Composer N N
Conan N N
Helm N N
Debian N N
Go N N
Ruby gems N N

Deleting packages

When package requests are forwarded to a public registry, deleting packages can be a dependency confusion vulnerability.

If a system tries to pull a deleted package, the request is forwarded to the public registry. If a package with the same name and version is found in the public registry, that package is pulled instead. There is a risk that the package pulled from the registry might not be what is expected, and could even be malicious.

To reduce the associated security risks, before deleting a package you can:

  • Verify the package is not being actively used.
  • Disable request forwarding:
    • Instance administrators can disable forwarding in the Continuous Integration section of the Admin area.
    • Group owners can disable forwarding in the Packages and Registries section of the group settings.

Importing packages from other repositories

You can use GitLab pipelines to import packages from other repositories, such as Maven Central or Artifactory with the package importer tool.

Package type Importer available?
Maven (with mvn) Y
Maven (with gradle) Y
Maven (with sbt) Y
npm Y
NuGet Y
PyPI Y
Generic packages N
Terraform N
Composer N
Conan N
Helm N
Debian N
Go N
Ruby gems N

Allow or prevent duplicates

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

By default, the GitLab package registry either allows or prevents duplicates based on the default of that specific package manager format.

Package type Duplicates allowed?
Maven (with mvn) Y (configurable)
Maven (with gradle) Y (configurable)
Maven (with sbt) Y (configurable)
npm N
NuGet Y
PyPI N
Generic packages Y (configurable)
Terraform N
Composer N
Conan N
Helm Y
Debian Y
Go N
Ruby gems Y

Authenticate with the registry

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Authentication depends on the package manager you’re using. To learn what authentication protocols are supported for a specific package type, see Authentication protocols.

For most package types, the following authentication tokens are valid:

The following table lists which authentication tokens are supported for a given package manager:

Package type Supported tokens
Maven (with mvn) Personal access, job tokens, deploy (project or group), project access
Maven (with gradle) Personal access, job tokens, deploy (project or group), project access
Maven (with sbt) Personal access, job tokens, deploy (project or group), project access
npm Personal access, job tokens, deploy (project or group), project access
NuGet Personal access, job tokens, deploy (project or group), project access
PyPI Personal access, job tokens, deploy (project or group), project access
Generic packages Personal access, job tokens, deploy (project or group), project access
Terraform Personal access, job tokens, deploy (project or group), project access
Composer Personal access, job tokens, deploy (project or group), project access
Conan Personal access, job tokens, project access
Helm Personal access, job tokens, deploy (project or group)
Debian Personal access, job tokens, deploy (project or group)
Go Personal access, job tokens, project access
Ruby gems Personal access, job tokens, deploy (project or group)

{{< alert type=”note” >}}

When you configure authentication to the package registry:

  • If the Package registry project setting is turned off, you receive a 403 Forbidden error when you interact with the package registry, even if you have the Owner role.
  • If external authorization is turned on, you can’t access the package registry with a deploy token.
  • If your organization uses two-factor authentication (2FA), you must use a personal access token with the scope set to api.
  • If you are publishing a package by using CI/CD pipelines, you must use a CI/CD job token.

{{< /alert >}}

Authentication protocols

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

  • Basic authentication for Maven packages introduced in GitLab 16.0.

{{< /history >}}

The following authentication protocols are supported:

Package type Supported auth protocols
Maven (with mvn) Headers, Basic auth
Maven (with gradle) Headers, Basic auth
Maven (with sbt) Basic auth (pulling only)
npm OAuth
NuGet Basic auth
PyPI Basic auth
Generic packages Basic auth
Terraform Token
Composer OAuth
Conan OAuth, Basic auth
Helm Basic auth
Debian Basic auth
Go Basic auth
Ruby gems Token

Supported hash types

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Hash values are used to ensure you are using the correct package. You can view these values in the user interface or with the API.

The package registry supports the following hash types:

Package type Supported hashes
Maven (with mvn) MD5, SHA1
Maven (with gradle) MD5, SHA1
Maven (with sbt) MD5, SHA1
npm SHA1
NuGet not applicable
PyPI MD5, SHA256
Generic packages SHA256
Composer not applicable
Conan MD5, SHA1
Helm not applicable
Debian MD5, SHA1, SHA256
Go MD5, SHA1, SHA256
Ruby gems MD5, SHA1, SHA256 (gemspec only)