diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-12-16 00:07:28 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-12-16 00:07:28 +0300 |
commit | d22c6f7410966b5288a8b8e904cd24758e9cec50 (patch) | |
tree | b54768ea1b03a1affb798898e2cf81fd1259e80b /doc | |
parent | a84aefe0bb8fc2ad47ab67cb4ddcfbb7aecfbd5e (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/container_registry.md | 39 | ||||
-rw-r--r-- | doc/architecture/blueprints/ci_pipeline_components/index.md | 2 | ||||
-rw-r--r-- | doc/development/migration_style_guide.md | 12 | ||||
-rw-r--r-- | doc/user/asciidoc.md | 5 | ||||
-rw-r--r-- | doc/user/infrastructure/iac/terraform_template_recipes.md | 2 | ||||
-rw-r--r-- | doc/user/markdown.md | 29 | ||||
-rw-r--r-- | doc/user/packages/gradle_repository/index.md | 372 | ||||
-rw-r--r-- | doc/user/packages/maven_repository/index.md | 694 | ||||
-rw-r--r-- | doc/user/packages/package_registry/index.md | 3 | ||||
-rw-r--r-- | doc/user/packages/workflows/project_registry.md | 4 | ||||
-rw-r--r-- | doc/user/project/merge_requests/commits.md | 59 |
11 files changed, 570 insertions, 651 deletions
diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index 5b11c324802..a2e4d9f37f5 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -419,18 +419,51 @@ To query those, follow the Registry's built-in mechanism to obtain and use an NOTE: These are different from project or personal access tokens in the GitLab application. +### Obtain token from GitLab + +```plaintext +GET ${CI_SERVER_URL}/jwt/auth?service=container_registry&scope=* +``` + +You must specify the correct [scopes and actions](https://docs.docker.com/registry/spec/auth/scope/) to retrieve a valid token: + +```shell +$ SCOPE="repository:${CI_REGISTRY_IMAGE}:delete" #or push,pull + +$ curl --request GET --user "${CI_REGISTRY_USER}:${CI_REGISTRY_PASSWORD}" \ + "https://gitlab.example.com/jwt/auth?service=container_registry&scope=${SCOPE}" +{"token":" ... "} +``` + +### Delete image tags by reference + +```plaintext +DELETE http(s)://${CI_REGISTRY}/v2/${CI_REGISTRY_IMAGE}/tags/reference/${CI_COMMIT_SHORT_SHA} +``` + +You can use the token retrieved with the predefined `CI_REGISTRY_USER` and `CI_REGISTRY_PASSWORD` variables to delete container image tags by reference on your GitLab instance. +The `tag_delete` [Container-Registry-Feature](https://gitlab.com/gitlab-org/container-registry/-/tree/v3.61.0-gitlab/docs-gitlab#api) must be enabled. + +```shell +$ curl --request DELETE --header "Authorization: Bearer <token_from_above>" \ + --header "Accept: application/vnd.docker.distribution.manifest.v2+json" \ + "https://gitlab.example.com:5050/v2/${CI_REGISTRY_IMAGE}/tags/reference/${CI_COMMIT_SHORT_SHA}" +``` + ### Listing all container repositories ```plaintext -GET /v2/_catalog +GET http(s)://${CI_REGISTRY}/v2/_catalog ``` To list all container repositories on your GitLab instance, administrator credentials are required: ```shell -$ curl --request GET --user "<admin-username>:<admin-password>" "https://gitlab.example.com/jwt/auth?service=container_registry&scope=registry:catalog:*" +$ SCOPE="registry:catalog:*" + +$ curl --request GET --user "<admin-username>:<admin-password>" \ + "https://gitlab.example.com/jwt/auth?service=container_registry&scope=${SCOPE}" {"token":" ... "} $ curl --header "Authorization: Bearer <token_from_above>" https://gitlab.example.com:5050/v2/_catalog -{"repositories":["user/project1", "group/subgroup/project2", ... ]} ``` diff --git a/doc/architecture/blueprints/ci_pipeline_components/index.md b/doc/architecture/blueprints/ci_pipeline_components/index.md index 87a0e7c0b66..100c9e67fda 100644 --- a/doc/architecture/blueprints/ci_pipeline_components/index.md +++ b/doc/architecture/blueprints/ci_pipeline_components/index.md @@ -509,6 +509,6 @@ Domain experts: | Area | Who |------------------------------|------------------------| | Verify / Pipeline authoring | Avielle Wolfe | -| Verify / Pipeline authoring | Furkan Ayhan | +| Verify / Pipeline authoring | Laura Montemayor-Rodriguez | <!-- vale gitlab.Spelling = YES --> diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 443ec780ffb..e857ae5b112 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -376,7 +376,7 @@ Occasionally a migration may need to acquire multiple locks on different objects To prevent catalog bloat, ask for all those locks explicitly before performing any DDL. A better strategy is to split the migration, so that we only need to acquire one lock at the time. -**Removing a column:** +#### Removing a column ```ruby enable_lock_retries! @@ -386,7 +386,7 @@ def change end ``` -**Multiple changes on the same table:** +#### Multiple changes on the same table With the lock-retry methodology enabled, all operations wrap into a single transaction. When you have the lock, you should do as much as possible inside the transaction rather than trying to get another lock later. @@ -406,7 +406,7 @@ def down end ``` -**Removing a foreign key:** +#### Removing a foreign key ```ruby enable_lock_retries! @@ -420,7 +420,7 @@ def down end ``` -**Changing default value for a column:** +#### Changing default value for a column ```ruby enable_lock_retries! @@ -434,7 +434,7 @@ def down end ``` -**Creating a new table with a foreign key:** +#### Creating a new table with a foreign key We can wrap the `create_table` method with `with_lock_retries`: @@ -453,7 +453,7 @@ def down end ``` -**Creating a new table when we have two foreign keys:** +#### Creating a new table when we have two foreign keys Only one foreign key should be created per transaction. This is because [the addition of a foreign key constraint requires a `SHARE ROW EXCLUSIVE` lock on the referenced table](https://www.postgresql.org/docs/12/sql-createtable.html#:~:text=The%20addition%20of%20a%20foreign%20key%20constraint%20requires%20a%20SHARE%20ROW%20EXCLUSIVE%20lock%20on%20the%20referenced%20table), and locking multiple tables in the same transaction should be avoided. diff --git a/doc/user/asciidoc.md b/doc/user/asciidoc.md index 3ceecf88c5e..6b642363dd6 100644 --- a/doc/user/asciidoc.md +++ b/doc/user/asciidoc.md @@ -9,6 +9,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab uses the [Asciidoctor](https://asciidoctor.org) gem to convert AsciiDoc content to HTML5. Consult the [Asciidoctor User Manual](https://asciidoctor.org/docs/user-manual/) for a complete Asciidoctor reference. +You can use AsciiDoc in the following areas: + +- Wiki pages +- AsciiDoc documents (`.adoc` or `.asciidoc`) inside repositories + ## Syntax Here's a brief reference of the most commonly used AsciiDoc syntax. diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md index fc03833ce8d..ab2c8c1c48a 100644 --- a/doc/user/infrastructure/iac/terraform_template_recipes.md +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -165,7 +165,7 @@ prepare:image: DOCKER_TAG: latest before_script: # Authenticate to the docker registry and dependency proxy - - echo "{\"auths\":{\"$CI_REGISTRY\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"},\"$CI_DEPENDENCY_PROXY_SERVER\"}}" > /kaniko/.docker/config.json + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"}}}" > /kaniko/.docker/config.json script: - /kaniko/executor --context "${CI_PROJECT_DIR}/.gitlab/ci" diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 334c603c9e0..17b91eb9483 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1547,6 +1547,7 @@ Tables are not part of the core Markdown specification, but are part of GitLab F by pipes (`|`). - You **can** have blank cells. 1. Column widths are calculated dynamically based on the content of the cells. +1. To use the pipe character (`|`) in the text and not as table delimiter, you must escape it with a backslash (`\|`). Example: @@ -1598,7 +1599,8 @@ use `<br>` tags to force a cell to have multiple lines: | Item2 | This item has:<br>- Multiple items<br>- That we want listed separately | You can use HTML formatting in GitLab itself to add [task lists](#task-lists) with checkboxes, -but they do not render properly on `docs.gitlab.com`: +but they do not render properly on `docs.gitlab.com`. Note that these tasks will not save their +state when selected, like regular GitLab task lists. ```markdown | header 1 | header 2 | @@ -1607,6 +1609,31 @@ but they do not render properly on `docs.gitlab.com`: | cell 3 | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> | ``` +To have fully functioning task lists in a table, create an HTML table with Markdown in the cells: + +```html +<table> +<thead> +<tr><th>header 1</th><th>header 2</th></tr> +</thead> +<tbody> +<tr> +<td>cell 1</td> +<td>cell 2</td> +</tr> +<tr> +<td>cell 3</td> +<td> + +- [ ] Task one +- [ ] Task two + +</td> +</tr> +</tbody> +</table> +``` + ##### Copy and paste from a spreadsheet > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27205) in GitLab 12.7. diff --git a/doc/user/packages/gradle_repository/index.md b/doc/user/packages/gradle_repository/index.md new file mode 100644 index 00000000000..4247c13297d --- /dev/null +++ b/doc/user/packages/gradle_repository/index.md @@ -0,0 +1,372 @@ +--- +stage: Package +group: Package Registry +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Maven packages in the Package Registry **(FREE)** + +Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry using Gradle. +Then, install the packages whenever you need to use them as a dependency. + +For documentation of the specific API endpoints that the Maven package manager +client uses, see the [Maven API documentation](../../../api/packages/maven.md). + +Learn how to build a [Gradle](../workflows/build_packages.md#gradle) package. + +## Publish to the GitLab Package Registry + +### Tokens + +You need a token to publish a package. Different tokens are available depending on what you're trying to +achieve. For more information, review the [guidance on tokens](../package_registry/index.md#authenticate-with-the-registry). + +- If your organization uses two-factor authentication (2FA), you must use a personal access token with the scope set to `api`. +- If you publish a package via CI/CD pipelines, you must use a CI job token. + +Create a token and save it to use later in the process. + +## Authenticate to the Package Registry with Gradle + +### Authenticate with a personal access token or deploy token in Gradle + +In [your `GRADLE_USER_HOME` directory](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home), +create a file `gradle.properties` with the following content: + +```properties +gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN +``` + +Your token name depends on which token you use. + +| Token type | Token name | +| --------------------- | --------------- | +| Personal access token | `Private-Token` | +| Deploy token | `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.example.com/api/v4/groups/<group>/-/packages/maven" + name "GitLab" + credentials(HttpHeaderCredentials) { + name = 'REPLACE_WITH_TOKEN_NAME' + value = gitLabPrivateToken + } + authentication { + header(HttpHeaderAuthentication) + } + } +} +``` + +Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") + name = "GitLab" + credentials(HttpHeaderCredentials::class) { + name = "REPLACE_WITH_TOKEN_NAME" + value = findProperty("gitLabPrivateToken") as String? + } + authentication { + create("header", HttpHeaderAuthentication::class) + } + } +} +``` + +### Authenticate 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 "${CI_API_V4_URL}/groups/<group>/-/packages/maven" + name "GitLab" + credentials(HttpHeaderCredentials) { + name = 'Job-Token' + value = System.getenv("CI_JOB_TOKEN") + } + authentication { + header(HttpHeaderAuthentication) + } + } +} +``` + +Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("$CI_API_V4_URL/groups/<group>/-/packages/maven") + name = "GitLab" + credentials(HttpHeaderCredentials::class) { + name = "Job-Token" + value = System.getenv("CI_JOB_TOKEN") + } + authentication { + create("header", HttpHeaderAuthentication::class) + } + } +} +``` + +### Naming convention + +You can use one of three API endpoints to install a Maven package. You must publish a package to a project, but note which endpoint +you use to install the package. The option you choose determines the settings you add to your `pom.xml` file for publishing. + +The three endpoints are: + +- **Project-level**: Use when you have a few Maven packages that are not in the same GitLab group. +- **Group-level**: Use when installing packages from many different projects in the same GitLab group. GitLab does not guarantee the uniqueness of package names in the group. You can have two projects with the same package name and package version. As a result, GitLab serves whichever one is more recent. +- **Instance-level**: Use when installing many packages from different GitLab groups or in their own namespace. + +**Only packages with the same path as the project** are exposed by the instance-level endpoint. + +| Project | Package | Instance-level endpoint available | +| ------------------- | -------------------------------- | --------------------------------- | +| `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | +| `gitlab-org/gitlab` | `foo/bar/1.0-SNAPSHOT` | No | +| `gitlab-org/gitlab` | `gitlab-org/gitlab/1.0-SNAPSHOT` | Yes | + +#### Endpoint URLs + +| Endpoint | Endpoint URL | Additional information | +| -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | +| Project | `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<project_id>` with your project ID found on your project's homepage. | +| Group | `https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<group_id>` with your group ID found on your group's homepage. | +| Instance | `https:///gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | + +In all cases, to publish a package, you need: + +- A project-specific URL in the `distributionManagement` section. +- A `repository` and `distributionManagement` section. + +### Edit the Groovy DSL or Kotlin DSL + +The Gradle Groovy DSL `repositories` section should look like this: + +```groovy +repositories { + maven { + url "<your_endpoint_url>" + name "GitLab" + } +} +``` + +In Kotlin DSL: + +```kotlin +repositories { + maven { + url = uri("<your_endpoint_url>") + name = "GitLab" + } +} +``` + +- Replace `<your_endpoint_url>` with the [endpoint](#endpoint-urls) you chose. + +## Publish using Gradle + +Your token name depends on which token you use. + +| Token type | Token name | +| --------------------- | --------------- | +| Personal access token | `Private-Token` | +| Deploy token | `Deploy-Token` | + +To publish a package by using Gradle: + +1. Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: + + In Groovy DSL: + + ```groovy + plugins { + id 'java' + id 'maven-publish' + } + ``` + + In Kotlin DSL: + + ```kotlin + plugins { + java + `maven-publish` + } + ``` + +1. Add a `publishing` section: + + In Groovy DSL: + + ```groovy + publishing { + publications { + library(MavenPublication) { + from components.java + } + } + repositories { + maven { + url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven" + credentials(HttpHeaderCredentials) { + name = "REPLACE_WITH_TOKEN_NAME" + value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties + } + authentication { + header(HttpHeaderAuthentication) + } + } + } + } + ``` + + In Kotlin DSL: + + ```kotlin + publishing { + publications { + create<MavenPublication>("library") { + from(components["java"]) + } + } + repositories { + maven { + url = uri("https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven") + credentials(HttpHeaderCredentials::class) { + name = "REPLACE_WITH_TOKEN_NAME" + value = + findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties + } + authentication { + create("header", HttpHeaderAuthentication::class) + } + } + } + } + ``` + +1. Replace `PROJECT_ID` with your project ID, which you can find on your project's home page. + +1. Run the publish task: + + ```shell + gradle publish + ``` + +Go to your project's **Packages and registries** page and view the published packages. + +## Install a package + +To install a package from the GitLab Package Registry, you must configure +the [remote and authenticate](#authenticate-to-the-package-registry-with-gradle). +After configuring the remote and authenticate, you can install a package from a project, group, or namespace. + +If multiple packages have the same name and version, when you install +a package, the most recently-published package is retrieved. + +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' +} +``` + +Or to `build.gradle.kts` if you are using Kotlin DSL: + +```kotlin +dependencies { + implementation("com.mycompany.mydepartment:my-project:1.0-SNAPSHOT") +} +``` + +## Helpful hints + +For the complete list of helpful hints, see the [Maven documentation](../maven_repository/index.md#helpful-hints). + +### Create Maven packages with GitLab CI/CD by using Gradle + +You can create a package each time the `main` branch +is updated. + +1. Authenticate with [a CI job token in Gradle](#authenticate-with-a-ci-job-token-in-gradle). + +1. Add a `deploy` job to your `.gitlab-ci.yml` file: + + ```yaml + deploy: + image: gradle:6.5-jdk11 + script: + - 'gradle publish' + only: + - main + ``` + +1. Commit files to your repository. + +When the pipeline is successful, the Maven package is created. + +### Publishing a package with the same name or version + +When you publish a package with the same name and version as an existing package, the new package +files are added to the existing package. You can still use the UI or API to access and view the +existing package's older assets. + +Consider using the Packages API or the UI to delete older package versions. + +### Do not allow duplicate Maven packages + +To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. + +In the UI: + +1. For your group, go to **Settings > Packages and registries**. +1. Expand the **Package Registry** section. +1. Turn on the **Do not allow duplicates** toggle. +1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names and/or versions of packages you want to allow. + +Your changes are automatically saved. + +### Request forwarding to Maven Central + +FLAG: +By default, this feature is not available for self-managed. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. +This feature is not available for SaaS users. + +When a Maven package is not found in the Package Registry, the request is forwarded +to [Maven Central](https://search.maven.org/). + +When the feature flag is enabled, administrators can disable this behavior in the +[Continuous Integration settings](../../admin_area/settings/continuous_integration.md). + +There are many ways to configure your Maven project to request packages +in Maven Central from GitLab. Maven repositories are queried in a +[specific order](https://maven.apache.org/guides/mini/guide-multiple-repositories.html#repository-order). +By default, maven-central is usually checked first through the +[Super POM](https://maven.apache.org/guides/introduction/introduction-to-the-pom.html#Super_POM), so +GitLab needs to be configured to be queried before maven-central. + +[Using GitLab as a mirror of the central proxy](../maven_repository/index.md#setting-gitlab-as-a-mirror-for-the-central-proxy) is one +way to force GitLab to be queried in place of maven-central. + +Maven forwarding is restricted to only the project level and +group level [endpoints](#naming-convention). The instance-level endpoint +has naming restrictions that prevent it from being used for packages that don't follow that convention and also +introduces too much security risk for supply-chain style attacks. diff --git a/doc/user/packages/maven_repository/index.md b/doc/user/packages/maven_repository/index.md index 2aa71e111fb..c6c2f238564 100644 --- a/doc/user/packages/maven_repository/index.md +++ b/doc/user/packages/maven_repository/index.md @@ -4,9 +4,7 @@ group: Package Registry info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Maven packages in the Package Repository **(FREE)** - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +# Maven packages in the Package Registry **(FREE)** Publish [Maven](https://maven.apache.org) artifacts in your project's Package Registry. Then, install the packages whenever you need to use them as a dependency. @@ -14,75 +12,29 @@ Then, install the packages whenever you need to use them as a dependency. For documentation of the specific API endpoints that the Maven package manager client uses, see the [Maven API documentation](../../../api/packages/maven.md). -Learn how to build a [Maven](../workflows/build_packages.md#maven) or [Gradle](../workflows/build_packages.md#gradle) package. - -## Authenticate to the Package Registry with Maven - -To authenticate to the Package Registry, you need one of the following: +Learn how to build a [Maven](../workflows/build_packages.md#maven) package. -- A [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`. -- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both. -- A [CI_JOB_TOKEN](#authenticate-with-a-ci-job-token-in-maven). +## Publish to the GitLab Package Registry -### Authenticate with a personal access token in Maven - -To use a personal access token, add this section to your -[`settings.xml`](https://maven.apache.org/settings.html) file. +### Authenticate to the Package Registry -The `name` must be `Private-Token`. - -```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 need an token to publish a package. There are different tokens available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../package_registry/index.md#authenticate-with-the-registry). -### Authenticate with a deploy token in Maven +Create a token and save it to use later in the process. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) deploy token authentication in GitLab 13.0. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. +### Edit the `settings.xml` -To use a deploy token, add this section to your +Add the following section to your [`settings.xml`](https://maven.apache.org/settings.html) file. -The `name` must be `Deploy-Token`. - -```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> -``` - -### Authenticate with a CI job token in Maven - -To authenticate with a CI job token, add this section to your -[`settings.xml`](https://maven.apache.org/settings.html) file. +NOTE: +The `<name>` field must be named to match the token you chose. -The `name` must be `Job-Token`. +| Token type | Name must be | Token | +| --------------------- | --------------- | ---------------------------------------------------------------------- | +| Personal access token | `Private-Token` | Paste token as-is, or define an environment variable to hold the token | +| Deploy token | `Deploy-Token` | Paste token as-is, or define an environment variable to hold the token | +| CI Job token | `Job-Token` | `${CI_JOB_TOKEN}` | ```xml <settings> @@ -92,8 +44,8 @@ The `name` must be `Job-Token`. <configuration> <httpHeaders> <property> - <name>Job-Token</name> - <value>${CI_JOB_TOKEN}</value> + <name>REPLACE_WITH_NAME</name> + <value>REPLACE_WITH_TOKEN</value> </property> </httpHeaders> </configuration> @@ -102,361 +54,70 @@ The `name` must be `Job-Token`. </settings> ``` -Read more about [how to create Maven packages using GitLab CI/CD](#create-maven-packages-with-gitlab-cicd). - -## Authenticate to the Package Registry with Gradle - -To authenticate to the Package Registry, you need either a personal access token or deploy token. - -- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`. -- If you use a [deploy token](../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both. - -### Authenticate with a personal access token in Gradle - -In [your `GRADLE_USER_HOME` directory](https://docs.gradle.org/current/userguide/directory_layout.html#dir:gradle_user_home), -create a file `gradle.properties` with the following content: - -```properties -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.example.com/api/v4/groups/<group>/-/packages/maven" - name "GitLab" - credentials(HttpHeaderCredentials) { - name = 'Private-Token' - value = gitLabPrivateToken - } - authentication { - header(HttpHeaderAuthentication) - } - } -} -``` - -Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: - -```kotlin -repositories { - maven { - url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") - name = "GitLab" - credentials(HttpHeaderCredentials::class) { - name = "Private-Token" - value = findProperty("gitLabPrivateToken") as String? - } - authentication { - create("header", HttpHeaderAuthentication::class) - } - } -} -``` +### Naming convention -### Authenticate 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.example.com/api/v4/groups/<group>/-/packages/maven" - name "GitLab" - credentials(HttpHeaderCredentials) { - name = 'Deploy-Token' - value = '<deploy-token>' - } - authentication { - header(HttpHeaderAuthentication) - } - } -} -``` +You can use one of three endpoints to install a Maven package. You must publish a package to a project, but the endpoint you choose determines the settings you add to your `pom.xml` file for publishing. -Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: - -```kotlin -repositories { - maven { - url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") - name = "GitLab" - credentials(HttpHeaderCredentials::class) { - name = "Deploy-Token" - value = "<deploy-token>" - } - authentication { - create("header", HttpHeaderAuthentication::class) - } - } -} -``` +The three endpoints are: -### Authenticate 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 "${CI_API_V4_URL}/groups/<group>/-/packages/maven" - name "GitLab" - credentials(HttpHeaderCredentials) { - name = 'Job-Token' - value = System.getenv("CI_JOB_TOKEN") - } - authentication { - header(HttpHeaderAuthentication) - } - } -} -``` +- **Project-level**: Use when you have a few Maven packages and they are not in the same GitLab group. +- **Group-level**: Use when you want to install packages from many different projects in the same GitLab group. GitLab does not guarantee the uniqueness of package names within the group. You can have two projects with the same package name and package version. As a result, GitLab serves whichever one is more recent. +- **Instance-level**: Use when you have many packages in different GitLab groups or in their own namespace. -Or add it to your `build.gradle.kts` file if you are using Kotlin DSL: - -```kotlin -repositories { - maven { - url = uri("$CI_API_V4_URL/groups/<group>/-/packages/maven") - name = "GitLab" - credentials(HttpHeaderCredentials::class) { - name = "Job-Token" - value = System.getenv("CI_JOB_TOKEN") - } - authentication { - create("header", HttpHeaderAuthentication::class) - } - } -} -``` +**Only packages that have the same path as the project** are exposed by the instance-level endpoint. -## Use the GitLab endpoint for Maven packages +| Project | Package | Instance-level endpoint available | +| ------------------- | -------------------------------- | --------------------------------- | +| `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | +| `gitlab-org/gitlab` | `foo/bar/1.0-SNAPSHOT` | No | +| `gitlab-org/gitlab` | `gitlab-org/gitlab/1.0-SNAPSHOT` | Yes | -To use the GitLab endpoint for Maven packages, choose an option: +#### Endpoint URLs -- **Project-level**: To publish Maven packages to a project, use a project-level endpoint. - To install Maven packages, use a project-level endpoint when you have few Maven packages - and they are not in the same GitLab group. -- **Group-level**: Use a group-level endpoint when you want to install packages from - many different projects in the same GitLab group. -- **Instance-level**: Use an instance-level endpoint when you want to install many - packages from different GitLab groups or in their own namespace. +| Endpoint | Endpoint URL for `pom.xml` | Additional information | +| -------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | +| Project | `https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<project_id>` with your project ID, found on your project's homepage. | +| Group | `https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/maven` | Replace `gitlab.example.com` with your domain name. Replace `<group_id>` with your group ID, found on your group's homepage. | +| Instance | `https:///gitlab.example.com/api/v4/packages/maven` | Replace `gitlab.example.com` with your domain name. | -The option you choose determines the settings you add to your `pom.xml` file. +### Edit the `pom.xml` for publishing -In all cases, to publish a package, you need: +No matter which endpoint you choose, you must have: - A project-specific URL in the `distributionManagement` section. - A `repository` and `distributionManagement` section. -### Project-level Maven endpoint - -The relevant `repository` section of your `pom.xml` -in Maven should look like this: +The relevant `repository` section of your `pom.xml` in Maven should look like this: ```xml <repositories> <repository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url><your_endpoint_url></url> </repository> </repositories> <distributionManagement> <repository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url> </repository> <snapshotRepository> <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url> </snapshotRepository> </distributionManagement> ``` -The corresponding section in Gradle Groovy DSL would be: - -```groovy -repositories { - maven { - url "https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven" - name "GitLab" - } -} -``` - -In Kotlin DSL: - -```kotlin -repositories { - maven { - url = uri("https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven") - name = "GitLab" - } -} -``` - -- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). -- The `PROJECT_ID` is your project ID, which you can view on your project's home page. -- Replace `gitlab.example.com` with your domain name. -- For retrieving artifacts, use either the - [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project - (like `group%2Fproject`) or the project's ID (like `42`). However, only the - project's ID can be used for publishing. - -### Group-level Maven endpoint - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. - -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 -all the Maven packages stored within one GitLab group. Only packages you have access to -are available for download. - -The group-level endpoint works with any package names, so you -have more flexibility in naming, compared to the [instance-level endpoint](#instance-level-maven-endpoint). -However, GitLab does not guarantee the uniqueness of package names within -the group. You can have two projects with the same package name and package -version. As a result, GitLab serves whichever one is more recent. - -This example shows the relevant `repository` section of your `pom.xml` file. -You still need a project-specific URL for publishing a package in -the `distributionManagement` section: - -```xml -<repositories> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven</url> - </repository> -</repositories> -<distributionManagement> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </repository> - <snapshotRepository> - <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </snapshotRepository> -</distributionManagement> -``` - -For Gradle, the corresponding `repositories` section in Groovy DSL would look like: - -```groovy -repositories { - maven { - url "https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven" - name "GitLab" - } -} -``` - -In Kotlin DSL: - -```kotlin -repositories { - maven { - url = uri("https://gitlab.example.com/api/v4/groups/GROUP_ID/-/packages/maven") - name = "GitLab" - } -} -``` - -- For the `id`, use what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). -- For `GROUP_ID`, use your group ID, which you can view on your group's home page. -- For `PROJECT_ID`, use your project ID, which you can view on your project's home page. +- The `id` is what you [defined in `settings.xml`](#edit-the-settingsxml). +- The `<your_endpoint_url>` depends on which [endpoint](#endpoint-urls) you choose. - Replace `gitlab.example.com` with your domain name. -- For retrieving artifacts, use either the - [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the group - (like `group%2Fsubgroup`) or the group's ID (like `12`). - -### Instance-level Maven endpoint - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) from GitLab Premium to GitLab Free in 13.3. - -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 -all Maven packages stored in GitLab. All packages you have access to are available -for download. - -**Only packages that have the same path as the project** are exposed by -the instance-level endpoint. - -| Project | Package | Instance-level endpoint available | -| ------------------- | -------------------------------- | --------------------------------- | -| `foo/bar` | `foo/bar/1.0-SNAPSHOT` | Yes | -| `gitlab-org/gitlab` | `foo/bar/1.0-SNAPSHOT` | No | -| `gitlab-org/gitlab` | `gitlab-org/gitlab/1.0-SNAPSHOT` | Yes | - -This example shows how relevant `repository` section of your `pom.xml`. -You still need a project-specific URL in the `distributionManagement` section. - -```xml -<repositories> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/packages/maven</url> - </repository> -</repositories> -<distributionManagement> - <repository> - <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </repository> - <snapshotRepository> - <id>gitlab-maven</id> - <url>https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven</url> - </snapshotRepository> -</distributionManagement> -``` - -The corresponding repositories section in Gradle Groovy DSL would look like: - -```groovy -repositories { - maven { - url "https://gitlab.example.com/api/v4/packages/maven" - name "GitLab" - } -} -``` - -In Kotlin DSL: - -```kotlin -repositories { - maven { - url = uri("https://gitlab.example.com/api/v4/packages/maven") - name = "GitLab" - } -} -``` - -- The `id` is what you [defined in `settings.xml`](#authenticate-to-the-package-registry-with-maven). -- The `PROJECT_ID` is your project ID, which you can view on your project's home page. -- Replace `gitlab.example.com` with your domain name. -- For retrieving artifacts, use either the - [URL-encoded](../../../api/index.md#namespaced-path-encoding) path of the project - (like `group%2Fproject`) or the project's ID (like `42`). However, only the - project's ID can be used for publishing. ## Publish a package -After you have set up the [remote and authentication](#authenticate-to-the-package-registry-with-maven) -and [configured your project](#use-the-gitlab-endpoint-for-maven-packages), +After you have set up the [authentication](#authenticate-to-the-package-registry) +and [chosen an endpoint for publishing](#naming-convention), publish a Maven package to your project. -### Publish by using Maven - To publish a package by using Maven: ```shell @@ -474,122 +135,13 @@ If the deploy is successful, the build success message should be displayed: The message should also show that the package was published to the correct location: ```shell -Uploading to gitlab-maven: https://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar +Uploading to gitlab-maven: https://example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.jar ``` -### Publish by using Gradle - -To publish a package by using Gradle: - -1. Add the Gradle plugin [`maven-publish`](https://docs.gradle.org/current/userguide/publishing_maven.html) to the plugins section: - - In Groovy DSL: - - ```groovy - plugins { - id 'java' - id 'maven-publish' - } - ``` - - In Kotlin DSL: - - ```kotlin - plugins { - java - `maven-publish` - } - ``` - -1. Add a `publishing` section: - - In Groovy DSL: - - ```groovy - publishing { - publications { - library(MavenPublication) { - from components.java - } - } - repositories { - maven { - url "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven" - credentials(HttpHeaderCredentials) { - name = "Private-Token" - value = gitLabPrivateToken // the variable resides in $GRADLE_USER_HOME/gradle.properties - } - authentication { - header(HttpHeaderAuthentication) - } - } - } - } - ``` - - In Kotlin DSL: - - ```kotlin - publishing { - publications { - create<MavenPublication>("library") { - from(components["java"]) - } - } - repositories { - maven { - url = uri("https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/packages/maven") - credentials(HttpHeaderCredentials::class) { - name = "Private-Token" - value = - findProperty("gitLabPrivateToken") as String? // the variable resides in $GRADLE_USER_HOME/gradle.properties - } - authentication { - create("header", HttpHeaderAuthentication::class) - } - } - } - } - ``` - -1. Replace `PROJECT_ID` with your project ID, which can be found on your project's home page. - -1. Run the publish task: - - ```shell - gradle publish - ``` - -Now navigate to your project's **Packages and registries** page and view the published artifacts. - -### Publishing a package with the same name or version - -When you publish a package with the same name and version as an existing package, the new package -files are added to the existing package. You can still use the UI or API to access and view the -existing package's older files. - -To delete these older package versions, consider using the Packages API or the UI. - -#### Do not allow duplicate Maven packages - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/296895) in GitLab 13.9. -> - [Required permissions](https://gitlab.com/gitlab-org/gitlab/-/issues/350682) changed from developer to maintainer in GitLab 15.0. - -To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. - -In the UI: - -1. For your group, go to **Settings > Packages and registries**. -1. Expand the **Package Registry** section. -1. Turn on the **Reject duplicates** toggle. -1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names and/or versions of packages you want to allow. - -Your changes are automatically saved. - ## Install a package To install a package from the GitLab Package Registry, you must configure -the [remote and authenticate](#authenticate-to-the-package-registry-with-maven). +the [remote and authenticate](#authenticate-to-the-package-registry). When this is completed, you can install a package from a project, group, or namespace. @@ -633,8 +185,8 @@ You can install packages by using the Maven `dependency:get` [command](https://m mvn dependency:get -Dartifact=com.nickkipling.app:nick-test-app:1.1-SNAPSHOT -DremoteRepositories=gitlab-maven::::<gitlab endpoint url> -s <path to settings.xml> ``` - - `<gitlab endpoint url>` is the URL of the GitLab [endpoint](#use-the-gitlab-endpoint-for-maven-packages). - - `<path to settings.xml>` is the path to the `settings.xml` file that contains the [authentication details](#authenticate-to-the-package-registry-with-maven). + - `<gitlab endpoint url>` is the URL of the GitLab [endpoint](#endpoint-urls). + - `<path to settings.xml>` is the path to the `settings.xml` file that contains the [authentication details](#edit-the-settingsxml). NOTE: The repository IDs in the command(`gitlab-maven`) and the `settings.xml` file must match. @@ -645,34 +197,34 @@ The message should show that the package is downloading from the Package Registr Downloading from gitlab-maven: http://gitlab.example.com/api/v4/projects/PROJECT_ID/packages/maven/com/mycompany/mydepartment/my-project/1.0-SNAPSHOT/my-project-1.0-20200128.120857-1.pom ``` -NOTE: -In the GitLab UI, on the Package Registry page for Maven, you can view and copy these commands. +## Helpful hints -### Use Gradle +### Publishing a package with the same name or version -Add a [dependency](https://docs.gradle.org/current/userguide/declaring_dependencies.html) to `build.gradle` in the dependencies section: +When you publish a package with the same name and version as an existing package, the new package +files are added to the existing package. You can still use the UI or API to access and view the +existing package's older assets. -```groovy -dependencies { - implementation 'com.mycompany.mydepartment:my-project:1.0-SNAPSHOT' -} -``` +To delete older package versions, consider using the Packages API or the UI. -Or to `build.gradle.kts` if you are using Kotlin DSL: +### Do not allow duplicate Maven packages -```kotlin -dependencies { - implementation("com.mycompany.mydepartment:my-project:1.0-SNAPSHOT") -} -``` +To prevent users from publishing duplicate Maven packages, you can use the [GraphQl API](../../../api/graphql/reference/index.md#packagesettings) or the UI. -### Request forwarding to Maven Central +In the UI: + +1. For your group, go to **Settings > Packages and registries**. +1. Expand the **Package Registry** section. +1. Turn on the **Do not allow duplicates** toggle. +1. Optional. To allow some duplicate packages, in the **Exceptions** box, enter a regex pattern that matches the names and/or versions of packages you want to allow. + +Your changes are automatically saved. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/362657) behind a [feature flag](../../feature_flags.md), disabled by default in GitLab 15.4 +### Request forwarding to Maven Central FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. -On GitLab.com, this feature is not available. +By default this feature is not available for self-managed. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `maven_central_request_forwarding`. +This feature is not available for SaaS users. When a Maven package is not found in the Package Registry, the request is forwarded to [Maven Central](https://search.maven.org/). @@ -690,8 +242,8 @@ GitLab needs to be configured to be queried before maven-central. [Using GitLab as a mirror of the central proxy](#setting-gitlab-as-a-mirror-for-the-central-proxy) is one way to force GitLab to be queried in place of maven-central. -Maven forwarding is restricted to only the [project level](#project-level-maven-endpoint) and -[group level](#group-level-maven-endpoint) endpoints. The [instance level endpoint](#instance-level-maven-endpoint) +Maven forwarding is restricted to only the project level and +group level [endpoints](#naming-convention). The instance level endpoint has naming restrictions that prevent it from being used for packages that don't follow that convention and also introduces too much security risk for supply-chain style attacks. @@ -710,7 +262,7 @@ section to your `settings.xml`: <httpHeaders> <property> <name>Private-Token</name> - <value>{personal_access_token}</value> + <value><personal_access_token></value> </property> </httpHeaders> </configuration> @@ -720,25 +272,19 @@ section to your `settings.xml`: <mirror> <id>central-proxy</id> <name>GitLab proxy of central repo</name> - <url>https://gitlab.example.com/api/v4/projects/{project_id}/packages/maven</url> + <url>https://gitlab.example.com/api/v4/projects/<project_id>/packages/maven</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors> </settings> ``` -## Remove a package - -For your project, go to **Packages and registries > Package Registry**. - -To remove a package, select the red trash icon or, from the package details, the **Delete** button. - -## Create Maven packages with GitLab CI/CD +### Create Maven packages with GitLab CI/CD After you have configured your repository to use the Package Repository for Maven, you can configure GitLab CI/CD to build new packages automatically. -### Create Maven packages with GitLab CI/CD by using Maven +### Create Maven packages with GitLab CI/CD using Maven You can create a new package each time the `main` branch is updated. @@ -808,37 +354,51 @@ user's home location. In this example: - The user is `root`, because the job runs in a Docker container. - Maven uses the configured CI/CD variables. -### Create Maven packages with GitLab CI/CD by using Gradle +### Version validation -You can create a package each time the `main` branch -is updated. +The version string is validated by using the following regex. -1. Authenticate with [a CI job token in Gradle](#authenticate-with-a-ci-job-token-in-gradle). +```ruby +\A(?!.*\.\.)[\w+.-]+\z +``` -1. Add a `deploy` job to your `.gitlab-ci.yml` file: +You can experiment with the regex and try your version strings on [this regular expression editor](https://rubular.com/r/rrLQqUXjfKEoL6). - ```yaml - deploy: - image: gradle:6.5-jdk11 - script: - - 'gradle publish' - only: - - main - ``` +### Useful Maven command-line options -1. Commit files to your repository. +There are some [Maven command-line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) +that you can use when performing tasks with GitLab CI/CD. -When the pipeline is successful, the package is created. +- File transfer progress can make the CI logs hard to read. + Option `-ntp,--no-transfer-progress` was added in + [3.6.1](https://maven.apache.org/docs/3.6.1/release-notes.html#User_visible_Changes). + Alternatively, look at `-B,--batch-mode` + [or lower level logging changes.](https://stackoverflow.com/questions/21638697/disable-maven-download-progress-indication) -### Version validation +- Specify where to find the `pom.xml` file (`-f,--file`): -The version string is validated by using the following regex. + ```yaml + package: + script: + - 'mvn --no-transfer-progress -f helloworld/pom.xml package' + ``` -```ruby -\A(?!.*\.\.)[\w+.-]+\z -``` +- Specify where to find the user settings (`-s,--settings`) instead of + [the default location](https://maven.apache.org/settings.html). There's also a `-gs,--global-settings` option: + + ```yaml + package: + script: + - 'mvn -s settings/ci.xml package' + ``` -You can play around with the regex and try your version strings on [this regular expression editor](https://rubular.com/r/rrLQqUXjfKEoL6). +### Supported CLI commands + +The GitLab Maven repository supports the following Maven CLI commands: + +- `mvn deploy`: Publish your package to the Package Registry. +- `mvn install`: Install packages specified in your Maven project. +- `mvn dependency:get`: Install a specific package. ## Troubleshooting @@ -870,34 +430,6 @@ mvn deploy \ WARNING: When you set these options, all network requests are logged and a large amount of output is generated. -### Useful Maven command-line options - -There are some [Maven command-line options](https://maven.apache.org/ref/current/maven-embedder/cli.html) -that you can use when performing tasks with GitLab CI/CD. - -- File transfer progress can make the CI logs hard to read. - Option `-ntp,--no-transfer-progress` was added in - [3.6.1](https://maven.apache.org/docs/3.6.1/release-notes.html#User_visible_Changes). - Alternatively, look at `-B,--batch-mode` - [or lower level logging changes.](https://stackoverflow.com/questions/21638697/disable-maven-download-progress-indication) - -- Specify where to find the `pom.xml` file (`-f,--file`): - - ```yaml - package: - script: - - 'mvn --no-transfer-progress -f helloworld/pom.xml package' - ``` - -- Specify where to find the user settings (`-s,--settings`) instead of - [the default location](https://maven.apache.org/settings.html). There's also a `-gs,--global-settings` option: - - ```yaml - package: - script: - - 'mvn -s settings/ci.xml package' - ``` - ### Verify your Maven settings If you encounter issues within CI/CD that relate to the `settings.xml` file, try adding @@ -916,11 +448,3 @@ package: - 'mvn help:system' - 'mvn package' ``` - -## Supported CLI commands - -The GitLab Maven repository supports the following Maven CLI commands: - -- `mvn deploy`: Publish your package to the Package Registry. -- `mvn install`: Install packages specified in your Maven project. -- `mvn dependency:get`: Install a specific package. diff --git a/doc/user/packages/package_registry/index.md b/doc/user/packages/package_registry/index.md index 0cd04c81e10..caa305999c5 100644 --- a/doc/user/packages/package_registry/index.md +++ b/doc/user/packages/package_registry/index.md @@ -60,6 +60,9 @@ For most package types, the following credential types are valid: allows access to packages in the project running the job for the users running the pipeline. Access to other external projects can be configured. +- If your organization uses two factor authentication (2FA), you must use a personal access token with the scope set to `api`. +- If you are publishing a package via CI/CD pipelines, you must use a CI job token. + NOTE: If you have not activated the "Packages" feature for your project at **Settings > General > Project features**, you will receive a 403 Forbidden response. Accessing package registry via deploy token is not available when external authorization is enabled. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 9e6c2877ca5..371ab83a4fb 100644 --- a/doc/user/packages/workflows/project_registry.md +++ b/doc/user/packages/workflows/project_registry.md @@ -57,8 +57,8 @@ you do this, you can publish your npm package to your project using `npm publish ### Maven If you are using Maven, you update your `pom.xml` file with distribution sections. These updates include the -appropriate URL for your project, as described in the [GitLab Maven Repository documentation](../maven_repository/index.md#project-level-maven-endpoint). -Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticate-with-a-personal-access-token-in-maven). +appropriate URL for your project, as described in the [GitLab Maven Repository documentation](../maven_repository/index.md#naming-convention). +Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticate-to-the-package-registry). Now you can [publish Maven packages](../maven_repository/index.md#publish-a-package) to your project. ### Conan diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index a6ae3ac80a5..a9f67c39ae8 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -1,56 +1,11 @@ --- -stage: Create -group: Code Review -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -type: index, reference +redirect_to: '../merge_requests/index.md' +remove_date: '2023-03-12' --- -# Commits tab in merge requests **(FREE)** +This document was removed. -The **Commits** tab in a merge request displays a sequential list of commits -to the Git branch your merge request is based on. From this page, you can review -full commit messages and copy a commit's SHA when you need to -[cherry-pick changes](cherry_pick_changes.md). - -## Merge requests commit navigation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0. - -To seamlessly navigate among commits in a merge request: - -1. Select the **Commits** tab. -1. Select a commit to open it in the single-commit view. -1. Navigate through the commits by either: - - - Selecting **Prev** and **Next** buttons below the tab buttons. - - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - -![Merge requests commit navigation](img/commit_nav_v13_11.png) - -## View merge request commits in context - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12 [with a flag](../../../administration/feature_flags.md) named `context_commits`. Enabled by default. -> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.8. -> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) in GitLab 14.9. [Feature flag `context_commits`](https://gitlab.com/gitlab-org/gitlab/-/issues/320757) removed. - -When reviewing a merge request, it helps to have more context about the changes -made. That includes unchanged lines in unchanged files, and previous commits -that have already merged that the change is built on. - -To add previously merged commits to a merge request for more context: - -1. Go to your merge request. -1. Select the **Commits** tab. -1. Scroll to the end of the list of commits, and select **Add previously merged commits**: - - ![Add previously merged commits button](img/add_previously_merged_commits_button_v14_1.png) - -1. Select the commits that you want to add. -1. Select **Save changes**. - -To view the changes done on those previously merged commits: - -1. On your merge request, select the **Changes** tab. -1. Scroll to **(file-tree)** **Compare** and select **previously merged commits**: - - ![Previously merged commits](img/previously_merged_commits_v14_1.png) +<!-- This redirect file can be deleted after <2023-03-12>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> |