Maven packages in the package registry

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Publish Maven artifacts in your project’s package registry. Then, install the packages whenever you need to use them as a dependency.

For documentation of the specific API endpoints that the Maven package manager client uses, see the Maven API documentation.

Supported clients:

  • mvn. Learn how to build a Maven package.
  • gradle. Learn how to build a Gradle package.
  • sbt.

Publish to the GitLab package registry

Authenticate to the package registry

You need a token to publish a package. There are different tokens available depending on what you’re trying to achieve. For more information, review the guidance on tokens.

Create a token and save it to use later in the process.

Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future.

Edit the client configuration

Update your configuration to authenticate to the Maven repository with HTTP.

Custom HTTP header

You must add the authentication details to the configuration file for your client.

Token typeName must beToken
Personal access tokenPrivate-TokenPaste token as-is, or define an environment variable to hold the token
Deploy tokenDeploy-TokenPaste token as-is, or define an environment variable to hold the token
CI Job tokenJob-Token${CI_JOB_TOKEN}

The <name> field must be named to match the token you chose.

Add the following section to your settings.xml file.

Copy to clipboard
<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>
Basic HTTP Authentication

You can also use basic HTTP authentication to authenticate to the Maven package registry.

Token typeName must beToken
Personal access tokenThe username of the userPaste token as-is, or define an environment variable to hold the token
Deploy tokenThe username of deploy tokenPaste token as-is, or define an environment variable to hold the token
CI Job tokengitlab-ci-token${CI_JOB_TOKEN}

Add the following section to your settings.xml file.

Copy to clipboard
<settings>
  <servers>
    <server>
      <id>gitlab-maven</id>
      <username>REPLACE_WITH_NAME</username>
      <password>REPLACE_WITH_TOKEN</password>
      <configuration>
        <authenticationInfo>
          <userName>REPLACE_WITH_NAME</userName>
          <password>REPLACE_WITH_TOKEN</password>
        </authenticationInfo>
      </configuration>
    </server>
  </servers>
</settings>

Naming convention

You can use one of three endpoints to install a Maven package. You must publish a package to a project, but the endpoint you choose determines the settings you add to your pom.xml file for publishing.

The three endpoints are:

  • Project-level: Use when you have a few Maven packages and they are not in the same GitLab group.
  • Group-level: Use when you want to install packages from many different projects in the same GitLab group. GitLab does not guarantee the uniqueness of package names within the group. You can have two projects with the same package name and package version. As a result, GitLab serves whichever one is more recent.
  • Instance-level: Use when you have many packages in different GitLab groups or in their own namespace.

For the instance-level endpoint, ensure the relevant section of your pom.xml in Maven looks like this:

Copy to clipboard
  <groupId>group-slug.subgroup-slug</groupId>
  <artifactId>project-slug</artifactId>

Only packages that have the same path as the project are exposed by the instance-level endpoint.

ProjectPackageInstance-level endpoint available
foo/barfoo/bar/1.0-SNAPSHOTYes
gitlab-org/gitlabfoo/bar/1.0-SNAPSHOTNo
gitlab-org/gitlabgitlab-org/gitlab/1.0-SNAPSHOTYes

Endpoint URLs

EndpointEndpoint URL for pom.xmlAdditional information
Projecthttps://gitlab.example.com/api/v4/projects/<project_id>/packages/mavenReplace gitlab.example.com with your domain name. Replace <project_id> with your project ID, found on your project overview page.
Grouphttps://gitlab.example.com/api/v4/groups/<group_id>/-/packages/mavenReplace gitlab.example.com with your domain name. Replace <group_id> with your group ID, found on your group’s homepage.
Instancehttps://gitlab.example.com/api/v4/packages/mavenReplace gitlab.example.com with your domain name.

Edit the configuration file for publishing

You must add publishing details to the configuration file for your client.

No matter which endpoint you choose, you must have:

  • A project-specific URL in the distributionManagement section.
  • A repository and distributionManagement section.

The relevant repository section of your pom.xml in Maven should look like this:

Copy to clipboard
<repositories>
  <repository>
    <id>gitlab-maven</id>
    <url><your_endpoint_url></url>
  </repository>
</repositories>
<distributionManagement>
  <repository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </repository>
  <snapshotRepository>
    <id>gitlab-maven</id>
    <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
  </snapshotRepository>
</distributionManagement>

Publish a package

Using the DeployAtEnd option can cause an upload to be rejected with 400 bad request {"message":"Validation failed: Name has already been taken"}. For more details, see issue 424238.

After you have set up the authentication and chosen an endpoint for publishing, publish a Maven package to your project.

To publish a package by using Maven:

Copy to clipboard
mvn deploy

If the deploy is successful, the build success message should be displayed:

Copy to clipboard
...
[INFO] BUILD SUCCESS
...

The message should also show that the package was published to the correct location:

Copy to clipboard
Uploading to gitlab-maven: https://example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar

If you protect a Maven package before publishing it, the package will be rejected with a 403 Forbidden error and an Authorization failed error message. Ensure the Maven package is not protected when publishing. For more information about package protection rules, see how to protect a package.

Install a package

To install a package from the GitLab package registry, you must configure the remote and authenticate. When this is completed, you can install a package from a project, group, or namespace.

If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved.

In case there are not enough permissions to read the most recently-published package than 403 Forbidden is returning.

To install a package by using mvn install:

  1. Add the dependency manually to your project pom.xml file. To add the example created earlier, the XML would be:

    Copy to clipboard
    <dependency>
      <groupId>com.mycompany.mydepartment</groupId>
      <artifactId>my-project</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
  2. In your project, run the following:

    Copy to clipboard
    mvn install

The message should show that the package is downloading from the package registry:

Copy to clipboard
Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

You can also install packages by using the Maven dependency:get command directly.

  1. In your project directory, run:

    Copy to clipboard
    mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT -DremoteRepositories=gitlab-maven::::<gitlab endpoint url>  -s <path to settings.xml>
    • <gitlab endpoint url> is the URL of the GitLab endpoint.
    • <path to settings.xml> is the path to the settings.xml file that contains the authentication details.

The repository IDs in the command(gitlab-maven) and the settings.xml file must match.

The message should show that the package is downloading from the package registry:

Copy to clipboard
Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom

Proxy downloads for Maven packages

History

The GitLab Maven package registry uses remote included checksums. When you download a file, the registry proxies the file and sends both the file and its related checksums to Maven clients in a single request.

Using remote included checksums with recent Maven clients:

  • Reduces the number of web requests from the clients to the GitLab Maven package registry.
  • Decreases the load on your GitLab instance.
  • Improves the client command execution time.

Due to technical constraints, when you use object storage, the Maven package registry ignores the proxy download setting in the object storage configuration for packages. Instead, proxy download is always enabled for Maven package registry downloads.

If you don’t use object storage, this behavior has no impact on your instance.

CI/CD integration for Maven packages

You can use CI/CD to automatically build, test, and publish Maven packages. The examples in this section cover scenarios like:

  • Multi-module projects
  • Versioned releases
  • Conditional publishing
  • Integration with code quality and security scans

You can adapt and combine these examples to suit your specific project needs.

Remember to adjust the Maven version, Java version, and other specifics according to your project requirements. Also, make sure you properly configured the necessary credentials and settings for publishing to the GitLab package registry.

Basic Maven package build and publish

This example configures a pipeline that builds and publishes a Maven package:

Copy to clipboard
default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Multi-module Maven project with parallel jobs

For larger projects with multiple modules, you can use parallel jobs to speed up the build process:

Copy to clipboard
default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  parallel:
    matrix:
      - MODULE: [module1, module2, module3]
  script:
    - mvn $MAVEN_CLI_OPTS test -pl $MODULE

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Versioned releases with tags

This example creates versioned releases when a tag is pushed:

Copy to clipboard
default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish
  - release

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

release:
  stage: release
  script:
    - mvn versions:set -DnewVersion=${CI_COMMIT_TAG}
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_TAG

Conditional publishing based on changes

This example publishes packages only when certain files are changed:

Copy to clipboard
default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

stages:
  - build
  - test
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - pom.xml
        - src/**/*

Integration with code quality and security scans

This example integrates code quality checks and security scans into the pipeline:

Copy to clipboard
default:
  image: maven:3.8.5-openjdk-17
  cache:
    paths:
      - .m2/repository/
      - target/

variables:
  MAVEN_CLI_OPTS: "-s .m2/settings.xml --batch-mode"
  MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Code-Quality.gitlab-ci.yml

stages:
  - build
  - test
  - quality
  - publish

build:
  stage: build
  script:
    - mvn $MAVEN_CLI_OPTS compile

test:
  stage: test
  script:
    - mvn $MAVEN_CLI_OPTS test

code_quality:
  stage: quality

sast:
  stage: quality

publish:
  stage: publish
  script:
    - mvn $MAVEN_CLI_OPTS deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Helpful hints

Publishing a package with the same name or version

When you publish a package with the same name and version as an existing package, the new package files are added to the existing package. You can still use the UI or API to access and view the existing package’s older assets.

To delete older package versions, consider using the Packages API or the UI.

Do not allow duplicate Maven packages

History

To prevent users from publishing duplicate Maven packages, you can use the GraphQl API or the UI.

In the UI:

  1. On the left sidebar, select Search or go to and find your group.
  2. Select Settings > Packages and registries.
  3. In the Maven row of the Duplicate packages table, turn off the Allow duplicates toggle.
  4. Optional. In the Exceptions text box, enter a regular expression that matches the names and versions of packages to allow.

If Allow duplicates is turned on, you can specify package names and versions that should not have duplicates in the Exceptions text box.

Your changes are automatically saved.

Request forwarding to Maven Central

History

The availability of this feature is controlled by a feature flag. For more information, see the history.

When a Maven package is not found in the package registry, the request is forwarded to Maven Central.

When the feature flag is enabled, administrators can disable this behavior in the Continuous Integration settings.

Maven forwarding is restricted to only the project level and group level endpoints. The instance level endpoint has naming restrictions that prevent it from being used for packages that don’t follow that convention and also introduces too much security risk for supply-chain style attacks.

Additional configuration for mvn

When using mvn, there are many ways to configure your Maven project so that it requests packages in Maven Central from GitLab. Maven repositories are queried in a specific order. By default, Maven Central is usually checked first through the Super POM, so GitLab needs to be configured to be queried before maven-central.

To ensure all package requests are sent to GitLab instead of Maven Central, you can override Maven Central as the central repository by adding a <mirror> section to your settings.xml:

Copy to clipboard
<settings>
  <servers>
    <server>
      <id>central-proxy</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Private-Token</name>
            <value><personal_access_token></value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
  <mirrors>
    <mirror>
      <id>central-proxy</id>
      <name>GitLab proxy of central repo</name>
      <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

Create Maven packages with GitLab CI/CD

After you have configured your repository to use the Package Repository for Maven, you can configure GitLab CI/CD to build new packages automatically.

You can create a new package each time the default branch is updated.

  1. Create a ci_settings.xml file that serves as Maven’s settings.xml file.

  2. Add the server section with the same ID you defined in your pom.xml file. For example, use gitlab-maven as the ID:

    Copy to clipboard
    <settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
      <servers>
        <server>
          <id>gitlab-maven</id>
          <configuration>
            <httpHeaders>
              <property>
                <name>Job-Token</name>
                <value>${CI_JOB_TOKEN}</value>
              </property>
            </httpHeaders>
          </configuration>
        </server>
      </servers>
    </settings>
  3. Make sure your pom.xml file includes the following. You can either let Maven use the predefined CI/CD variables, as shown in this example, or you can hard code your server’s hostname and project’s ID.

    Copy to clipboard
    <repositories>
      <repository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
      </repository>
    </repositories>
    <distributionManagement>
      <repository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
      </repository>
      <snapshotRepository>
        <id>gitlab-maven</id>
        <url>${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/maven</url>
      </snapshotRepository>
    </distributionManagement>
  4. Add a deploy job to your .gitlab-ci.yml file:

    Copy to clipboard
    deploy:
      image: maven:3.6-jdk-11
      script:
        - 'mvn deploy -s ci_settings.xml'
      rules:
        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  5. Push those files to your repository.

The next time the deploy job runs, it copies ci_settings.xml to the user’s home location. In this example:

  • The user is root, because the job runs in a Docker container.
  • Maven uses the configured CI/CD variables.

Version validation

The version string is validated by using the following regex.

Copy to clipboard
\A(?!.*\.\.)[\w+.-]+\z

You can experiment with the regex and try your version strings on this regular expression editor.

Use different settings for snapshot and release deployments

To use different URLs or settings for snapshots and releases:

  • In the <distributionManagement> section of your pom.xml file, define separate <repository> and <snapshotRepository> elements.

Useful Maven command-line options

There are some Maven command-line options that you can use when performing tasks with GitLab CI/CD.

  • File transfer progress can make the CI logs hard to read. Option -ntp,--no-transfer-progress was added in 3.6.1. Alternatively, look at -B,--batch-mode or lower level logging changes.

  • Specify where to find the pom.xml file (-f,--file):

    Copy to clipboard
    package:
      script:
        - 'mvn --no-transfer-progress -f helloworld/pom.xml package'
  • Specify where to find the user settings (-s,--settings) instead of the default location. There’s also a -gs,--global-settings option:

    Copy to clipboard
    package:
      script:
        - 'mvn -s settings/ci.xml package'

Supported CLI commands

The GitLab Maven repository supports the following CLI commands:

  • mvn deploy: Publish your package to the package registry.
  • mvn install: Install packages specified in your Maven project.
  • mvn dependency:get: Install a specific package.

Troubleshooting

While working with Maven packages in GitLab, you might encounter an issue. To resolve many common issues, try these steps:

  • Verify authentication - Ensure your authentication tokens are correct and have not expired.
  • Check permissions - Confirm you have the necessary permissions to publish or install packages.
  • Validate Maven settings - Double-check your settings.xml file for correct configuration.
  • Review GitLab CI/CD logs - For CI/CD issues, carefully examine the job logs for error messages.
  • Ensure correct endpoint URLs - Verify you’re using the correct endpoint URLs for your project or group.
  • Use the -s option with mvn commands - Always run Maven commands with the -s option, for example, mvn package -s settings.xml. Without this option, authentication settings aren’t applied, and Maven might fail to find packages.

Clear the cache

To improve performance, clients cache files related to a package. If you encounter issues, clear the cache with these commands:

Copy to clipboard
rm -rf ~/.m2/repository

Review network trace logs

If you are having issues with the Maven Repository, you may want to review network trace logs. Reviewing network trace logs provides more detailed error messages, which Maven clients do not include by default.

For example, try to run mvn deploy locally with a PAT token and use these options:

Copy to clipboard
mvn deploy \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient=trace \
-Dorg.slf4j.simpleLogger.log.org.apache.maven.wagon.providers.http.httpclient.wire=trace

When you set these options, all network requests are logged and a large amount of output is generated.

Verify your Maven settings

If you encounter issues within CI/CD that relate to the settings.xml file, try adding an additional script task or job to verify the effective settings.

The help plugin can also provide system properties, including environment variables:

Copy to clipboard
mvn-settings:
  script:
    - 'mvn help:effective-settings'

package:
  script:
    - 'mvn help:system'
    - 'mvn package'

“401 Unauthorized” error when trying to publish a package

This usually indicates an authentication issue. Check that:

  • Your authentication token is valid and has not expired.
  • You’re using the correct token type (personal access token, deploy token, or CI job token).
  • The token has the necessary permissions (api, read_api, or read_repository).
  • For Maven projects, you’re using the -s option with your mvn commands (for example, mvn deploy -s settings.xml). Without this option, Maven won’t apply the authentication settings from your settings.xml file, leading to unauthorized errors.

“400 Bad Request” error with message “Validation failed: Version is invalid”

GitLab has specific requirements for version strings. Ensure your version follows the format:

Copy to clipboard
^(?!.*\.\.)(?!.*\.$)[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*(\+[0-9A-Za-z-]+)?$

For example, “1.0.0”, “1.0-SNAPSHOT”, and “1.0.0-alpha” are valid, but “1..0” or “1.0.” are not.

403 Forbidden error when trying to publish a package

The 403 Forbidden error with the message Authorization failed usually indicates either an authentication or permissions issue. Check that:

  • You’re using the correct token type (personal access token, deploy token, or CI/CD job token). For more information, see Authenticate to the package registry.
  • The token has the necessary permissions. Only users with the Developer role or higher can publish packages. For more information, see GitLab permissions.
  • The package you’re publishing is not protected by push protection rules. For more information about package protection rules, see how to protect a package.

“Artifact already exists” errors when publishing

This error occurs when you try to publish a package version that already exists. To resolve:

  • Increment your package version before publishing.
  • If you’re using SNAPSHOT versions, ensure you’re allowing SNAPSHOT overwrites in your configuration.

Published package not appearing in the UI

If you’ve just published a package, it might take a few moments to appear. If it still doesn’t show:

  • Verify you have the necessary permissions to view packages.
  • Check that the package was successfully published by reviewing CI/CD logs or Maven output.
  • Ensure you’re looking in the correct project or group.

Maven repository dependency conflicts

Dependency conflicts can be resolved by:

  • Explicitly defining versions in your pom.xml.
  • Using Maven’s dependency management section to control versions.
  • Using the <exclusions> tag to exclude conflicting transitive dependencies.

“Unable to find valid certification path to requested target” error

This is typically a SSL certificate issue. To resolve:

  • Ensure your JDK trusts the GitLab server’s SSL certificate.
  • If using a self-signed certificate, add it to the truststore of your JDK.
  • As a last resort, you can disable SSL verification in Maven settings. Not recommended for production.

“No plugin found for prefix” pipeline errors

This usually means Maven can’t find the plugin. To fix:

  • Ensure the plugin is correctly defined in your pom.xml.
  • Check that your CI/CD configuration is using the correct Maven settings file.
  • Verify that your pipeline has access to all necessary repositories.