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.

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