Maven packages in Artifact Registry
- Tier: Premium, Ultimate
- Offering: GitLab.com
- Status: Beta
Use the Maven repository to store Maven packages.
Supported clients
mvngradle, with either a Groovy or a Kotlin build scriptsbt
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:
glab auth statusIf the command does not report that you are logged in, authenticate with the GitLab CLI:
glab auth loginThen 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 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 setSBT_CONFIG_HOME, the command writes$SBT_CONFIG_HOME/2/credentials.sbtinstead. Otherwise, if you setXDG_CONFIG_HOME, it writes$XDG_CONFIG_HOME/sbt/2/credentials.sbt. On Windows, the command readsLOCALAPPDATAin place ofXDG_CONFIG_HOME, and writes%LOCALAPPDATA%\sbt\2\credentials.sbt.- On Windows, also
%LOCALAPPDATA%\sbt\credentials.sbt. Every build that thesbt.batlauncher 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 setSBT_CONFIG_HOME, use$SBT_CONFIG_HOME/2/credentials.sbtinstead. Otherwise, if you setXDG_CONFIG_HOME, use$XDG_CONFIG_HOME/sbt/2/credentials.sbt. - Copy the
credentials +=line into acredentials.sbtfile in your project root. The file holds your token, so do not commit it to version control. For example, add it to your.gitignorefile. - If your build does not use sbt version 2.x features or plugins, set
sbt.versioninproject/build.propertiesto 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>: Formvnandgradle, the alias you passed to--registry-aliaswhen you authenticated.
To use the repository in place of Maven Central:
-
Merge the following mirror into your
~/.m2/settings.xmlfile:<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 thatglabwrote, so use the same alias. -
Optional. To also resolve snapshot dependencies, merge the following repository into your
pom.xmlfile:<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 thatglabwrote togradle.properties:-
In Groovy DSL, in
build.gradle: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: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.sbtfile, setexternalResolvers: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
409after 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, andjob_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.xmlfrom the upstreams that hold one, so the document lists the union of their versions. - A merged package-level
maven-metadata.xmlresponse carriesX-Checksum-Sha1, so Maven verifies the document without requesting its.sha1sidecar. - 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
.md5sidecar 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.