Skip to content

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

Merge branch 'doc-maven-package-ci' into 'master' 

Refactor maven package repository docs

Closes #7517

See merge request gitlab-org/gitlab-ee!7269
parents 036683d5 163ab9f4
Hide whitespace changes
Inline Side-by-side
Showing with 306 additions and 77 deletions
doc/administration/maven_packages.md
View file @ 08a8e3b3
# GitLab private Maven repository administration
# GitLab 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](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811)
in GitLab 11.3. To learn how to use
When enabled, every project in GitLab will have its own space to store Maven packages.
When the GitLab Maven repository is enabled, every project in GitLab will have
its own space to store [Maven](https://maven.apache.org/) packages.
## Enable the Maven repository
To learn how to use it, see the [user documentation](../user/project/packages/maven.md).
## Enabling the Packages 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/packages/maven.md#enabling-the-packages-repository).
To enable the Packages repository:
**Omnibus GitLab installations**
......@@ -21,23 +30,121 @@ When enabled, every project in GitLab will have its own space to store Maven pac
**Installations from source**
If you have installed GitLab from source:
1. After the installation is complete, you will have to configure the `packages`
section in `config/gitlab.yml`. Set to `true` to enable it:
```yaml
packages:
enabled: true
```
1. [Restart GitLab] for the changes to take effect.
## Changing the storage path
1. After the installation is complete, you will have to configure the `packages`
section in `gitlab.yml` in order to enable it.
By default, the packages are stored locally, but you can change the default
local location or even use object storage.
### Changing the local storage path
The packages for Omnibus GitLab installations are stored under
`/var/opt/gitlab/gitlab-rails/shared/packages/` and for source
installations under `shared/packages/` (relative to the git homedir).
To change the local storage path:
**Omnibus GitLab installations**
The contents of `gitlab.yml` are:
1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
```ruby
gitlab_rails['packages_storage_path'] = "/mnt/maven"
```
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
**Installations from source**
```
packages:
enabled: true
```
1. Edit the `packages` section in `config/gitlab.yml`:
where:
```yaml
packages:
enabled: true
storage_path: shared/packages
```
1. [Restart GitLab] for the changes to take effect.
### Using object storage
Instead of relying on the local storage, you can use an object storage to
upload the maven packages:
**Omnibus GitLab installations**
1. Edit `/etc/gitlab/gitlab.rb` and add the following lines (uncomment where
necessary):
```ruby
gitlab_rails['packages_enabled'] = true
gitlab_rails['packages_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/packages"
gitlab_rails['packages_object_store_enabled'] = true
gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
gitlab_rails['packages_object_store_direct_upload'] = false # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
gitlab_rails['packages_object_store_background_upload'] = true # Temporary option to limit automatic upload (Default: true).
gitlab_rails['packages_object_store_proxy_download'] = false # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
gitlab_rails['packages_object_store_connection'] = {
##
## If the provider is AWS S3, uncomment the following
##
#'provider' => 'AWS',
#'region' => 'eu-west-1',
#'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
#'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
##
## If the provider is other than AWS (an S3-compatible one), uncomment the following
##
#'host' => 's3.amazonaws.com',
#'aws_signature_version' => 4 # For creation of signed URLs. Set to 2 if provider does not support v4.
#'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
#'path_style' => false # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
}
```
1. Save the file and [reconfigure GitLab][] for the changes to take effect.
**Installations from source**
1. Edit the `packages` section in `config/gitlab.yml` (uncomment where necessary):
```yaml
packages:
enabled: true
##
## The location where build packages are stored (default: shared/packages).
##
#storage_path: shared/packages
object_store:
enabled: false
remote_directory: packages # The bucket name.
#direct_upload: false # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
#background_upload: true # Temporary option to limit automatic upload (Default: true).
#proxy_download: false # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
connection:
##
## If the provider is AWS S3, uncomment the following
##
#provider: AWS
#region: us-east-1
#aws_access_key_id: AWS_ACCESS_KEY_ID
#aws_secret_access_key: AWS_SECRET_ACCESS_KEY
##
## If the provider is other than AWS (an S3-compatible one), uncomment the following
##
#host: 's3.amazonaws.com' # default: s3.amazonaws.com.
#aws_signature_version: 4 # For creation of signed URLs. Set to 2 if provider does not support v4.
#endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
#path_style: false # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
```
| Parameter | Description |
| --------- | ----------- |
| `enabled` | `true` or `false`. Enables the packages repository in GitLab. By default this is `false`. |
1. [Restart GitLab] for the changes to take effect.
[reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
[ee-5811]: https://gitlab.com/gitlab-org/gitlab-ee/issues/5811
[restart gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab"
doc/user/project/index.md
View file @ 08a8e3b3
......@@ -86,7 +86,7 @@ website with GitLab Pages
- [Syntax highlighting](highlighting.md): An alternative to customize
your code blocks, overriding GitLab's default choice of language
- [Badges](badges.md): Badges for the project overview
- [Maven packages](maven_packages.md): Your private Maven repository in GitLab
- [Maven packages](packages/maven.md): Your private Maven repository in GitLab **[PREMIUM]**
- [Code owners](code_owners.md): Specify code owners for certain files **[STARTER]**
### Project's integrations
......
doc/user/project/maven_packages.md deleted 100644 → 0
View file @ 036683d5
# GitLab Maven Packages repository
## Configure project to use GitLab Maven Repository URL
To download packages from GitLab, you need `repository` section in your `pom.xml`.
```xml
<repositories>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
</repositories>
```
To upload packages to GitLab, you need a `distributionManagement` section in your `pom.xml`.
```xml
<distributionManagement>
<snapshotRepository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</snapshotRepository>
</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>
```
[pat]: ../profile/personal_access_tokens.md
doc/user/project/packages/maven.md 0 → 100644
View file @ 08a8e3b3
# GitLab Maven Packages repository **[PREMIUM]**
> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
With the GitLab [Maven](https://maven.apache.org) Packages repository, every
project can have its own space to store its Maven artifacts.
![GitLab Maven repository](img/maven_package_view.png)
## 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
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 GitLab Maven
repository.
## Authorizing with the GitLab 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 and upload packages from GitLab, you need a `repository` and
`distributionManagement` section respectively in your `pom.xml` file:
```xml
<repositories>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
</repositories>
<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>
</snapshotRepository>
</distributionManagement>
```
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 self-hosted GitLab installation, replace `gitlab.com` with your
domain name.
## Uploading packages
Once you have set up the [authorization](#authorizing-with-the-gitlab-maven-repository)
and [configuration](#configuring-your-project-to-use-the-gitlab-maven-repository-url),
test to upload a Maven artifact from a project of yours:
```sh
mvn deploy
```
You can then navigate to your project's **Packages** page and see the uploaded
artifacts or even delete them.
## 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. Make sure your `pom.xml` file includes the following:
```xml
<repositories>
<repository>
<id>gitlab-maven</id>
<url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
</repository>
</repositories>
<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>
</snapshotRepository>
</distributionManagement>
```
TIP: **Tip:**
You can either leave GitLab CI/CD to replace your project ID value while
the deploy job is running or hardcode your project's ID.
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'
- 'sed -i "s/PROJECT_ID/${CI_PROJECT_ID}/g" pom.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 values with the
contents of the actual
[environment variables](../../../ci/variables/README.md#predefined-variables-environment-variables).
ee/app/helpers/ee/projects_helper.rb
View file @ 08a8e3b3
......@@ -39,7 +39,7 @@ module EE
def project_permissions_panel_data(project)
super.merge(
packagesAvailable: ::Gitlab.config.packages.enabled,
packagesHelpPath: help_page_path('user/project/maven_packages')
packagesHelpPath: help_page_path('user/project/packages/maven')
)
end
......
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