Maven packages in Artifact Registry

Tier: Premium, Ultimate
Offering: GitLab.com
Status: Beta

Use the Maven repository to store Maven packages.

Supported clients

mvn
gradle, with either a Groovy or a Kotlin build script
sbt

Authenticate

All three clients authenticate with basic authentication. Custom header authentication is not supported, so the Private-Token header used by the older GitLab Maven package registry does not work.

Prerequisites:

The GitLab CLI, version 1.115.0 or later.

Authentication with Maven requires the GITLAB_TOKEN to be set. To check if the environment variable is set, run:

echo $GITLAB_TOKEN

If nothing is printed, authenticate with the GitLab CLI to set GITLAB_TOKEN:

glab auth login

After the token is set, follow the steps for your preferred client.

Run the following command:

glab artifact-registry login --maven --registry <repository_url> --registry-alias <alias>

This writes a <server> block in ~/.m2/settings.xml, keyed by the alias you choose. In your pom.xml, the <repository> element’s <id> must match this alias.

Run the following command:

glab artifact-registry login --gradle --registry <repository_url> --registry-alias <alias>

This writes <alias>Url, <alias>Username, and <alias>Password in ~/.gradle/gradle.properties. Pick an alias that is a valid identifier. The default alias comes from the host name and contains hyphens, which a Groovy build script cannot use in ${...} references.

Run the following command:

glab artifact-registry login --sbt --registry <repository_url>

This writes a credentials += line in ~/.sbt/1.0/credentials.sbt. Only a stock sbt version 1.x installation reads this file. An sbt that moved its global base with -Dsbt.global.base does not read this file.

Run the glab artifact-registry login command again for your client before the token expires. The token lasts 15 minutes by default, and up to 12 hours if you request a longer duration.

Configure your client

A Maven repository is available at:

https://<registry_host>/<registry_handle>/maven/<repository_name>

Replace the following placeholders:

<registry_host>: Enter the hostname from your repository’s setup instructions. To find it, go to your repository and select More actions > View setup instructions.
<registry_handle>: Enter your organization’s registry handle.
<repository_name>: Enter the name of your repository.

The GitLab CLI (glab) writes the credential for you. It requires glab 1.115.0 or later. The artifact-registry login commands are experiments, so their names and flags can change.

Make sure glab can authenticate. It reads the GITLAB_TOKEN environment variable. If that is not set, run glab auth login first.

Republishing a version

Artifact Registry accepts a re-upload when the content is byte-for-byte identical.
It returns 409 after the content differs. A rebuilt Java Archive (JAR) usually differs, so a repeated deploy of the same version usually fails.
Use a new version number instead.

Limits

Limit	Value
Artifact size	5 GB
`maven-metadata.xml` size	10 MB
Versions per package	25,000

For the full list of limits, see Artifact Registry limits.

Delete a Maven package

The Management API deletes Maven packages, versions, and files, one at a time or in a batch. Maven itself has no delete command.

For specific steps, see the Artifact Registry API.

Errors you might see

Error	What it means
`Release file already exists with different content.`	You re-deployed a version with changed content. Use a new version number.
`Per-package version cap reached.`	The package holds the maximum number of versions.
`Request body exceeds the configured maximum.`	The upload is larger than 5 GB.
`Uploaded checksum does not match the stored parent file.`	The checksum file does not match the artifact it describes. Re-run the deploy.
`MD5 checksum sidecars are not served while FIPS mode is enabled.`	The instance runs in Federal Information Processing Standards (FIPS) mode, which does not serve Message Digest 5 (MD5) checksums.

A mismatched alias makes Maven send no credentials at all. The deploy fails with 401, without saying why.