Merge branch 'master' into 'master'

Docs feedback: Maven repository - Add examples for Gradle

Closes #213187

See merge request gitlab-org/gitlab!29039

doc/user/packages/maven_repository/index.md

@@ -25,13 +25,15 @@ 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.
 
-## 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,6 +98,110 @@ 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
@@ -109,7 +215,12 @@ 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,28 @@ 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)
+        }
+    }
+}
+```
+
 ## Configuring your project to use the GitLab Maven repository URL
 
 To download and upload packages from GitLab, you need a `repository` and
@@ -185,7 +348,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 +369,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).
 
@@ -259,6 +433,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).
 
@@ -314,6 +499,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 +529,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,6 +551,50 @@ 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
 ```
 
+### 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** page and see the uploaded
 artifacts or even delete them.
 
@@ -362,7 +604,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 +630,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 +646,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,8 +665,12 @@ 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.
@@ -481,6 +737,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