Previously, we used brackets to denote the tier badges, but this made Kramdown, the docs site Markdown renderer, show many warnings when building the site. This is now fixed by using parentheses instead of square brackets. This was caused by [PREMIUM] looking like a link to Kramdown, which couldn't find a URL there. See: - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/484 - https://gitlab.com/gitlab-org/gitlab-ce/issues/63800
12 KiB
GitLab Maven Repository (PREMIUM)
Introduced in GitLab Premium 11.3.
With the GitLab Maven Repository, every project can have its own space to store its Maven artifacts.
Enabling the Maven Repository
NOTE: Note: This option is available only if your GitLab administrator has enabled support for the Maven repository.(PREMIUM ONLY)
After the Packages feature is enabled, the Maven Repository will be available for all new projects by default. To enable it for existing projects, or if you want to disable it:
- Navigate to your project's Settings > General > Permissions.
- Find the Packages feature and enable or disable it.
- Click on Save changes for the changes to take effect.
You should then be able to see the Packages section on the left sidebar. Next, you must configure your project to authorize with the GitLab Maven repository.
Authenticating to the GitLab Maven Repository
If a project is private or you want to upload Maven artifacts to GitLab, credentials will need to be provided for authorization. Support is available for personal access tokens and CI job tokens only. Deploy tokens and regular username/password credentials do not work.
Authenticating with a personal access token
To authenticate with a personal access token,
add a corresponding section to your
settings.xml
file:
<settings>
<servers>
<server>
<id>gitlab-maven</id>
<configuration>
<httpHeaders>
<property>
<name>Private-Token</name>
<value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
You should now be able to upload Maven artifacts to your project.
Authenticating with a CI job token
If you're using Maven with GitLab CI/CD, a CI job token can be used instead of a personal access token.
To authenticate with a CI job token, add a corresponding section to your
settings.xml
file:
<settings>
<servers>
<server>
<id>gitlab-maven</id>
<configuration>
<httpHeaders>
<property>
<name>Job-Token</name>
<value>${env.CI_JOB_TOKEN}</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
You can read more on how to create Maven packages using GitLab CI/CD.
Configuring your project to use the GitLab Maven repository URL
To download and upload packages from GitLab, you need a repository
and
distributionManagement
section in your pom.xml
file.
Depending on your workflow and the amount of Maven packages you have, there are 3 ways you can configure your project to use the GitLab endpoint for Maven packages:
- Project level: Useful when you have few Maven packages which are not under the same GitLab group.
- Group level: Useful when you have many Maven packages under the same GitLab group.
- Instance level: Useful when you have many Maven packages under different GitLab groups or on their own namespace.
NOTE: Note:
In all cases, you need a project specific URL for uploading a package in
the distributionManagement
section.
Project level Maven endpoint
The example below shows how the relevant repository
section of your pom.xml
would look like:
<repositories>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</snapshotRepository>
</distributionManagement>
The id
must be the same with what you
defined in settings.xml
.
Replace PROJECT_ID
with your project ID which can be found on the home page
of your project.
If you have a self-hosted GitLab installation, replace gitlab.com
with your
domain name.
NOTE: Note:
For retrieving artifacts, you can use either the
URL encoded path of the project
(e.g., group%2Fproject
) or the project's ID (e.g., 42
). However, only the
project's ID can be used for uploading.
Group level Maven endpoint
Introduced in GitLab Premium 11.7.
If you rely on many packages, it might be inefficient to include the repository
section
with a unique URL for each package. Instead, you can use the group level endpoint for
all your Maven packages stored within one GitLab group. Only packages you have access to
will be available for download.
The group level endpoint works with any package names, which means the you have the flexibility of naming compared to instance level endpoint. However, GitLab will not guarantee the uniqueness of the package names within the group. You can have two projects with the same package name and package version. As a result, GitLab will serve whichever one is more recent.
The example below shows how the relevant repository
section of your pom.xml
would look like. You still need a project specific URL for uploading a package in
the distributionManagement
section:
<repositories>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/groups/my-group/-/packages/maven</url>
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</snapshotRepository>
</distributionManagement>
The id
must be the same with what you
defined in settings.xml
.
Replace my-group
with your group name and PROJECT_ID
with your project ID
which can be found on the home page of your project.
If you have a self-hosted GitLab installation, replace gitlab.com
with your
domain name.
NOTE: Note:
For retrieving artifacts, you can use either the
URL encoded path of the group
(e.g., group%2Fsubgroup
) or the group's ID (e.g., 12
).
Instance level Maven endpoint
Introduced in GitLab Premium 11.7.
If you rely on many packages, it might be inefficient to include the repository
section
with a unique URL for each package. Instead, you can use the instance level endpoint for
all maven packages stored in GitLab and the packages you have access to will be available
for download.
Note that only packages that have the same path as the project are exposed via the instance level endpoint.
Project | Package | Instance level endpoint available |
---|---|---|
foo/bar |
foo/bar/1.0-SNAPSHOT |
Yes |
gitlab-org/gitlab-ce |
foo/bar/1.0-SNAPSHOT |
No |
gitlab-org/gitlab-ce |
gitlab-org/gitlab-ce/1.0-SNAPSHOT |
Yes |
The example below shows how the relevant repository
section of your pom.xml
would look like. You still need a project specific URL for uploading a package in
the distributionManagement
section:
<repositories>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/packages/maven</url>
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</snapshotRepository>
</distributionManagement>
The id
must be the same with what you
defined in settings.xml
.
Replace PROJECT_ID
with your project ID which can be found on the home page
of your project.
If you have a self-hosted GitLab installation, replace gitlab.com
with your
domain name.
NOTE: Note:
For retrieving artifacts, you can use either the
URL encoded path of the project
(e.g., group%2Fproject
) or the project's ID (e.g., 42
). However, only the
project's ID can be used for uploading.
Uploading packages
Once you have set up the authentication and configuration, test to upload a Maven artifact from a project of yours:
mvn deploy
You can then navigate to your project's Packages page and see the uploaded artifacts or even delete them.
Creating Maven packages with GitLab CI/CD
Once you have your repository configured to use the GitLab Maven Repository,
you can configure GitLab CI/CD to build new packages automatically. The example below
shows how to create a new package each time the master
branch is updated:
-
Create a
ci_settings.xml
file that will serve as Maven'ssettings.xml
file. Add the server section with the same id you defined in yourpom.xml
file. For example, in our case it'sgitlab-maven
:<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>${env.CI_JOB_TOKEN}</value> </property> </httpHeaders> </configuration> </server> </servers> </settings>
-
Make sure your
pom.xml
file includes the following:<repositories> <repository> <id>gitlab-maven</id> <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> <url>https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url> </snapshotRepository> </distributionManagement>
TIP: Tip: You can either let Maven utilize the CI environment variables or hardcode your project's ID.
-
Add a
deploy
job to your.gitlab-ci.yml
file:deploy: image: maven:3.3.9-jdk-8 script: - 'mvn deploy -s ci_settings.xml' only: - master
-
Push those files to your repository.
The next time the deploy
job runs, it will copy ci_settings.xml
to the
user's home location (in this case the user is root
since it runs in a
Docker container), and Maven will utilize the configured CI
environment variables.