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

845 lines
26 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-01-03 14:25:43 +05:30
# Maven packages in the Package Repository
2019-12-04 20:38:33 +05:30
2020-10-24 23:57:45 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
2019-12-04 20:38:33 +05:30
2021-01-03 14:25:43 +05:30
Publish [Maven](https://maven.apache.org) artifacts in your projects Package Registry.
Then, install the packages whenever you need to use them as a dependency.
2019-12-04 20:38:33 +05:30
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-01-29 00:20:46 +05:30
To authenticate to the Package Registry, you need either a personal access token or deploy token.
2019-12-04 20:38:33 +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.
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-01-29 00:20:46 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core 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-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 = '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-01-29 00:20:46 +05:30
- **Project-level**: Use when you have few Maven packages and they are not in
2019-12-04 20:38:33 +05:30
the same GitLab group.
2021-01-29 00:20:46 +05:30
- **Group-level**: Use when you have many Maven packages in the same GitLab
2019-12-04 20:38:33 +05:30
group.
2021-01-29 00:20:46 +05:30
- **Instance-level**: Use when you have many Maven packages in different
GitLab groups or in their own namespace.
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
[URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project
(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-01-29 00:20:46 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core 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).
- For `my-group`, use your group name.
- 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
[URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the group
(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-01-29 00:20:46 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core 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
[URL-encoded](../../../api/README.md#namespaced-path-encoding) path of the project
(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),
publish a Maven artifact from 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-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).
When this is completed, there are two ways to install a package.
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-01-29 00:20:46 +05:30
You can create a new package each time the `master` 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.
You can either let Maven use the CI environment variables, 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-02-22 17:27:13 +05:30
<url>${env.CI_SERVER_URL}/api/v4/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-02-22 17:27:13 +05:30
<url>${env.CI_SERVER_URL}/api/v4/projects/${env.CI_PROJECT_ID}/packages/maven</url>
2019-12-04 20:38:33 +05:30
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
2021-02-22 17:27:13 +05:30
<url>${env.CI_SERVER_URL}/api/v4/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:
- master
```
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.
- Maven uses the configured CI [environment variables](../../../ci/variables/README.md#predefined-environment-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-01-29 00:20:46 +05:30
You can create a package each time the `master` branch
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:
- master
```
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
\A(\.?[\w\+-]+\.?)+\z
```
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
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'
```