Skip to content

G
gitlab-ce
Commit d5aad336 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Copyedit the maven packages repo docs

parent e02e7855
Hide whitespace changes
Inline Side-by-side
Showing with 138 additions and 94 deletions
doc/administration/maven_packages.md
View file @ d5aad336
# GitLab private Maven repository administration
> **Notes:**
> - [Introduced][ee-5811] in GitLab 11.3.
> - This document is about the admin guide. Learn how to use GitLab Maven
> repository from [user documentation](../user/project/maven_packages.md).
- [Introduced][ee-5811] in GitLab 11.3.
- This document is about the admin guide. Learn how to use GitLab Maven
repository from [user documentation](../user/project/maven_packages.md).
When enabled, every project in GitLab will have its own space to store Maven packages.
When enabled, every project in GitLab will have its own space to store
[Maven](https://maven.apache.org/) packages.
## Enable the Maven repository
## Enabling the Maven repository
NOTE: **Note:**
Once enabled, newly created projects will have the Packages feature enabled by
default. Existing projects will need to
[explicitly enabled it](../user/project/maven_packages.md#enabling-the-packages-repository).
**Omnibus GitLab installations**
......@@ -23,21 +29,15 @@ When enabled, every project in GitLab will have its own space to store Maven pac
If you have installed GitLab from source:
1. After the installation is complete, you will have to configure the `packages`
section in `gitlab.yml` in order to enable it.
The contents of `gitlab.yml` are:
```
packages:
enabled: true
```
where:
1. After the installation is complete, you will have to configure the `packages`
section in `config/gitlab.yml`. Set to `true` to enable it:
| Parameter | Description |
| --------- | ----------- |
| `enabled` | `true` or `false`. Enables the packages repository in GitLab. By default this is `false`. |
```yaml
packages:
enabled: true
```
1. [Restart GitLab] for the changes to take effect.
[reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
[restart gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
[ee-5811]: https://gitlab.com/gitlab-org/gitlab-ee/issues/5811
doc/user/project/maven_packages.md
View file @ d5aad336
# GitLab Maven Packages repository
# GitLab Maven Packages repository **[PREMIUM]**
## Configure project to use GitLab Maven Repository URL
> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
To download packages from GitLab, you need `repository` section in your `pom.xml`.
With the GitLab [Maven](https://maven.apache.org) Packages repository, every
project can have its own space to store its Maven artifacts.
## Enabling the Packages repository
NOTE: **Note:**
This option is available only if your GitLab administrator has
[enabled the Packages repository](../../administration/maven_packages.md).
In order to use the GitLab Maven Packages repository, you must enable the
general Packages repository. To enable (or disable) it:
1. Navigate to your project's **Settings > General > Permissions**.
1. Find the "Packages" feature and enable 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.
Next, you must configure your project to authorize with the Maven repository.
## Authorizing with the Maven repository
If a project is private or you want to upload Maven artifacts to GitLab,
credentials will need to be provided for authorization:
1. Create a new [personal access token](../profile/personal_access_tokens.md)
with the `api` scope.
1. 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>Private-Token</name>
<value>REPLACE_WITH_YOUR_PERSONAL_ACCESS_TOKEN</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
```
You should now be able to upload Maven artifacts to your project.
## Configuring your project to use the GitLab Maven repository URL
To download packages from GitLab, you need a `repository` section in your
`pom.xml` file:
```xml
<repositories>
......@@ -13,10 +65,15 @@ To download packages from GitLab, you need `repository` section in your `pom.xml
</repositories>
```
To upload packages to GitLab, you need a `distributionManagement` section in your `pom.xml`.
Similarly, to upload packages to GitLab, you need a `distributionManagement`
section in your `pom.xml` file:
```xml
<distributionManagement>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
<snapshotRepository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
......@@ -24,74 +81,61 @@ To upload packages to GitLab, you need a `distributionManagement` section in you
</distributionManagement>
```
In both examples, replace `PROJECT_ID` with your project ID.
If you have a private GitLab installation, replace `gitlab.com` with your domain name.
## Configure repository access
If a project is private, credentials will need to be provided for authorization.
The preferred way to do this, is by using a [personal access tokens][pat].
You can add a corresponding section to your `settings.xml` file:
```xml
<settings>
<servers>
<server>
<id>gitlab-maven</id>
<configuration>
<httpHeaders>
<property>
<name>Private-Token</name>
<value>REPLACE_WITH_YOUR_PRIVATE_TOKEN</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
```
## Create maven packages with GitLab CI
Once you have your repository configured to use GitLab Maven Packages repository,
you can configure GitLab CI to build new packages automatically. The example below
shows you how to create a new package each time the master branch is updated.
1\. Create a `ci_settings.xml` file specially for GitLab CI and put it into your repository.
Add server section there with same id as you used for GitLab repository in your `pom.xml` file.
For example, in our case its `gitlab-maven`.
```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>CI_JOB_TOKEN</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
```
2\. Add `deploy` section to your `.gitlab-ci.yml` file.
```
deploy:
script:
- 'cp ci_settings.xml /root/.m2/settings.xml'
- 'sed -i "s/CI_JOB_TOKEN/${CI_JOB_TOKEN}/g" /root/.m2/settings.xml'
- 'mvn deploy'
only:
- master
image: maven:3.3.9-jdk-8
```
[pat]: ../profile/personal_access_tokens.md
The `id` must be the same with what you
[defined in `settings.xml`](#authorizing-with-the-maven-repository).
In both examples, replace `PROJECT_ID` with your project ID which can be found
on the home page of your project.
If you have a private GitLab installation, replace `gitlab.com` with your
domain name.
## Creating maven packages with GitLab CI/CD
Once you have your repository configured to use the GitLab Maven Packages 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:
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.
For example, in our case it's `gitlab-maven`:
```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>CI_JOB_TOKEN</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
```
1. Add a `deploy` job to your `.gitlab-ci.yml` file:
```yaml
deploy:
image: maven:3.3.9-jdk-8
script:
- 'cp ci_settings.xml /root/.m2/settings.xml'
- 'sed -i "s/CI_JOB_TOKEN/${CI_JOB_TOKEN}/g" /root/.m2/settings.xml'
- 'mvn deploy'
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 `sed` will replace the placeholder `CI_JOB_TOKEN`
value with the contents of the actual [`CI_JOB_TOKEN`
environment variable](../../ci/variables/README.md#predefined-variables-environment-variables).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7