diff options
Diffstat (limited to 'doc/user/packages/maven_repository/index.md')
| -rw-r--r-- | doc/user/packages/maven_repository/index.md | 368 |
1 files changed, 351 insertions, 17 deletions
diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index b4aec11d029..51e62dc871e 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -21,17 +21,19 @@ to disable it: 1. Find the Packages feature and enable or disable it. 1. Click on **Save changes** for the changes to take effect. -You should then be able to see the **Packages** section on the left sidebar. +You should then be able to see the **Packages & Registries** section on the left sidebar. Next, you must configure your project to authorize with the GitLab Maven repository. -## Getting Started +## Getting Started with Maven This section will cover installing Maven and building a package. This is a quickstart to help if you're new to building Maven packages. If you're already using Maven and understand how to build your own packages, move onto the [next section](#adding-the-gitlab-package-registry-as-a-maven-remote). +Maven repositories work well with Gradle, too. Move onto [getting started with Gradle](#getting-started-with-gradle) if you want to setup a Gradle project. + ### Installing Maven The required minimum versions are: @@ -96,20 +98,129 @@ your project has been set up successfully: You should see a new directory where you ran this command matching your `DartifactId` parameter (in this case it should be `my-project`). +## Getting started with Gradle + +This section will cover installing Gradle and initializing a Java project. This is a +quickstart to help if you're new to Gradle. If you're already +using Gradle and understand how to build your own packages, move onto the +[next section](#adding-the-gitlab-package-registry-as-a-maven-remote). + +### Installing Gradle + +Installation is needed only if you want to create a new Gradle project. Follow +instructions at [gradle.org](https://gradle.org/install/) to download and install +Gradle for your local development environment. + +Verify you can use Gradle in your terminal by running: + +```shell +gradle -version +``` + +If you want to use an existing Gradle project, installation is not necessary. +Simply execute `gradlew` (on Linux) or `gradlew.bat` (on Windows) in the project +directory instead. + +You should see something imilar to the below printed in the output: + +```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 +``` + +### Creating a project in Gradle + +Understanding how to create a full Java project in Gradle is outside the scope of this +guide, but you can follow the steps below to create a new project that can be +published to the GitLab Package Registry. + +Start by opening your terminal and creating a directory where you would like to +store the project in your environment. From inside the directory, you can run +the following Maven command to initialize a new package: + +```shell +gradle init +``` + +The output should be + +```plaintext +Select type of project to generate: + 1: basic + 2: application + 3: library + 4: Gradle plugin +Enter selection (default: basic) [1..4] +``` + +Enter `3` to create a new Library project. The output should be: + +```plaintext +Select implementation language: + 1: C++ + 2: Groovy + 3: Java + 4: Kotlin + 5: Scala + 6: Swift +``` + +Enter `3` to create a new Java Library project. The output should be: + +```plaintext +Select build script DSL: + 1: Groovy + 2: Kotlin +Enter selection (default: Groovy) [1..2] +``` + +Choose `1` to create a new Java Library project which will be described in Groovy DSL. The output should be: + +```plaintext +Select test framework: + 1: JUnit 4 + 2: TestNG + 3: Spock + 4: JUnit Jupiter +``` + +Choose `1` to initialize the project with JUnit 4 testing libraries. The output should be: + +```plaintext +Project name (default: test): +``` + +Enter a project name or hit enter to use the directory name as project name. + ## Adding the GitLab Package Registry as a Maven remote The next step is to add the GitLab Package Registry as a Maven remote. If a project is private or you want to upload Maven artifacts to GitLab, credentials will need to be provided for authorization too. Support is available -for [personal access tokens](#authenticating-with-a-personal-access-token) and -[CI job tokens](#authenticating-with-a-ci-job-token) only. -[Deploy tokens](../../project/deploy_tokens/index.md) and regular username/password +for [personal access tokens](#authenticating-with-a-personal-access-token), +[CI job tokens](#authenticating-with-a-ci-job-token), and +[deploy tokens](../../project/deploy_tokens/index.md) only. Regular username/password credentials do not work. ### Authenticating with a personal access token To authenticate with a [personal access token](../../profile/personal_access_tokens.md), -set the scope to `api` and add a corresponding section to your +set the scope to `api` when creating one, and add it to your Maven or Gradle configuration +files. + +#### Authenticating with a personal access token in Maven + +Add a corresponding section to your [`settings.xml`](https://maven.apache.org/settings.html) file: ```xml @@ -130,13 +241,43 @@ set the scope to `api` and add a corresponding section to your </settings> ``` +#### Authenticating 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 +[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) +file: + +```groovy +repositories { + maven { + url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" + name "GitLab" + credentials(HttpHeaderCredentials) { + name = 'Private-Token' + value = gitLabPrivateToken + } + authentication { + header(HttpHeaderAuthentication) + } + } +} +``` + 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 +If you're using GitLab CI/CD, a CI job token can be used instead of a personal access token. +#### Authenticating with a CI job token in Maven + To authenticate with a CI job token, add a corresponding section to your [`settings.xml`](https://maven.apache.org/settings.html) file: @@ -161,6 +302,81 @@ To authenticate with a CI job token, add a corresponding section to your You can read more on [how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd). +#### Authenticating with a CI job token in Gradle + +To authenticate with a CI job token, add a repositories section to your +[`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html) +file: + +```groovy +repositories { + maven { + url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" + name "GitLab" + credentials(HttpHeaderCredentials) { + name = 'Job-Token' + value = '${CI_JOB_TOKEN}' + } + authentication { + header(HttpHeaderAuthentication) + } + } +} +``` + +### Authenticating with a deploy token + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0. + +To authenticate with a [deploy token](./../../project/deploy_tokens/index.md), +set the scope to `api` when creating one, and add it to your Maven or Gradle configuration +files. + +#### Authenticating with a deploy token in Maven + +Add a corresponding section to your +[`settings.xml`](https://maven.apache.org/settings.html) file: + +```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> +``` + +#### Authenticating with a deploy token in Gradle + +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: + +```groovy +repositories { + maven { + url "https://<gitlab-url>/api/v4/groups/<group>/-/packages/maven" + name "GitLab" + credentials(HttpHeaderCredentials) { + name = 'Deploy-Token' + value = '<deploy-token>' + } + authentication { + header(HttpHeaderAuthentication) + } + } +} +``` + ## Configuring your project to use the GitLab Maven repository URL To download and upload packages from GitLab, you need a `repository` and @@ -185,7 +401,7 @@ the `distributionManagement` section. ### Project level Maven endpoint The example below shows how the relevant `repository` section of your `pom.xml` -would look like: +would look like in Maven: ```xml <repositories> @@ -206,6 +422,17 @@ would look like: </distributionManagement> ``` +The corresponding section in Gradle would look like this: + +```groovy +repositories { + maven { + url "https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven" + name "GitLab" + } +} +``` + The `id` must be the same with what you [defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote). @@ -223,7 +450,7 @@ project's ID can be used for uploading. ### Group level Maven endpoint -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in GitLab Premium 11.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8798) in [GitLab Premium](https://about.gitlab.com/pricing/) 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 @@ -259,6 +486,17 @@ the `distributionManagement` section: </distributionManagement> ``` +For Gradle, the corresponding repositories section would look like: + +```groovy +repositories { + maven { + url "https://gitlab.com/api/v4/groups/GROUP_ID/-/packages/maven" + name "GitLab" + } +} +``` + The `id` must be the same with what you [defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote). @@ -275,7 +513,7 @@ For retrieving artifacts, you can use either the ### Instance level Maven endpoint -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in GitLab Premium 11.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/8274) in [GitLab Premium](https://about.gitlab.com/pricing/) 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 @@ -314,6 +552,17 @@ the `distributionManagement` section: </distributionManagement> ``` +The corresponding repositories section in Gradle would look like: + +```groovy +repositories { + maven { + url "https://gitlab.com/api/v4/packages/maven" + name "GitLab" + } +} +``` + The `id` must be the same with what you [defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote). @@ -333,7 +582,9 @@ project's ID can be used for uploading. Once you have set up the [remote and authentication](#adding-the-gitlab-package-registry-as-a-maven-remote) and [configured your project](#configuring-your-project-to-use-the-gitlab-maven-repository-url), -test to upload a Maven artifact from a project of yours: +test to upload a Maven artifact from a project of yours. + +### Upload using Maven ```shell mvn deploy @@ -353,7 +604,51 @@ You should also see that the upload was uploaded to the correct registry: Uploading to gitlab-maven: https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar ``` -You can then navigate to your project's **Packages** page and see the uploaded +### Upload using Gradle + +Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: + +```groovy +plugins { + id 'java' + id 'maven-publish' +} +``` + +Add a `publishing` section: + +```groovy +publishing { + publications { + library(MavenPublication) { + from components.java + } + } + repositories { + maven { + url "https://gitlab.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) + } + } + } +} +``` + +Replace `PROJECT_ID` with your project ID which can be found on the home page +of your project. + +Run the publish task: + +```shell +gradle publish +``` + +You can then navigate to your project's **Packages & Registries** page and see the uploaded artifacts or even delete them. ## Installing a package @@ -362,7 +657,7 @@ Installing a package from the GitLab Package Registry requires that you set up the [remote and authentication](#adding-the-gitlab-package-registry-as-a-maven-remote) as above. Once this is completed, there are two ways for installaing a package. -### Install with `mvn install` +### Install using Maven with `mvn install` Add the dependency manually to your project `pom.xml` file. To add the example created above, the XML would look like: @@ -388,7 +683,7 @@ downloaded from the GitLab Package Registry: Downloading from gitlab-maven: http://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom ``` -### Install with `mvn dependency:get` +#### Install with `mvn dependency:get` The second way to install packages is to use the Maven commands directly. Inside your project directory, run: @@ -404,6 +699,16 @@ TIP: **Tip:** Both the XML block and Maven command are readily copy and pastable from the Package details page, allowing for quick and easy installation. +### Install using Gradle + +Add a [dependency](https://docs.gradle.org/current/userguide/declaring_dependencies.html) to build.gradle in the dependencies section: + +```groovy +dependencies { + implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT' +} +``` + ## Removing a package In the packages view of your project page, you can delete packages by clicking @@ -413,11 +718,15 @@ page. ## 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: +you can configure GitLab CI/CD to build new packages automatically. + +### Creating Maven packages with GitLab CI/CD using Maven + +The example below shows how to create a new package each time the `master` branch +is updated: 1. Create a `ci_settings.xml` file that will serve as Maven's `settings.xml` file. - Add the server section with the same id you defined in your `pom.xml` file. + Add the server section with the same ID you defined in your `pom.xml` file. For example, in our case it's `gitlab-maven`: ```xml @@ -481,6 +790,31 @@ 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](../../../ci/variables/README.md#predefined-environment-variables). +### Creating Maven packages with GitLab CI/CD using Gradle + +The example below shows how to create a new package each time the `master` branch +is updated: + +1. Make sure you use the Job-Token authentication as described in ["Authenticating with a CI job token in Gradle"](#authenticating-with-a-ci-job-token-in-gradle). + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + deploy: + image: gradle:latest + script: + - 'gradle publish' + only: + - master + ``` + +1. 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 use the configured CI +[environment variables](../../../ci/variables/README.md#predefined-environment-variables). + ## Troubleshooting ### Useful Maven command line options |