Maven virtual registry

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed
Status: Experiment

Version history

Introduced in GitLab 18.0 with a flag named virtual_registry_maven. Disabled by default.

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available in experiment. Review the documentation carefully before you use this feature.

The Maven virtual registry uses a single, well-known URL to manage and distribute packages from multiple external registries in GitLab.

Use the Maven virtual registry to:

Create a virtual registry.
Connect the virtual registry to public and private upstream registries.
Configure Maven clients to pull packages from configured upstreams.
Manage cache entries for available upstreams.

This approach provides better package performance over time, and makes it easier to manage your Maven packages.

Prerequisites

Before you can use the Maven virtual registry:

Review the prerequisites to use the virtual registry.

When using the Maven virtual registry, remember the following restrictions:

You can create only one Maven virtual registry per top-level group.
You can set only 20 upstreams to a given Maven virtual registry.
For technical reasons, the proxy_download setting is force enabled, no matter what the value in the object storage configuration is configured to.
Geo support is not implemented. You can follow its development in issue 473033.

Manage the virtual registry

Manage the virtual registry with the dedicated virtual registry API.

You cannot configure the virtual registry in the UI, but this epic 15090 proposes the implementation of a virtual registry UI.

Authenticate to the virtual registry API

The virtual registry API uses REST API authentication methods. You must authenticate to the API to manage virtual registry objects.

Read operations are open to users that can use the virtual registry.

Write operations, such as creating a new registry or adding upstreams are restricted to direct maintainers of the top-level group that hosts the virtual registry.

Create and manage a virtual registry

To create a Maven virtual registry, use the following command:

curl --fail-with-body \
     --request POST \
     --header "<header>" \
     --data '{"name": "<registry_name>"}' \
     --url "https://gitlab.example.com/api/v4/groups/<group_id>/-/virtual_registries/packages/maven/registries"

<header> is the authentication header.
<group_id> is the top-level group ID.
<registry_name> is the registry name. Required.

To see other endpoints and examples related to managing a virtual registry, see the API documentation.

Manage upstream registries

Prerequisites:

You must have a valid Maven virtual registry ID.

When you create an upstream registry to an existing virtual registry, the upstream registry is added to the end of the list of available upstreams.

To create an upstream to an existing virtual registry, use the following command:

curl --fail-with-body \
     --request POST \
     --header "<header>" \
     --data '{ "name": "<upstream_name>", "url": "<upstream_url>", "username": "<upstream_username>", "password": "<upstream_password>", "cache_validity_hours": <upstream_cache_validity_hours> }' \
     --url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/registries/<registry_id>/upstreams"

<header> is the authentication header.
<registry_id> is the Maven virtual registry ID.
<upstream_name> is the upstream registry name. Required.
<upstream_url> is the Maven upstream URL. Required.
<upstream_username> is the username to use with the Maven upstream. Required if an <upstream_password> is set.
<upstream_password> is the password to use with the Maven upstream. Required if an <upstream_username> is set.
<upstream_cache_validity_hours> is the cache validity period in hours. Optional. The default value is 24. 0 disables the cache entry checks.
- if the <upstream_url> is set to Maven central, the validity period is set to 0.

<upstream_username> and <upstream_password> are optional. If not set, a public (anonymous) request is used to access the upstream.

To see other endpoints and examples related to managing an upstream registry, including updating the upstream registry position in the list, see the API documentation.

Use Maven central as an upstream

To configure an upstream to Maven central, use the following URL: https://repo1.maven.org/maven2.

On Maven central, all files are immutable. You should set the cache validity period to 0 to disable cache checks with Maven central.

Manage cache entries

If necessary, cache entries can be inspected or destroyed.

The next time the virtual registry receives a request for the file that was referenced by the destroyed cache entry, the list of upstreams is walked again to find an upstream that can fulfill this request.

To see the endpoints and examples related to managing cache entries, see the API documentation.

Use the virtual registry

After you create a virtual registry, you must configure Maven clients to pull dependencies through the virtual registry.

Authentication with Maven clients

The virtual registry endpoint can be used by any of following tokens:

A personal access token.
A group deploy token for the top-level group hosting the considered virtual registry.
A group access token for the top-level group hosting the considered virtual registry.
A CI job token.

Tokens need one of the following scopes:

api
read_virtual_registry

Access tokens and the CI job token are resolved to users. The resolved user must be either:

A direct member of the top-level group with the minimal access level of guest.
A GitLab instance administrator.
A direct member of one of the projects included in the top-level group.

Configure Maven clients

The Maven virtual registry supports the following Maven clients:

You must declare virtual registries in the Maven client configuration.

All clients must be authenticated. For the client authentication, you can use a custom HTTP header or Basic Auth. You should use one of the configurations below for each client.

`mvn`

Token type	Name must be	Token
Personal access token	`Private-Token`	Paste token as-is, or define an environment variable to hold the token.
Group deploy token	`Deploy-Token`	Paste token as-is, or define an environment variable to hold the token.
Group access token	`Private-Token`	Paste token as-is, or define an environment variable to hold the token.
CI Job token	`Job-Token`	`${CI_JOB_TOKEN}`

Add the following section to your settings.xml file.

<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>REPLACE_WITH_NAME</name>
            <value>REPLACE_WITH_TOKEN</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

You can configure the virtual registry in mvn applications in one of two ways:

As an additional registry on top of the default registry (Maven central). In this configuration, you can pull the project dependencies that are present in both the virtual registry and the default registry from any of the declared registries.
As a replacement of the default registry (Maven central). With this configuration, dependencies are pulled through the virtual registry. You should configure Maven central as the last upstream of the virtual registry to avoid missing required public dependencies.

To configure a Maven virtual registry as an additional registry, in the pom.xml file, add a repository element:

<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id></url>
  </repository>
</repositories>

Where:

<registry_id> is the ID of the Maven virtual registry.
<id> contains the same ID of the <server> used in the settings.xml.

To configure a Maven virtual registry as a replacement of the default registry, in the settings.xml, add a mirrors element:

<settings>
  <servers>
    ...
  </servers>
  <mirrors>
    <mirror>
      <id>central-proxy</id>
      <name>GitLab proxy of central repo</name>
      <url>https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id></url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

Where:

<registry_id> is the ID of the Maven virtual registry.

`gradle`

Token type	Name must be	Token
Personal access token	`Private-Token`	Paste token as-is, or define an environment variable to hold the token.
Group deploy token	`Deploy-Token`	Paste token as-is, or define an environment variable to hold the token.
Group access token	`Private-Token`	Paste token as-is, or define an environment variable to hold the token.
CI Job token	`Job-Token`	`${CI_JOB_TOKEN}`

In your GRADLE_USER_HOME directory, create a file gradle.properties with the following content:

gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

Add a repositories section to your build.gradle.

In Groovy DSL:

repositories {
    maven {
        url "https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id>"
        name "GitLab"
        credentials(HttpHeaderCredentials) {
            name = 'REPLACE_WITH_NAME'
            value = gitLabPrivateToken
        }
        authentication {
            header(HttpHeaderAuthentication)
        }
    }
}

In Kotlin DSL:

repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id>")
        name = "GitLab"
        credentials(HttpHeaderCredentials::class) {
            name = "REPLACE_WITH_NAME"
            value = findProperty("gitLabPrivateToken") as String?
        }
        authentication {
            create("header", HttpHeaderAuthentication::class)
        }
    }
}

Where:

<registry_id> is the ID of the Maven virtual registry.

`sbt`

Token type	Username must be	Token
Personal access token	The username of the user	Paste token as-is, or define an environment variable to hold the token.
Group deploy token	The username of deploy token	Paste token as-is, or define an environment variable to hold the token.
Group access token	The username of the user linked to the access token	Paste token as-is, or define an environment variable to hold the token.
CI Job token	`gitlab-ci-token`	`sys.env.get("CI_JOB_TOKEN").get`

Authentication for SBT is based on basic HTTP Authentication. You must to provide a name and a password.

In your build.sbt, add the following lines:

resolvers += ("gitlab" at "<endpoint_url>")

credentials += Credentials("GitLab Virtual Registry", "<host>", "<username>", "<token>")

Where:

<endpoint_url> is the Maven virtual registry URL. For example, https://gitlab.example.com/api/v4/virtual_registries/packages/maven/<registry_id>. <registry_id> is the ID of the Maven virtual registry.
<host> is the host present in the <endpoint_url> without the protocol scheme or the port. For example, gitlab.example.com.
<username> is the username.
<token> is the configured token.
Make sure that the first argument of Credentials is "GitLab Virtual Registry". This realm name must exactly match the basic auth realm sent by the Maven virtual registry.