debian-mirror-gitlab/doc/user/packages/maven_repository/index.md

898 lines
28 KiB
Markdown
Raw Normal View History

2020-06-23 00:09:42 +05:30
---
stage: Package
group: Package
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-23 00:09:42 +05:30
---
2021-03-11 19:13:27 +05:30
# Maven packages in the Package Repository **(FREE)**
2019-12-04 20:38:33 +05:30
2021-12-11 22:18:48 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in GitLab 11.3.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
2019-12-04 20:38:33 +05:30
2021-04-29 21:17:54 +05:30
Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry.
2021-01-03 14:25:43 +05:30
Then, install the packages whenever you need to use them as a dependency.
2019-12-04 20:38:33 +05:30
2021-04-29 21:17:54 +05:30
For documentation of the specific API endpoints that the Maven package manager
client uses, see the [Maven API documentation](../../../api/packages/maven.md).
2021-01-03 14:25:43 +05:30
## Build a Maven package
2019-12-04 20:38:33 +05:30
2021-01-03 14:25:43 +05:30
This section explains how to install Maven and build a package.
2019-12-04 20:38:33 +05:30
2021-01-03 14:25:43 +05:30
If you already use Maven and know how to build your own packages, go to the
2021-01-29 00:20:46 +05:30
[next section](#authenticate-to-the-package-registry-with-maven).
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
Maven repositories work well with Gradle, too. To set up a Gradle project, see [get started with Gradle](#build-a-java-project-with-gradle).
2019-12-04 20:38:33 +05:30
2021-01-03 14:25:43 +05:30
### Install Maven
2020-03-13 15:44:24 +05:30
2020-04-22 19:07:51 +05:30
The required minimum versions are:
- Java 11.0.5+
- Maven 3.6+
2020-03-13 15:44:24 +05:30
Follow the instructions at [maven.apache.org](https://maven.apache.org/install.html)
2021-01-29 00:20:46 +05:30
to download and install Maven for your local development environment. After
2020-03-13 15:44:24 +05:30
installation is complete, verify you can use Maven in your terminal by running:
```shell
mvn --version
```
2021-01-29 00:20:46 +05:30
The output should be similar to:
2020-03-13 15:44:24 +05:30
```shell
Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T20:00:29+01:00)
Maven home: /Users/<your_user>/apache-maven-3.6.1
Java version: 12.0.2, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/Contents/Home
Default locale: en_GB, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.2", arch: "x86_64", family: "mac"
```
2021-01-03 14:25:43 +05:30
### Create a project
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
Follow these steps to create a Maven project that can be
2020-03-13 15:44:24 +05:30
published to the GitLab Package Registry.
2021-01-29 00:20:46 +05:30
1. Open your terminal and create a directory to store the project.
1. From the new directory, run this Maven command to initialize a new package:
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
```shell
mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
The arguments are:
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
- `DgroupId`: A unique string that identifies your package. Follow
the [Maven naming conventions](https://maven.apache.org/guides/mini/guide-naming-conventions.html).
- `DartifactId`: The name of the `JAR`, appended to the end of the `DgroupId`.
- `DarchetypeArtifactId`: The archetype used to create the initial structure of
the project.
- `DinteractiveMode`: Create the project using batch mode (optional).
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
This message indicates that the project was set up successfully:
2020-03-13 15:44:24 +05:30
```shell
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.429 s
[INFO] Finished at: 2020-01-28T11:47:04Z
[INFO] ------------------------------------------------------------------------
```
2021-01-29 00:20:46 +05:30
In the folder where you ran the command, a new directory should be displayed.
The directory name should match the `DartifactId` parameter, which in this case,
is `my-project`.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
## Build a Java project with Gradle
2021-01-03 14:25:43 +05:30
This section explains how to install Gradle and initialize a Java project.
2020-05-24 23:13:21 +05:30
2021-01-03 14:25:43 +05:30
If you already use Gradle and know how to build your own packages, go to the
2021-01-29 00:20:46 +05:30
[next section](#authenticate-to-the-package-registry-with-maven).
2020-05-24 23:13:21 +05:30
2021-01-03 14:25:43 +05:30
### Install Gradle
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
If you want to create a new Gradle project, you must install Gradle. Follow
2020-05-24 23:13:21 +05:30
instructions at [gradle.org](https://gradle.org/install/) to download and install
Gradle for your local development environment.
2021-01-29 00:20:46 +05:30
In your terminal, verify you can use Gradle by running:
2020-05-24 23:13:21 +05:30
```shell
gradle -version
```
2021-01-29 00:20:46 +05:30
To use an existing Gradle project, in the project directory,
on Linux execute `gradlew`, or on Windows execute `gradlew.bat`.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
The output should be similar to:
2020-05-24 23:13:21 +05:30
```plaintext
------------------------------------------------------------
Gradle 6.0.1
------------------------------------------------------------
Build time: 2019-11-18 20:25:01 UTC
Revision: fad121066a68c4701acd362daf4287a7c309a0f5
Kotlin: 1.3.50
Groovy: 2.5.8
Ant: Apache Ant(TM) version 1.10.7 compiled on September 1 2019
JVM: 11.0.5 (Oracle Corporation 11.0.5+10)
OS: Windows 10 10.0 amd64
```
2021-01-03 14:25:43 +05:30
### Create a Java project
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
Follow these steps to create a Maven project that can be
2020-05-24 23:13:21 +05:30
published to the GitLab Package Registry.
2021-01-29 00:20:46 +05:30
1. Open your terminal and create a directory to store the project.
1. From this new directory, run this Maven command to initialize a new package:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```shell
gradle init
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
The output should be:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```plaintext
Select type of project to generate:
1: basic
2: application
3: library
4: Gradle plugin
Enter selection (default: basic) [1..4]
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Enter `3` to create a new Library project. The output should be:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```plaintext
Select implementation language:
1: C++
2: Groovy
3: Java
4: Kotlin
5: Scala
6: Swift
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Enter `3` to create a new Java Library project. The output should be:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```plaintext
Select build script DSL:
1: Groovy
2: Kotlin
Enter selection (default: Groovy) [1..2]
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Enter `1` to create a new Java Library project that is described in Groovy DSL. The output should be:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```plaintext
Select test framework:
1: JUnit 4
2: TestNG
3: Spock
4: JUnit Jupiter
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Enter `1` to initialize the project with JUnit 4 testing libraries. The output should be:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```plaintext
Project name (default: test):
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Enter a project name or press Enter to use the directory name as project name.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
## Authenticate to the Package Registry with Maven
2020-03-13 15:44:24 +05:30
2021-03-11 19:13:27 +05:30
To authenticate to the Package Registry, you need one of the following:
2019-12-04 20:38:33 +05:30
2021-03-11 19:13:27 +05:30
- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`.
- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both.
- A [CI_JOB_TOKEN](#authenticate-with-a-ci-job-token-in-maven).
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
### Authenticate with a personal access token in Maven
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
To use a personal access token, add this section to your
[`settings.xml`](https://maven.apache.org/settings.html) file.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
The `name` must be `Private-Token`.
2019-12-04 20:38:33 +05:30
```xml
<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>
```
2021-01-29 00:20:46 +05:30
### Authenticate with a deploy token in Maven
2020-05-24 23:13:21 +05:30
2021-12-11 22:18:48 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in GitLab 13.0.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
To use a deploy token, add this section to your
[`settings.xml`](https://maven.apache.org/settings.html) file.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
The `name` must be `Deploy-Token`.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```xml
<settings>
<servers>
<server>
<id>gitlab-maven</id>
<configuration>
<httpHeaders>
<property>
<name>Deploy-Token</name>
<value>REPLACE_WITH_YOUR_DEPLOY_TOKEN</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
2020-05-24 23:13:21 +05:30
```
2021-01-29 00:20:46 +05:30
### Authenticate with a CI job token in Maven
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
To authenticate with a CI job token, add this section to your
[`settings.xml`](https://maven.apache.org/settings.html) file.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
The `name` must be `Job-Token`.
2019-12-04 20:38:33 +05:30
```xml
<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>
```
2021-01-29 00:20:46 +05:30
Read more about [how to create Maven packages using GitLab CI/CD](#create-maven-packages-with-gitlab-cicd).
## Authenticate to the Package Registry with Gradle
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
To authenticate to the Package Registry, you need either a personal access token or deploy token.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`.
- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both.
### Authenticate with a personal access token in Gradle
Create a file `~/.gradle/gradle.properties` with the following content:
```groovy
gitLabPrivateToken=REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN
```
Add a `repositories` section to your
2020-05-24 23:13:21 +05:30
[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html)
file:
```groovy
repositories {
maven {
2021-01-29 00:20:46 +05:30
url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
2020-05-24 23:13:21 +05:30
name "GitLab"
credentials(HttpHeaderCredentials) {
2021-01-29 00:20:46 +05:30
name = 'Private-Token'
value = gitLabPrivateToken
2020-05-24 23:13:21 +05:30
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
```
2021-01-29 00:20:46 +05:30
### Authenticate with a deploy token in Gradle
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
To authenticate with a deploy token, add a `repositories` section to your
[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html)
file:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```groovy
repositories {
maven {
url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven"
name "GitLab"
credentials(HttpHeaderCredentials) {
name = 'Deploy-Token'
value = '<deploy-token>'
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
2020-05-24 23:13:21 +05:30
```
2021-01-29 00:20:46 +05:30
### Authenticate with a CI job token in Gradle
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
To authenticate with a CI job token, add a `repositories` section to your
2020-05-24 23:13:21 +05:30
[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html)
file:
```groovy
repositories {
maven {
2021-09-04 01:27:46 +05:30
url "${CI_API_V4_URL}/groups/<group>/-/packages/maven"
2020-05-24 23:13:21 +05:30
name "GitLab"
credentials(HttpHeaderCredentials) {
2021-01-29 00:20:46 +05:30
name = 'Job-Token'
value = System.getenv("CI_JOB_TOKEN")
2020-05-24 23:13:21 +05:30
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
```
2021-01-29 00:20:46 +05:30
## Use the GitLab endpoint for Maven packages
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
To use the GitLab endpoint for Maven packages, choose an option:
2019-12-04 20:38:33 +05:30
2021-03-11 19:13:27 +05:30
- **Project-level**: To publish Maven packages to a project, use a project-level endpoint.
To install Maven packages, use a project-level endpoint when you have few Maven packages
and they are not in the same GitLab group.
- **Group-level**: Use a group-level endpoint when you want to install packages from
many different projects in the same GitLab group.
- **Instance-level**: Use an instance-level endpoint when you want to install many
packages from different GitLab groups or in their own namespace.
2021-01-29 00:20:46 +05:30
2021-02-22 17:27:13 +05:30
The option you choose determines the settings you add to your `pom.xml` file.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
In all cases, to publish a package, you need:
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
- A project-specific URL in the `distributionManagement` section.
- A `repository` and `distributionManagement` section.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
### Project-level Maven endpoint
The relevant `repository` section of your `pom.xml`
in Maven should look like this:
2019-12-04 20:38:33 +05:30
```xml
<repositories>
<repository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url>
2019-12-04 20:38:33 +05:30
</snapshotRepository>
</distributionManagement>
```
2021-01-29 00:20:46 +05:30
The corresponding section in Gradle would be:
2020-05-24 23:13:21 +05:30
```groovy
repositories {
maven {
2021-01-29 00:20:46 +05:30
url "https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven"
2020-05-24 23:13:21 +05:30
name "GitLab"
}
}
```
2021-01-29 00:20:46 +05:30
- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven).
- The `PROJECT_ID` is your project ID, which you can view on your project's home page.
- Replace `gitlab.example.com` with your domain name.
- For retrieving artifacts, use either the
2021-09-30 23:02:18 +05:30
[URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project
2021-01-29 00:20:46 +05:30
(like `group%2Fproject`) or the project's ID (like `42`). However, only the
project's ID can be used for publishing.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
### Group-level Maven endpoint
2019-12-04 20:38:33 +05:30
2021-12-11 22:18:48 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in GitLab 11.7.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
2019-12-04 20:38:33 +05:30
If you rely on many packages, it might be inefficient to include the `repository` section
2021-01-29 00:20:46 +05:30
with a unique URL for each package. Instead, you can use the group-level endpoint for
all the Maven packages stored within one GitLab group. Only packages you have access to
2020-11-24 15:15:51 +05:30
are available for download.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
The group-level endpoint works with any package names, so you
have more flexibility in naming, compared to the [instance-level endpoint](#instance-level-maven-endpoint).
However, GitLab does not guarantee the uniqueness of package names within
2019-12-04 20:38:33 +05:30
the group. You can have two projects with the same package name and package
2020-11-24 15:15:51 +05:30
version. As a result, GitLab serves whichever one is more recent.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
This example shows the relevant `repository` section of your `pom.xml` file.
You still need a project-specific URL for publishing a package in
2019-12-04 20:38:33 +05:30
the `distributionManagement` section:
```xml
<repositories>
<repository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url>
2019-12-04 20:38:33 +05:30
</snapshotRepository>
</distributionManagement>
```
2021-01-29 00:20:46 +05:30
For Gradle, the corresponding `repositories` section would look like:
2020-05-24 23:13:21 +05:30
```groovy
repositories {
maven {
2021-01-29 00:20:46 +05:30
url "https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven"
2020-05-24 23:13:21 +05:30
name "GitLab"
}
}
```
2021-01-29 00:20:46 +05:30
- For the `id`, use what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven).
2021-03-11 19:13:27 +05:30
- For `GROUP_ID`, use your group ID, which you can view on your group's home page.
2021-01-29 00:20:46 +05:30
- For `PROJECT_ID`, use your project ID, which you can view on your project's home page.
- Replace `gitlab.example.com` with your domain name.
- For retrieving artifacts, use either the
2021-09-30 23:02:18 +05:30
[URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the group
2021-01-29 00:20:46 +05:30
(like `group%2Fsubgroup`) or the group's ID (like `12`).
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
### Instance-level Maven endpoint
2019-12-04 20:38:33 +05:30
2021-12-11 22:18:48 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in GitLab 11.7.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3.
2019-12-04 20:38:33 +05:30
If you rely on many packages, it might be inefficient to include the `repository` section
2021-01-29 00:20:46 +05:30
with a unique URL for each package. Instead, you can use the instance-level endpoint for
all Maven packages stored in GitLab. All packages you have access to are available
2019-12-04 20:38:33 +05:30
for download.
2021-01-29 00:20:46 +05:30
**Only packages that have the same path as the project** are exposed by
the instance-level endpoint.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
| Project | Package | Instance-level endpoint available |
2019-12-04 20:38:33 +05:30
| ------- | ------- | --------------------------------- |
| `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 |
2021-01-29 00:20:46 +05:30
This example shows how relevant `repository` section of your `pom.xml`.
You still need a project-specific URL in the `distributionManagement` section.
2019-12-04 20:38:33 +05:30
```xml
<repositories>
<repository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
2021-01-29 00:20:46 +05:30
<url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url>
2019-12-04 20:38:33 +05:30
</snapshotRepository>
</distributionManagement>
```
2020-05-24 23:13:21 +05:30
The corresponding repositories section in Gradle would look like:
```groovy
repositories {
maven {
2021-01-29 00:20:46 +05:30
url "https://gitlab.example.com/api/v4/packages/maven"
2020-05-24 23:13:21 +05:30
name "GitLab"
}
}
```
2021-01-29 00:20:46 +05:30
- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven).
- The `PROJECT_ID` is your project ID, which you can view on your project's home page.
- Replace `gitlab.example.com` with your domain name.
- For retrieving artifacts, use either the
2021-09-30 23:02:18 +05:30
[URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project
2021-01-29 00:20:46 +05:30
(like `group%2Fproject`) or the project's ID (like `42`). However, only the
project's ID can be used for publishing.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
## Publish a package
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
After you have set up the [remote and authentication](#authenticate-to-the-package-registry-with-maven)
and [configured your project](#use-the-gitlab-endpoint-for-maven-packages),
2021-03-11 19:13:27 +05:30
publish a Maven package to your project.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
### Publish by using Maven
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
To publish a package by using Maven:
2019-12-04 20:38:33 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-12-04 20:38:33 +05:30
mvn deploy
```
2021-01-29 00:20:46 +05:30
If the deploy is successful, the build success message should be displayed:
2020-03-13 15:44:24 +05:30
```shell
...
[INFO] BUILD SUCCESS
...
```
2021-01-29 00:20:46 +05:30
The message should also show that the package was published to the correct location:
2020-03-13 15:44:24 +05:30
```shell
2021-01-29 00:20:46 +05:30
Uploading to gitlab-maven: https://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.jar
2020-03-13 15:44:24 +05:30
```
2021-01-29 00:20:46 +05:30
### Publish by using Gradle
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
To publish a package by using Gradle:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```groovy
plugins {
id 'java'
id 'maven-publish'
}
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Add a `publishing` section:
```groovy
publishing {
publications {
library(MavenPublication) {
from components.java
}
}
repositories {
maven {
url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven"
credentials(HttpHeaderCredentials) {
name = "Private-Token"
value = gitLabPrivateToken // the variable resides in ~/.gradle/gradle.properties
}
authentication {
header(HttpHeaderAuthentication)
}
}
}
}
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Replace `PROJECT_ID` with your project ID, which can be found on your project's home page.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Run the publish task:
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
```shell
gradle publish
```
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
Now navigate to your project's **Packages & Registries** page and view the published artifacts.
2019-12-04 20:38:33 +05:30
2021-03-11 19:13:27 +05:30
### Publishing a package with the same name or version
2021-09-04 01:27:46 +05:30
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 files.
To delete these older package versions, consider using the Packages API or the UI.
2021-03-11 19:13:27 +05:30
#### Do not allow duplicate Maven packages
2021-12-11 22:18:48 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296895) in GitLab 13.9.
2021-03-11 19:13:27 +05:30
To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI.
In the UI:
1. For your group, go to **Settings > Packages & Registries**.
1. Expand the **Package Registry** section.
1. Turn on the **Reject duplicates** toggle.
2021-06-08 01:23:25 +05:30
1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names and/or versions of packages you want to allow.
2021-03-11 19:13:27 +05:30
Your changes are automatically saved.
2021-01-29 00:20:46 +05:30
## Install a package
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
To install a package from the GitLab Package Registry, you must configure
the [remote and authenticate](#authenticate-to-the-package-registry-with-maven).
2021-03-11 19:13:27 +05:30
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.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
### Use Maven with `mvn install`
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
To install a package by using `mvn install`:
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
1. Add the dependency manually to your project `pom.xml` file.
To add the example created earlier, the XML would be:
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
```xml
<dependency>
<groupId>com.mycompany.mydepartment</groupId>
<artifactId>my-project</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
```
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
1. In your project, run the following:
```shell
mvn install
```
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
The message should show that the package is downloading from the Package Registry:
2020-03-13 15:44:24 +05:30
```shell
2021-01-29 00:20:46 +05:30
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
2020-03-13 15:44:24 +05:30
```
2021-01-29 00:20:46 +05:30
### Use Maven with `mvn dependency:get`
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
You can install packages by using the Maven commands directly.
1. In your project directory, run:
```shell
mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT
```
The message should show that the package is downloading from the Package Registry:
2020-03-13 15:44:24 +05:30
```shell
2021-01-29 00:20:46 +05:30
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
2020-03-13 15:44:24 +05:30
```
2021-02-22 17:27:13 +05:30
NOTE:
2021-01-29 00:20:46 +05:30
In the GitLab UI, on the Package Registry page for Maven, you can view and copy these commands.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
### Use Gradle
2020-05-24 23:13:21 +05:30
2021-01-03 14:25:43 +05:30
Add a [dependency](https://docs.gradle.org/current/userguide/declaring_dependencies.html) to `build.gradle` in the dependencies section:
2020-05-24 23:13:21 +05:30
```groovy
dependencies {
implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT'
}
```
2021-01-29 00:20:46 +05:30
## Remove a package
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
For your project, go to **Packages & Registries > Package Registry**.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
To remove a package, click the red trash icon or, from the package details, the **Delete** button.
2019-12-04 20:38:33 +05:30
2021-01-29 00:20:46 +05:30
## Create Maven packages with GitLab CI/CD
After you have configured your repository to use the Package Repository for Maven,
2020-05-24 23:13:21 +05:30
you can configure GitLab CI/CD to build new packages automatically.
2021-01-29 00:20:46 +05:30
### Create Maven packages with GitLab CI/CD by using Maven
2020-05-24 23:13:21 +05:30
2021-10-27 15:23:28 +05:30
You can create a new package each time the `main` branch is updated.
2019-12-04 20:38:33 +05:30
2020-11-24 15:15:51 +05:30
1. Create a `ci_settings.xml` file that serves as Maven's `settings.xml` file.
2021-01-29 00:20:46 +05:30
1. Add the `server` section with the same ID you defined in your `pom.xml` file.
For example, use `gitlab-maven` as the ID:
2019-12-04 20:38:33 +05:30
```xml
<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>
```
2021-01-29 00:20:46 +05:30
1. Make sure your `pom.xml` file includes the following.
2021-03-11 19:13:27 +05:30
You can either let Maven use the [predefined CI/CD variables](../../../ci/variables/predefined_variables.md), as shown in this example,
2021-02-22 17:27:13 +05:30
or you can hard code your server's hostname and project's ID.
2019-12-04 20:38:33 +05:30
```xml
<repositories>
<repository>
<id>gitlab-maven</id>
2021-09-30 23:02:18 +05:30
<url>${env.CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
</repositories>
<distributionManagement>
<repository>
<id>gitlab-maven</id>
2021-09-04 01:27:46 +05:30
<url>${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
2021-09-04 01:27:46 +05:30
<url>${CI_API_V4_URL}/projects/${env.CI_PROJECT_ID}/packages/maven</url>
2019-12-04 20:38:33 +05:30
</snapshotRepository>
</distributionManagement>
```
1. Add a `deploy` job to your `.gitlab-ci.yml` file:
```yaml
deploy:
2020-10-24 23:57:45 +05:30
image: maven:3.6-jdk-11
2019-12-04 20:38:33 +05:30
script:
- 'mvn deploy -s ci_settings.xml'
only:
2021-10-27 15:23:28 +05:30
- main
2019-12-04 20:38:33 +05:30
```
1. Push those files to your repository.
2020-11-24 15:15:51 +05:30
The next time the `deploy` job runs, it copies `ci_settings.xml` to the
2021-01-29 00:20:46 +05:30
user's home location. In this example:
- The user is `root`, because the job runs in a Docker container.
2021-03-11 19:13:27 +05:30
- Maven uses the configured CI/CD variables.
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
### Create Maven packages with GitLab CI/CD by using Gradle
2020-05-24 23:13:21 +05:30
2021-10-27 15:23:28 +05:30
You can create a package each time the `main` branch
2021-01-29 00:20:46 +05:30
is updated.
2020-05-24 23:13:21 +05:30
2021-01-29 00:20:46 +05:30
1. Authenticate with [a CI job token in Gradle](#authenticate-with-a-ci-job-token-in-gradle).
2020-05-24 23:13:21 +05:30
1. Add a `deploy` job to your `.gitlab-ci.yml` file:
```yaml
deploy:
2020-10-24 23:57:45 +05:30
image: gradle:6.5-jdk11
2020-05-24 23:13:21 +05:30
script:
- 'gradle publish'
only:
2021-10-27 15:23:28 +05:30
- main
2020-05-24 23:13:21 +05:30
```
2021-01-29 00:20:46 +05:30
1. Commit files to your repository.
When the pipeline is successful, the package is created.
2020-05-24 23:13:21 +05:30
2020-07-28 23:09:34 +05:30
### Version validation
2021-01-29 00:20:46 +05:30
The version string is validated by using the following regex.
2020-07-28 23:09:34 +05:30
```ruby
2021-12-07 22:27:20 +05:30
\A(?!.*\.\.)[\w+.-]+\z
2020-07-28 23:09:34 +05:30
```
You can play around with the regex and try your version strings on [this regular expression editor](https://rubular.com/r/rrLQqUXjfKEoL6).
2020-03-13 15:44:24 +05:30
## Troubleshooting
2021-09-30 23:02:18 +05:30
To improve performance, Maven caches files related to a package. If you encounter issues, clear
the cache with these commands:
```shell
rm -rf ~/.m2/repository
```
If you're using Gradle, run this command to clear the cache:
```shell
rm -rf ~/.gradle/caches
```
2020-10-24 23:57:45 +05:30
### 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:
```shell
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
```
2021-02-22 17:27:13 +05:30
WARNING:
2020-10-24 23:57:45 +05:30
When you set these options, all network requests are logged and a large amount of output is generated.
### Useful Maven command-line options
2020-03-13 15:44:24 +05:30
2020-10-24 23:57:45 +05:30
There are some [Maven command-line options](https://maven.apache.org/ref/current/maven-embedder/cli.html)
2021-01-29 00:20:46 +05:30
that you can use when performing tasks with GitLab CI/CD.
2020-03-13 15:44:24 +05:30
- File transfer progress can make the CI logs hard to read.
Option `-ntp,--no-transfer-progress` was added in
[3.6.1](https://maven.apache.org/docs/3.6.1/release-notes.html#User_visible_Changes).
Alternatively, look at `-B,--batch-mode`
[or lower level logging changes.](https://stackoverflow.com/questions/21638697/disable-maven-download-progress-indication)
2021-01-29 00:20:46 +05:30
- Specify where to find the `pom.xml` file (`-f,--file`):
2020-03-13 15:44:24 +05:30
```yaml
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](https://maven.apache.org/settings.html). There's also a `-gs,--global-settings` option:
```yaml
package:
script:
- 'mvn -s settings/ci.xml package'
```
2021-01-29 00:20:46 +05:30
### Verify your Maven settings
2020-03-13 15:44:24 +05:30
2021-01-29 00:20:46 +05:30
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](https://maven.apache.org/plugins/maven-help-plugin/effective-settings-mojo.html).
2020-03-13 15:44:24 +05:30
The help plugin can also provide
[system properties](https://maven.apache.org/plugins/maven-help-plugin/system-mojo.html), including environment variables:
```yaml
mvn-settings:
script:
- 'mvn help:effective-settings'
package:
script:
- 'mvn help:system'
- 'mvn package'
```
2021-04-29 21:17:54 +05:30
## Supported CLI commands
The GitLab Maven repository supports the following Maven 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.