Merge branch 'docs-ci-token-page' into 'master'

Move more ci token details to dedicated page

See merge request gitlab-org/gitlab!69872

doc/api/job_artifacts.md

@@ -20,7 +20,7 @@ GET /projects/:id/jobs/:job_id/artifacts
 |-------------|----------------|----------|--------------------------------------------------------------------------------------------------------------|
 | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `job_id`    | integer        | yes      | ID of a job.                                                                                                 |
-| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
+| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
 Example request using the `PRIVATE-TOKEN` header:
 
@@ -85,7 +85,7 @@ Parameters
 | `id`        | integer/string | yes      | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `ref_name`  | string         | yes      | Branch or tag name in repository. HEAD or SHA references are not supported.                                  |
 | `job`       | string         | yes      | The name of the job.                                                                                         |
-| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
+| `job_token` **(PREMIUM)** | string | no | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
 Example request using the `PRIVATE-TOKEN` header:
 
@@ -146,7 +146,7 @@ Parameters
 | `id`            | integer/string | yes      | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `job_id`        | integer        | yes      | The unique job identifier.                                                                                       |
 | `artifact_path` | string         | yes      | Path to a file inside the artifacts archive.                                                                     |
-| `job_token` **(PREMIUM)** | string | no     | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
+| `job_token` **(PREMIUM)** | string | no     | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
 Example request:
 
@@ -188,7 +188,7 @@ Parameters:
 | `ref_name`      | string         | yes      | Branch or tag name in repository. `HEAD` or `SHA` references are not supported.                              |
 | `artifact_path` | string         | yes      | Path to a file inside the artifacts archive.                                                                 |
 | `job`           | string         | yes      | The name of the job.                                                                                         |
-| `job_token` **(PREMIUM)** | string | no     | To be used with [triggers](../ci/triggers/index.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
+| `job_token` **(PREMIUM)** | string | no     | To be used with [triggers](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline) for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. |
 
 Example request:
 

doc/ci/jobs/ci_job_token.md

@@ -25,7 +25,7 @@ You can use a GitLab CI/CD job token to authenticate with specific API endpoints
 - [Terraform plan](../../user/infrastructure/index.md).
 
 The token has the same permissions to access the API as the user that triggers the
-pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../../user/permissions.md).
+pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions).
 
 The token is valid only while the pipeline job runs. After the job finishes, you can't
 use the token anymore.
@@ -123,3 +123,43 @@ To disable it:
 ```ruby
 Feature.disable(:ci_scoped_job_token)
 ```
+
+## Trigger a multi-project pipeline by using a CI job token
+
+> `CI_JOB_TOKEN` for multi-project pipelines was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) from GitLab Premium to GitLab Free in 12.4.
+
+You can use the `CI_JOB_TOKEN` to trigger [multi-project pipelines](../pipelines/multi_project_pipelines.md)
+from a CI/CD job. A pipeline triggered this way creates a dependent pipeline relation
+that is visible on the [pipeline graph](../pipelines/multi_project_pipelines.md#multi-project-pipeline-visualization).
+
+For example:
+
+```yaml
+trigger_pipeline:
+  stage: deploy
+  script:
+    - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
+  rules:
+    - if: $CI_COMMIT_TAG
+```
+
+If you use the `CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md)
+in a pipeline triggered this way, [the value is `pipeline` (not `triggered`)](../triggers/index.md#authentication-tokens).
+
+## Download an artifact from a different pipeline **(PREMIUM)**
+
+> `CI_JOB_TOKEN` for artifacts download with the API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in GitLab 9.5.
+
+You can use the `CI_JOB_TOKEN` to access artifacts from a job created by a previous
+pipeline. You must specify which job you want to retrieve the artifacts from:
+
+```yaml
+build_submodule:
+  stage: test
+  script:
+    - apt update && apt install -y unzip
+    - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
+    - unzip artifacts.zip
+```
+
+Read more about the [jobs artifacts API](../../api/job_artifacts.md#download-the-artifacts-archive).

doc/ci/jobs/job_control.md

@@ -225,7 +225,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
 | `pipeline`                    | For [multi-project pipelines](../pipelines/multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../pipelines/multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](../yaml/index.md#trigger) keyword. |
 | `push`                        | For pipelines triggered by a `git push` event, including for branches and tags.                                                                                                                                                  |
 | `schedule`                    | For [scheduled pipelines](../pipelines/schedules.md).                                                                                                                                                                            |
-| `trigger`                     | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token).                                                                                                                                           |
+| `trigger`                     | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens).                                                                                                                                           |
 | `web`                         | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section.                                                                                                       |
 | `webide`                      | For pipelines created by using the [WebIDE](../../user/project/web_ide/index.md).                                                                                                                                                |
 
@@ -335,7 +335,7 @@ to control when to add jobs to pipelines.
 In the following example, `job` runs only for:
 
 - Git tags
-- [Triggers](../triggers/index.md#trigger-token)
+- [Triggers](../triggers/index.md#authentication-tokens)
 - [Scheduled pipelines](../pipelines/schedules.md)
 
 ```yaml

doc/ci/pipelines/multi_project_pipelines.md

@@ -273,7 +273,7 @@ upstream_bridge:
 
 > [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) to GitLab Free in 12.4.
 
-When you use the [`CI_JOB_TOKEN` to trigger pipelines](../triggers/index.md#ci-job-token),
+When you use the [`CI_JOB_TOKEN` to trigger pipelines](../jobs/ci_job_token.md),
 GitLab recognizes the source of the job token. The pipelines become related,
 so you can visualize their relationships on pipeline graphs.
 

doc/ci/triggers/index.md

@@ -14,8 +14,8 @@ tag) with an API call.
 
 The following methods of authentication are supported:
 
-- [Trigger token](#trigger-token)
-- [CI job token](#ci-job-token)
+- Trigger tokens: A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger).
+- [CI job tokens](../jobs/ci_job_token.md).
 
 If using the `$CI_PIPELINE_SOURCE` [predefined CI/CD variable](../variables/predefined_variables.md)
 to limit which jobs run in a pipeline, the value could be either `pipeline` or `trigger`,
@@ -28,71 +28,6 @@ depending on which trigger method is used.
 
 This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/index.md#only--except).
 
-### Trigger token
-
-A unique trigger token can be obtained when [adding a new trigger](#adding-a-new-trigger).
-
-WARNING:
-Passing plain text tokens in public projects is a security issue. Potential
-attackers can impersonate the user that exposed their trigger token publicly in
-their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md)
-to protect trigger tokens.
-
-### CI job token
-
-You can use the `CI_JOB_TOKEN` [CI/CD variable](../variables/index.md#predefined-cicd-variables) (used to authenticate
-with the [GitLab Container Registry](../../user/packages/container_registry/index.md)) in the following cases.
-
-#### When used with multi-project pipelines
-
-> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2017) in GitLab Premium 9.3.
-> - Use of `CI_JOB_TOKEN` for multi-project pipelines was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) from GitLab Premium to GitLab Free in 12.4.
-
-This way of triggering can only be used when invoked inside `.gitlab-ci.yml`,
-and it creates a dependent pipeline relation visible on the
-[pipeline graph](../pipelines/multi_project_pipelines.md). For example:
-
-```yaml
-trigger_pipeline:
-  stage: deploy
-  script:
-    - curl --request POST --form "token=$CI_JOB_TOKEN" --form ref=main "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
-  rules:
-    - if: $CI_COMMIT_TAG
-```
-
-Pipelines triggered that way also expose a special variable:
-`CI_PIPELINE_SOURCE=pipeline`.
-
-Read more about the [pipelines trigger API](../../api/pipeline_triggers.md).
-
-#### When a pipeline depends on the artifacts of another pipeline **(PREMIUM)**
-
-> The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in GitLab 9.5.
-
-With the introduction of dependencies between different projects, one of
-them may need to access artifacts created by a previous one. This process
-must be granted for authorized accesses, and it can be done using the
-`CI_JOB_TOKEN` variable that identifies a specific job. For example:
-
-```yaml
-build_submodule:
-  image: debian
-  stage: test
-  script:
-    - apt update && apt install -y unzip
-    - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
-    - unzip artifacts.zip
-  rules:
-    - if: $CI_COMMIT_TAG
-```
-
-This allows you to use that for multi-project pipelines and download artifacts
-from any project to which you have access as this follows the same principles
-with the [permission model](../../user/permissions.md#job-permissions).
-
-Read more about the [jobs API](../../api/job_artifacts.md#download-the-artifacts-archive).
-
 ## Adding a new trigger
 
 Go to your
@@ -106,6 +41,12 @@ overview of the time the triggers were last used.
 
 ![Triggers page overview](img/triggers_page.png)
 
+WARNING:
+Passing plain text tokens in public projects is a security issue. Potential
+attackers can impersonate the user that exposed their trigger token publicly in
+their `.gitlab-ci.yml` file. Use [CI/CD variables](../variables/index.md)
+to protect trigger tokens.
+
 ## Revoking a trigger
 
 You can revoke a trigger any time by going at your project's

doc/ci/yaml/index.md

@@ -1367,7 +1367,7 @@ pipeline based on branch names or pipeline types.
   | `pushes`                 | For pipelines triggered by a `git push` event, including for branches and tags. |
   | `schedules`              | For [scheduled pipelines](../pipelines/schedules.md). |
   | `tags`                   | When the Git reference for a pipeline is a tag. |
-  | `triggers`               | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). |
+  | `triggers`               | For pipelines created by using a [trigger token](../triggers/index.md#authentication-tokens). |
   | `web`                    | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. |
 
 **Example of `only:refs` and `except:refs`**:

doc/user/packages/container_registry/index.md

@@ -154,7 +154,7 @@ To use CI/CD to authenticate, you can use:
   docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
   ```
 
-- A [CI job token](../../../ci/triggers/index.md#ci-job-token).
+- A [CI job token](../../../ci/jobs/ci_job_token.md).
 
   ```shell
   docker login -u $CI_JOB_USER -p $CI_JOB_TOKEN $CI_REGISTRY