Maven packages in the package registry All tiers All offerings
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
.-
sbt
can only be used to pull dependencies. See this issue 408479 for more details.
-
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.
mvn
Token type | Name must be | Token |
---|---|---|
Personal access token | Private-Token
| Paste token as-is, or define an environment variable to hold the token |
Deploy token | Deploy-Token
| Paste token as-is, or define an environment variable to hold the token |
CI Job token | Job-Token
| ${CI_JOB_TOKEN}
|
<name>
field must be named to match the token you chose.Add the following section to your
settings.xml
file.
<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>
gradle
Token type | Name must be | Token |
---|---|---|
Personal access token | Private-Token
| Paste token as-is, or define an environment variable to hold the token |
Deploy token | Deploy-Token
| Paste token as-is, or define an environment variable to hold the token |
CI Job token | Job-Token
| System.getenv("CI_JOB_TOKEN")
|
<name>
field must be named to match the token you chose.In your GRADLE_USER_HOME
directory,
create a file gradle.properties
with the following content:
gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN
Add a repositories
section to your
build.gradle
file:
-
In Groovy DSL:
repositories { maven { url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" name "GitLab" credentials(HttpHeaderCredentials) { name = 'REPLACE_WITH_NAME' value = gitLabPrivateToken } authentication { header(HttpHeaderAuthentication) } } }
-
In Kotlin DSL:
repositories { maven { url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") name = "GitLab" credentials(HttpHeaderCredentials::class) { name = "REPLACE_WITH_NAME" value = findProperty("gitLabPrivateToken") as String? } authentication { create("header", HttpHeaderAuthentication::class) } } }
Basic HTTP Authentication
You can also use basic HTTP authentication to authenticate to the Maven package registry.
mvn
Token type | Name must be | Token |
---|---|---|
Personal access token | The username of the user | Paste token as-is, or define an environment variable to hold the token |
Deploy token | The username of deploy token | Paste token as-is, or define an environment variable to hold the token |
CI Job token | gitlab-ci-token
| ${CI_JOB_TOKEN}
|
Add the following section to your
settings.xml
file.
<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>
gradle
Token type | Name must be | Token |
---|---|---|
Personal access token | The username of the user | Paste token as-is, or define an environment variable to hold the token |
Deploy token | The username of deploy token | Paste token as-is, or define an environment variable to hold the token |
CI Job token | gitlab-ci-token
| System.getenv("CI_JOB_TOKEN")
|
In your GRADLE_USER_HOME
directory,
create a file gradle.properties
with the following content:
gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN
Add a repositories
section to your
build.gradle
.
-
In Groovy DSL:
repositories { maven { url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" name "GitLab" credentials(PasswordCredentials) { username = 'REPLACE_WITH_NAME' password = gitLabPrivateToken } authentication { basic(BasicAuthentication) } } }
-
In Kotlin DSL:
repositories { maven { url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") name = "GitLab" credentials(BasicAuthentication::class) { username = "REPLACE_WITH_NAME" password = findProperty("gitLabPrivateToken") as String? } authentication { create("basic", BasicAuthentication::class) } } }
sbt
Token type | Name must be | Token |
---|---|---|
Personal access token | The username of the user | Paste token as-is, or define an environment variable to hold the token |
Deploy token | The username of deploy token | Paste token as-is, or define an environment variable to hold the token |
CI Job token | gitlab-ci-token
| sys.env.get("CI_JOB_TOKEN").get
|
Authentication for SBT is based on basic HTTP Authentication. You must to provide a name and a password.
To install a package from the Maven GitLab package registry by using sbt
, you must configure
a Maven resolver.
If you’re accessing a private or an internal project or group, you need to set up
credentials.
After configuring the resolver and authentication, you can install a package
from a project, group, or namespace.
In your build.sbt
, add the following lines:
resolvers += ("gitlab" at "<endpoint url>")
credentials += Credentials("GitLab Packages Registry", "<host>", "<name>", "<token>")
In this example:
-
<endpoint url>
is the endpoint URL. Example:https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven
. -
<host>
is the host present in the<endpoint url>
without the protocol scheme or the port. Example:gitlab.example.com
. -
<name>
and<token>
are explained in the table above.
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:
<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.
Project | Package | Instance-level endpoint available |
---|---|---|
foo/bar
| foo/bar/1.0-SNAPSHOT
| Yes |
gitlab-org/gitlab
| foo/bar/1.0-SNAPSHOT
| No |
gitlab-org/gitlab
| gitlab-org/gitlab/1.0-SNAPSHOT
| Yes |
Endpoint URLs
Endpoint | Endpoint URL for pom.xml
| Additional information |
---|---|---|
Project | https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven
| Replace gitlab.example.com with your domain name. Replace <project_id> with your project ID, found on your project’s homepage.
|
Group | https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven
| Replace gitlab.example.com with your domain name. Replace <group_id> with your group ID, found on your group’s homepage.
|
Instance | https://gitlab.example.com/api/v4/packages/maven
| Replace 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.
mvn
No matter which endpoint you choose, you must have:
- A project-specific URL in the
distributionManagement
section. - A
repository
anddistributionManagement
section.
The relevant repository
section of your pom.xml
in Maven should look like this:
<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>
- The
id
is what you defined insettings.xml
. - The
<your_endpoint_url>
depends on which endpoint you choose. - Replace
gitlab.example.com
with your domain name.
gradle
To publish a package by using Gradle:
-
Add the Gradle plugin
maven-publish
to the plugins section:-
In Groovy DSL:
plugins { id 'java' id 'maven-publish' }
-
In Kotlin DSL:
plugins { java `maven-publish` }
-
-
Add a
publishing
section:-
In Groovy DSL:
publishing { publications { library(MavenPublication) { from components.java } } repositories { maven { url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven" credentials(HttpHeaderCredentials) { name = "REPLACE_WITH_TOKEN_NAME" value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties } authentication { header(HttpHeaderAuthentication) } } } }
-
In Kotlin DSL:
publishing { publications { create<MavenPublication>("library") { from(components["java"]) } } repositories { maven { url = uri("https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven") credentials(HttpHeaderCredentials::class) { name = "REPLACE_WITH_TOKEN_NAME" value = findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties } authentication { create("header", HttpHeaderAuthentication::class) } } } }
-
Publish a package
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.
mvn
To publish a package by using Maven:
mvn deploy
If the deploy is successful, the build success message should be displayed:
...
[INFO] BUILD SUCCESS
...
The message should also show that the package was published to the correct location:
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
gradle
Run the publish task:
gradle publish
Go to your project’s Packages and registries page and view the published packages.
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.
mvn
To install a package by using mvn install
:
-
Add the dependency manually to your project
pom.xml
file. To add the example created earlier, the XML would be:<dependency> <groupId>com.mycompany.mydepartment</groupId> <artifactId>my-project</artifactId> <version>1.0-SNAPSHOT</version> </dependency>
-
In your project, run the following:
mvn install
The message should show that the package is downloading from the package registry:
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.
-
In your project directory, run:
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 thesettings.xml
file that contains the authentication details.
-
gitlab-maven
) and the settings.xml
file must match.The message should show that the package is downloading from the package registry:
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
gradle
To install a package by using gradle
:
-
Add a dependency to
build.gradle
in the dependencies section:-
In Groovy DSL:
dependencies { implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT' }
-
In Kotlin DSL:
dependencies { implementation("com.mycompany.mydepartment:my-project:1.0-SNAPSHOT") }
-
-
In your project, run the following:
gradle install
sbt
To install a package by using sbt
:
-
Add an inline dependency to
build.sbt
:libraryDependencies += "com.mycompany.mydepartment" % "my-project" % "8.4"
-
In your project, run the following:
sbt update
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
Required role changed from Developer to Maintainer in GitLab 15.0.
To prevent users from publishing duplicate Maven packages, you can use the GraphQl API or the UI.
In the UI:
- On the left sidebar, select Search or go to and find your group.
- Select Settings > Packages and registries.
- In the Maven row of the Duplicate packages table, turn off the Allow duplicates toggle.
- Optional. In the Exceptions text box, enter a regular expression that matches the names and versions of packages to allow.
Your changes are automatically saved.
Request forwarding to Maven Central
maven_central_request_forwarding
.
This feature is not available for SaaS users.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
:
<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.
mvn
You can create a new package each time the default branch is updated.
-
Create a
ci_settings.xml
file that serves as Maven’ssettings.xml
file. -
Add the
server
section with the same ID you defined in yourpom.xml
file. For example, usegitlab-maven
as the ID:<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>
-
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.<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>
-
Add a
deploy
job to your.gitlab-ci.yml
file:deploy: image: maven:3.6-jdk-11 script: - 'mvn deploy -s ci_settings.xml' rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-
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.
gradle
You can create a package each time the default branch is updated.
-
Authenticate with a CI job token in Gradle.
-
Add a
deploy
job to your.gitlab-ci.yml
file:deploy: image: gradle:6.5-jdk11 script: - 'gradle publish' rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-
Commit files to your repository.
When the pipeline is successful, the Maven package is created.
Version validation
The version string is validated by using the following regex.
\A(?!.*\.\.)[\w+.-]+\z
You can experiment with the regex and try your version strings on this regular expression editor.
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
):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:package: script: - 'mvn -s settings/ci.xml package'
Supported CLI commands
The GitLab Maven repository supports the following CLI commands:
mvn
-
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.
gradle
-
gradle publish
: Publish your package to the package registry. -
gradle install
: Install packages specified in your Gradle project.
Troubleshooting
To improve performance, clients cache files related to a package. If you encounter issues, clear the cache with these commands:
mvn
rm -rf ~/.m2/repository
gradle
rm -rf ~/.gradle/caches # Or replace ~/.gradle with your custom GRADLE_USER_HOME
Review network trace logs
If you are having issues with the Maven Repository, you may want to review network trace logs.
For example, try to run mvn deploy
locally with a PAT token and use these options:
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
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:
mvn-settings:
script:
- 'mvn help:effective-settings'
package:
script:
- 'mvn help:system'
- 'mvn package'