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. For sbt on Windows, or for an sbt project that declares sbt version 2.x, version 1.125.0 or later.

The GitLab CLI uses the GITLAB_TOKEN environment variable if it is set. Otherwise, it uses the credential that glab auth login stores. To check that the GitLab CLI can authenticate, run:

shell
glab auth status

If the command does not report that you are logged in, authenticate with the GitLab CLI:

shell
glab auth login

Then follow the steps for your preferred client.

Run the following command:

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

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

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

This writes the same credentials += line in each file that sbt reads:

  • ~/.sbt/1.0/credentials.sbt, for sbt version 1.x.
  • ~/.config/sbt/2/credentials.sbt, for sbt version 2.x. If you set SBT_CONFIG_HOME, the command writes $SBT_CONFIG_HOME/2/credentials.sbt instead. Otherwise, if you set XDG_CONFIG_HOME, it writes $XDG_CONFIG_HOME/sbt/2/credentials.sbt. On Windows, the command reads LOCALAPPDATA in place of XDG_CONFIG_HOME, and writes %LOCALAPPDATA%\sbt\2\credentials.sbt.
  • On Windows, also %LOCALAPPDATA%\sbt\credentials.sbt. Every build that the sbt.bat launcher of sbt version 2.x starts reads only this file, whichever sbt version your project declares.

The command output names each file it wrote. The command ignores a blank or relative SBT_CONFIG_HOME, XDG_CONFIG_HOME, or LOCALAPPDATA, and prints a warning that names the variable.

An sbt that you start with -Dsbt.global.base set to a directory of your own reads none of these files. In that case, copy the credentials += line into a credentials.sbt file in that directory. If that directory is inside your project, do not commit the file to version control, because it holds your token. Copy the line again each time you run the command.

An sbt shell or sbt version 2.x server that is already running keeps the credentials it loaded. After you run the command, run reload in the sbt shell. For an sbt version 2.x server, you can also run sbt shutdown.

If you use a GitLab CLI version earlier than 1.125.0, the command writes only ~/.sbt/1.0/credentials.sbt. On Windows, upgrade to version 1.125.0 or later. On other systems, if your project declares sbt version 2.x, after you run the command, do one of the following:

  • Copy the credentials += line into ~/.config/sbt/2/credentials.sbt. If you set SBT_CONFIG_HOME, use $SBT_CONFIG_HOME/2/credentials.sbt instead. Otherwise, if you set XDG_CONFIG_HOME, use $XDG_CONFIG_HOME/sbt/2/credentials.sbt.
  • Copy the credentials += line into a credentials.sbt file in your project root. The file holds your token, so do not commit it to version control. For example, add it to your .gitignore file.
  • If your build does not use sbt version 2.x features or plugins, set sbt.version in project/build.properties to a 1.x release.

If you copied the line, copy it again each time you run the command.

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, and glab 1.125.0 or later for sbt on Windows or for an sbt project that declares sbt version 2.x. The artifact-registry login commands are experiments, so their names and flags can change.

Use a remote or virtual repository in place of Maven Central

Use a remote or virtual repository in place of Maven Central so that your build resolves its dependencies through artifact registry.

Prerequisites:

  • One of the following:
    • A remote Maven repository that proxies Maven Central.
    • A virtual Maven repository with a remote repository that proxies Maven Central as one of its upstreams.
  • An authenticated Maven client.

With this configuration, your build no longer contacts Maven Central directly.

When the registry caches a release file or a timestamped snapshot file from an upstream, it also requests that file’s .sha1 from the same upstream and compares the two. A disagreement is a warning in the registry’s logs — an early signal that the upstream serves a damaged file — and never changes what your build receives.

In a virtual repository, list the Maven Central remote repository as the last upstream. A virtual repository serves each file from the first upstream that has it, so your other upstreams take precedence over a package with the same name on Maven Central.

In the following examples:

  • <repository_url>: The repository URL from Configure your client. For example, https://ar.example.com/acme/maven/my-repo.
  • <alias>: For mvn and gradle, the alias you passed to --registry-alias when you authenticated.

To use the repository in place of Maven Central:

  1. Merge the following mirror into your ~/.m2/settings.xml file:

    xml
    <mirrors>
      <mirror>
        <id><alias></id>
        <url><repository_url></url>
        <mirrorOf>central</mirrorOf>
      </mirror>
    </mirrors>

    The mirror <id> must match the ID of the <server> block that glab wrote, so use the same alias.

  2. Optional. To also resolve snapshot dependencies, merge the following repository into your pom.xml file:

    xml
    <repositories>
      <repository>
        <id><alias></id>
        <url><repository_url></url>
        <snapshots>
          <enabled>true</enabled>
        </snapshots>
      </repository>
    </repositories>

To use the repository in place of Maven Central:

  • Replace mavenCentral() with the following repository block, which reads values that glab wrote to gradle.properties:

    • In Groovy DSL, in build.gradle:

      groovy
      maven {
        url = providers.gradleProperty('<alias>Url').get()
        credentials {
          username = providers.gradleProperty('<alias>Username').get()
          password = providers.gradleProperty('<alias>Password').get()
        }
      }
    • In Kotlin DSL, in build.gradle.kts:

      kotlin
      maven {
        url = uri(providers.gradleProperty("<alias>Url").get())
        credentials {
          username = providers.gradleProperty("<alias>Username").get()
          password = providers.gradleProperty("<alias>Password").get()
        }
      }

To use the repository in place of Maven Central:

  • In your build.sbt file, set externalResolvers:

    scala
    externalResolvers := Resolver.combineDefaultResolvers(
      resolvers.value.toVector :+ ("artifact-registry" at "<repository_url>"),
      mavenCentral = false
    )

    This setting keeps your project resolvers and the local Ivy repository, and removes the default Maven Central resolver.

Dependencies your build would fetch from Maven Central now resolve through the repository.

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.

Version attribution

A version of a hosted repository records who published it and, when a CI/CD job published it, which job:

  • created_by: the GitLab user ID of the user whose upload created the version.
  • project_id, git_commit_sha, pipeline_id, and job_id: the project, commit, pipeline, and job of the CI/CD job that stored the file the rules below select.

Attribution works as follows:

  • Only an upload with a token that GitLab exchanged from a CI/CD ID token records the four build fields. An upload with any other credential, including CI_JOB_TOKEN, counts as an upload with no build fields.
  • The four build fields are recorded together or not at all. A job that sends values the registry cannot store leaves all four empty, and the upload still succeeds.
  • For a release version, the first file uploaded sets the four build fields. Later uploads into the version leave them as they are while it still holds a file; once all of its files are deleted, the next upload sets them again.
  • For a snapshot version, the most recent file uploaded sets the four build fields. A snapshot that a CI/CD job uploaded to, and that a user then uploaded another file to, ends with all four empty.
  • Checksum files (.md5, .sha1, .sha256, .sha512) do not count as files for these rules: uploading one changes nothing.
  • An upload that fails or is cancelled leaves the four build fields as they were. If it created the version, the version keeps created_by.
  • A version of a remote repository has no build fields.
  • Neither does a version whose files were uploaded before the registry recorded attribution, until a later upload sets them under the rules above.

Limits

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

Deleted versions count toward the versions limit until the registry permanently removes them. Deleting a version or a package, then deploying again, does not free that capacity.

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. On a hosted repository, a delete is permanent and can’t be undone.

For specific steps, see the Artifact Registry API.

Virtual repositories

A virtual Maven repository reads from its upstream repositories in the order you list them.

  • The first upstream that holds an artifact or a version-level metadata file serves it.
  • The registry merges a package-level maven-metadata.xml from the upstreams that hold one, so the document lists the union of their versions.
  • A merged package-level maven-metadata.xml response carries X-Checksum-Sha1, so Maven verifies the document without requesting its .sha1 sidecar.
  • The registry computes a checksum sidecar (.sha1, .md5, .sha256, .sha512) from the bytes it serves for the file it describes, so a sidecar response never carries an upstream’s own checksum file.
  • The registry does not serve an .md5 sidecar while FIPS mode is enabled.
  • You cannot publish to a virtual Maven repository.

For details, see Artifact Registry repositories.

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, deleted versions included until the registry permanently removes them.
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.