diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-04 15:09:00 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-02-04 15:09:00 +0300 |
commit | 88a0824944720b6edaaef56376713541b9a02118 (patch) | |
tree | f5fcc4f9755f249779cda9a8f02902d734af6e7e /doc/user/packages/maven_repository | |
parent | 7d19df2d34a9803d9f077c16315ba919b7ae2aa2 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user/packages/maven_repository')
-rw-r--r-- | doc/user/packages/maven_repository/index.md | 157 |
1 files changed, 147 insertions, 10 deletions
diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index f65042d2684..27c6a580797 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -25,11 +25,78 @@ You should then be able to see the **Packages** section on the left sidebar. Next, you must configure your project to authorize with the GitLab Maven repository. -## Authenticating to the GitLab Maven Repository +## Getting Started -If a project is private or you want to upload Maven artifacts to GitLab, -credentials will need to be provided for authorization. Support is available for -[personal access tokens](#authenticating-with-a-personal-access-token) and +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). + +### Installing Maven + +Follow the instructions at [maven.apache.org](https://maven.apache.org/install.html) +to download and install Maven for your local development environment. Once +installation is complete, verify you can use Maven in your terminal by running: + +```shell +mvn --version +``` + +You should see something similar to the below printed in the output: + +```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" +``` + +### Creating a project + +Understanding how to create a full Java project 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 initalize a new package: + +```shell +mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false +``` + +The arguments are as follows: + +- `DgroupId`: A unique string that identifies your package. You should 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 intial structure of +the project. +- `DinteractiveMode`: Create the project using batch mode (optional). + +After running the command, you should see the following message, indicating that +your project has been set up successfully: + +```shell +... +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 3.429 s +[INFO] Finished at: 2020-01-28T11:47:04Z +[INFO] ------------------------------------------------------------------------ +``` + +You should see a new directory where you ran this command matching your +`DartifactId` parameter (in this case it should be `my-project`). + +## 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 credentials do not work. @@ -92,7 +159,9 @@ You can read more on ## Configuring your project to use the GitLab Maven repository URL To download and upload packages from GitLab, you need a `repository` and -`distributionManagement` section in your `pom.xml` file. +`distributionManagement` section in your `pom.xml` file. If you're following the +steps from above, then you'll need to add the following information to your +`my-project/pom.xml` file. Depending on your workflow and the amount of Maven packages you have, there are 3 ways you can configure your project to use the GitLab endpoint for Maven packages: @@ -133,7 +202,7 @@ would look like: ``` The `id` must be the same with what you -[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). +[defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote). Replace `PROJECT_ID` with your project ID which can be found on the home page of your project. @@ -186,7 +255,7 @@ the `distributionManagement` section: ``` The `id` must be the same with what you -[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). +[defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote). Replace `my-group` with your group name and `PROJECT_ID` with your project ID which can be found on the home page of your project. @@ -241,7 +310,7 @@ the `distributionManagement` section: ``` The `id` must be the same with what you -[defined in `settings.xml`](#authenticating-to-the-gitlab-maven-repository). +[defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote). Replace `PROJECT_ID` with your project ID which can be found on the home page of your project. @@ -257,17 +326,85 @@ project's ID can be used for uploading. ## Uploading packages -Once you have set up the [authentication](#authenticating-to-the-gitlab-maven-repository) -and [configuration](#configuring-your-project-to-use-the-gitlab-maven-repository-url), +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: ```shell mvn deploy ``` +If the deploy is successful, you should see the build success message again: + +```shell +... +[INFO] BUILD SUCCESS +... +``` + +You should also see that the upload was uploaded to the correct registry: + +```shell +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 artifacts or even delete them. +## Installing a package + +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` + +Add the dependency manually to your project `pom.xml` file. To add the example +created above, the XML would look like: + +```xml +<dependency> + <groupId>com.mycompany.mydepartment</groupId> + <artifactId>my-project</artifactId> + <version>1.0-SNAPSHOT</version> +</dependency> +``` + +Then, inside your project, run the following: + +```shell +mvn install +``` + +Provided everything is set up correctly, you should see the dependency +downloaded from the GitLab Package Registry: + +```shell +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` + +The second way to install packages is to use the Maven commands directly. +Inside your project directory, run: + +```shell +mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT +``` + +You should see the same downloading message confirming that the project was +retrieved from the GitLab Package Registry. + +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. + +## Removing a package + +In the packages view of your project page, you can delete packages by clicking +the red trash icons or by clicking the **Delete** button on the package details +page. + ## Creating Maven packages with GitLab CI/CD Once you have your repository configured to use the GitLab Maven Repository, |