Merge branch 'docs-move-ci-token-details' into 'master'

Move CI job token details to new page in CI docs

See merge request gitlab-org/gitlab!69422

app/views/projects/settings/ci_cd/show.html.haml

@@ -105,6 +105,6 @@
         = expanded ? _('Collapse') : _('Expand')
       %p
         = _("Control which projects can be accessed by API requests authenticated with this project's CI_JOB_TOKEN CI/CD variable. It is a security risk to disable this feature, because unauthorized projects might attempt to retrieve an active token and access the API.")
-        = link_to _('Learn more'), help_page_path('api/index', anchor: 'limit-gitlab-cicd-job-token-access'), target: '_blank', rel: 'noopener noreferrer'
+        = link_to _('Learn more'), help_page_path('ci/jobs/ci_job_token'), target: '_blank', rel: 'noopener noreferrer'
     .settings-content
       = render 'ci/token_access/index'

doc/api/index.md

@@ -125,7 +125,7 @@ There are several ways you can authenticate with the GitLab API:
 - [Personal access tokens](../user/profile/personal_access_tokens.md)
 - [Project access tokens](../user/project/settings/project_access_tokens.md)
 - [Session cookie](#session-cookie)
-- [GitLab CI/CD job token](#gitlab-cicd-job-token) **(Specific endpoints only)**
+- [GitLab CI/CD job token](../ci/jobs/ci_job_token.md) **(Specific endpoints only)**
 
 Project access tokens are supported by:
 
@@ -208,126 +208,6 @@ The primary user of this authentication method is the web frontend of GitLab
 itself. The web frontend can use the API as the authenticated user to get a
 list of projects without explicitly passing an access token.
 
-### GitLab CI/CD job token
-
-When a pipeline job is about to run, GitLab generates a unique token and injects it as the
-[`CI_JOB_TOKEN` predefined variable](../ci/variables/predefined_variables.md).
-
-You can use a GitLab CI/CD job token to authenticate with specific API endpoints:
-
-- Packages:
-  - [Package Registry](../user/packages/package_registry/index.md). To push to the
-    Package Registry, you can use [deploy tokens](../user/project/deploy_tokens/index.md).
-  - [Container Registry](../user/packages/container_registry/index.md)
-    (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`).
-  - [Container Registry API](container_registry.md)
-    (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled).
-- [Get job artifacts](job_artifacts.md#get-job-artifacts).
-- [Get job token's job](jobs.md#get-job-tokens-job).
-- [Pipeline triggers](pipeline_triggers.md), using the `token=` parameter.
-- [Release creation](releases/index.md#create-a-release).
-- [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).
-
-The token is valid only while the pipeline job runs. After the job finishes, you can't
-use the token anymore.
-
-A job token can access a project's resources without any configuration, but it might
-give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559)
-to redesign the feature for more strategic control of the access permissions.
-
-You can also use the job token to authenticate and clone a repository from a private project
-in a CI/CD job:
-
-```shell
-git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>
-```
-
-#### GitLab CI/CD job token security
-
-To make sure that this token doesn't leak, GitLab:
-
-- Masks the job token in job logs.
-- Grants permissions to the job token only when the job is running.
-
-To make sure that this token doesn't leak, you should also configure
-your [runners](../ci/runners/README.md) to be secure. Avoid:
-
-- Using Docker's `privileged` mode if the machines are re-used.
-- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs
-  run on the same machine.
-
-If you have an insecure GitLab Runner configuration, you increase the risk that someone
-tries to steal tokens from other jobs.
-
-#### Limit GitLab CI/CD job token access
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1.
-> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default.
-> - Disabled on GitLab.com.
-> - Not recommended for production use.
-> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)**
-
-This in-development feature might not be available for your use. There can be
-[risks when enabling features still in development](../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
-Refer to this feature's version history for more details.
-
-You can limit the access scope of a project's CI/CD job token to increase the
-job token's security. A job token might give extra permissions that aren't necessary
-to access specific private resources. Limiting the job token access scope reduces the risk of a leaked
-token being used to access private data that the user associated to the job can access.
-
-Control the job token access scope with an allowlist of other projects authorized
-to be accessed by authenticating with the current project's job token. By default
-the token scope only allows access to the same project where the token comes from.
-Other projects can be added and removed by maintainers with access to both projects.
-
-This setting is enabled by default for all new projects, and disabled by default in projects
-created before GitLab 14.1. It is strongly recommended that project maintainers enable this
-setting at all times, and configure the allowlist for cross-project access if needed.
-
-For example, when the setting is enabled, jobs in a pipeline in project `A` have
-a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token
-to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`.
-If project `B` is public or internal, it doesn't need to be added to the allowlist.
-The job token scope is only for controlling access to private projects.
-
-To enable and configure the job token scope limit:
-
-1. On the top bar, select **Menu > Projects** and find your project.
-1. On the left sidebar, select **Settings > CI/CD**.
-1. Expand **Token Access**.
-1. Toggle **Limit CI_JOB_TOKEN access** to enabled.
-1. (Optional) Add existing projects to the token's access scope. The user adding a
-   project must have the [maintainer role](../user/permissions.md) in both projects.
-
-If the job token scope limit is disabled, the token can potentially be used to authenticate
-API requests to all projects accessible to the user that triggered the job.
-
-There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve
-the feature with more strategic control of the access permissions.
-
-##### Enable or disable CI job token scope limit **(FREE SELF)**
-
-The GitLab CI/CD job token access scope limit is under development and not ready for production
-use. It is deployed behind a feature flag that is **disabled by default**.
-[GitLab administrators with access to the GitLab Rails console](../administration/feature_flags.md)
-can enable it.
-
-To enable it:
-
-```ruby
-Feature.enable(:ci_scoped_job_token)
-```
-
-To disable it:
-
-```ruby
-Feature.disable(:ci_scoped_job_token)
-```
-
 ### Impersonation tokens
 
 Impersonation tokens are a type of [personal access token](../user/profile/personal_access_tokens.md).

doc/api/releases/index.md

@@ -21,7 +21,7 @@ For authentication, the Releases API accepts either:
 
 - A [Personal Access Token](../../user/profile/personal_access_tokens.md) using the
   `PRIVATE-TOKEN` header.
-- The [GitLab CI/CD job token](../index.md#gitlab-cicd-job-token) `$CI_JOB_TOKEN` using
+- The [GitLab CI/CD job token](../../ci/jobs/ci_job_token.md) `$CI_JOB_TOKEN` using
   the `JOB-TOKEN` header.
 
 ## List Releases

doc/ci/jobs/ci_job_token.md

+---
+stage: Verify
+group: Pipeline Execution
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# GitLab CI/CD job token
+
+When a pipeline job is about to run, GitLab generates a unique token and injects it as the
+[`CI_JOB_TOKEN` predefined variable](../variables/predefined_variables.md).
+
+You can use a GitLab CI/CD job token to authenticate with specific API endpoints:
+
+- Packages:
+  - [Package Registry](../../user/packages/package_registry/index.md). To push to the
+    Package Registry, you can use [deploy tokens](../../user/project/deploy_tokens/index.md).
+  - [Container Registry](../../user/packages/container_registry/index.md)
+    (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`).
+  - [Container Registry API](../../api/container_registry.md)
+    (scoped to the job's project, when the `ci_job_token_scope` feature flag is enabled).
+- [Get job artifacts](../../api/job_artifacts.md#get-job-artifacts).
+- [Get job token's job](../../api/jobs.md#get-job-tokens-job).
+- [Pipeline triggers](../../api/pipeline_triggers.md), using the `token=` parameter.
+- [Release creation](../../api/releases/index.md#create-a-release).
+- [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).
+
+The token is valid only while the pipeline job runs. After the job finishes, you can't
+use the token anymore.
+
+A job token can access a project's resources without any configuration, but it might
+give extra permissions that aren't necessary. There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559)
+to redesign the feature for more strategic control of the access permissions.
+
+You can also use the job token to authenticate and clone a repository from a private project
+in a CI/CD job:
+
+```shell
+git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>
+```
+
+## GitLab CI/CD job token security
+
+To make sure that this token doesn't leak, GitLab:
+
+- Masks the job token in job logs.
+- Grants permissions to the job token only when the job is running.
+
+To make sure that this token doesn't leak, you should also configure
+your [runners](../runners/index.md) to be secure. Avoid:
+
+- Using Docker's `privileged` mode if the machines are re-used.
+- Using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs
+  run on the same machine.
+
+If you have an insecure GitLab Runner configuration, you increase the risk that someone
+tries to steal tokens from other jobs.
+
+## Limit GitLab CI/CD job token access
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1.
+> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-ci-job-token-scope-limit). **(FREE SELF)**
+
+This in-development feature might not be available for your use. There can be
+[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
+Refer to this feature's version history for more details.
+
+You can limit the access scope of a project's CI/CD job token to increase the
+job token's security. A job token might give extra permissions that aren't necessary
+to access specific private resources. Limiting the job token access scope reduces the risk of a leaked
+token being used to access private data that the user associated to the job can access.
+
+Control the job token access scope with an allowlist of other projects authorized
+to be accessed by authenticating with the current project's job token. By default
+the token scope only allows access to the same project where the token comes from.
+Other projects can be added and removed by maintainers with access to both projects.
+
+This setting is enabled by default for all new projects, and disabled by default in projects
+created before GitLab 14.1. It is strongly recommended that project maintainers enable this
+setting at all times, and configure the allowlist for cross-project access if needed.
+
+For example, when the setting is enabled, jobs in a pipeline in project `A` have
+a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token
+to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`.
+If project `B` is public or internal, it doesn't need to be added to the allowlist.
+The job token scope is only for controlling access to private projects.
+
+To enable and configure the job token scope limit:
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Settings > CI/CD**.
+1. Expand **Token Access**.
+1. Toggle **Limit CI_JOB_TOKEN access** to enabled.
+1. (Optional) Add existing projects to the token's access scope. The user adding a
+   project must have the [maintainer role](../../user/permissions.md) in both projects.
+
+If the job token scope limit is disabled, the token can potentially be used to authenticate
+API requests to all projects accessible to the user that triggered the job.
+
+There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve
+the feature with more strategic control of the access permissions.
+
+### Enable or disable CI job token scope limit **(FREE SELF)**
+
+The GitLab CI/CD job token access scope limit is under development and not ready for production
+use. It is deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md)
+can enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:ci_scoped_job_token)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:ci_scoped_job_token)
+```

doc/ci/variables/predefined_variables.md

@@ -63,7 +63,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu
 | `CI_JOB_NAME`                            | 9.0    | 0.5    | The name of the job. |
 | `CI_JOB_STAGE`                           | 9.0    | 0.5    | The name of the job's stage. |
 | `CI_JOB_STATUS`                          | all    | 13.5   | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. |
-| `CI_JOB_TOKEN`                           | 9.0    | 1.2    | A token to authenticate with [certain API endpoints](../../api/index.md#gitlab-cicd-job-token). The token is valid as long as the job is running. |
+| `CI_JOB_TOKEN`                           | 9.0    | 1.2    | A token to authenticate with [certain API endpoints](../jobs/ci_job_token.md). The token is valid as long as the job is running. |
 | `CI_JOB_URL`                             | 11.1   | 0.5    | The job details URL. |
 | `CI_JOB_STARTED_AT`                      | 13.10  | all    | The UTC datetime when a job started, in [ISO 8601](https://tools.ietf.org/html/rfc3339#appendix-A) format. |
 | `CI_KUBERNETES_ACTIVE`                   | 13.0   | all    | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. |

doc/development/packages.md

@@ -133,7 +133,7 @@ During this phase, the idea is to collect as much information as possible about
 - **Authentication**: What authentication mechanisms are available (OAuth, Basic
   Authorization, other). Keep in mind that GitLab users often want to use their
   [Personal Access Tokens](../user/profile/personal_access_tokens.md).
-  Although not needed for the MVC first iteration, the [CI/CD job tokens](../api/index.md#gitlab-cicd-job-token)
+  Although not needed for the MVC first iteration, the [CI/CD job tokens](../ci/jobs/ci_job_token.md)
   have to be supported at some point in the future.
 - **Requests**: Which requests are needed to have a working MVC. Ideally, produce
   a list of all the requests needed for the MVC (including required actions). Further

doc/security/token_overview.md

@@ -71,7 +71,7 @@ You can use the runner registration token to add runners that execute jobs in a
 
 After registration, the runner receives an authentication token, which it uses to authenticate with GitLab when picking up jobs from the job queue. The authentication token is stored locally in the runner's [`config.toml`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) file.
 
-After authentication with GitLab, the runner receives a [job token](../api/index.md#gitlab-cicd-job-token), which it uses to execute the job.
+After authentication with GitLab, the runner receives a [job token](../ci/jobs/ci_job_token.md), which it uses to execute the job.
 
 In case of Docker Machine/Kubernetes/VirtualBox/Parallels/SSH executors, the execution environment has no access to the runner authentication token, because it stays on the runner machine. They have access to the job token only, which is needed to execute the job.
 
@@ -79,7 +79,7 @@ Malicious access to a runner's file system may expose the `config.toml` file and
 
 ## CI/CD job tokens
 
-The [CI/CD](../api/index.md#gitlab-cicd-job-token) job token
+The [CI/CD](../ci/jobs/ci_job_token.md) job token
 is a short lived token only valid for the duration of a job. It gives a CI/CD job
 access to a limited amount of API endpoints.
 API authentication uses the job token, by using the authorization of the user
@@ -105,7 +105,7 @@ This table shows available scopes per token. Scopes can be limited further on to
 
 1. Limited to the one project.
 1. Runner registration and authentication token don't provide direct access to repositories, but can be used to register and authenticate a new runner that may execute jobs which do have access to the repository
-1. Limited to certain [endpoints](../api/index.md#gitlab-cicd-job-token).
+1. Limited to certain [endpoints](../ci/jobs/ci_job_token.md).
 
 ## Security considerations
 

doc/user/packages/debian_repository/index.md

@@ -67,7 +67,7 @@ To create a distribution, publish a package, or install a private package, you n
 following:
 
 - [Personal access token](../../../api/index.md#personalproject-access-tokens)
-- [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token)
+- [CI/CD job token](../../../ci/jobs/ci_job_token.md)
 - [Deploy token](../../project/deploy_tokens/index.md)
 
 ## Create a Distribution

doc/user/packages/generic_packages/index.md

@@ -21,13 +21,13 @@ Publish generic files, like release binaries, in your project's Package Registry
 ## Authenticate to the Package Registry
 
 To authenticate to the Package Registry, you need either a [personal access token](../../../api/index.md#personalproject-access-tokens),
-[CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or [deploy token](../../project/deploy_tokens/index.md).
+[CI/CD job token](../../../ci/jobs/ci_job_token.md), or [deploy token](../../project/deploy_tokens/index.md).
 
 In addition to the standard API authentication mechanisms, the generic package
 API allows authentication with HTTP Basic authentication for use with tools that
 do not support the other available mechanisms. The `user-id` is not checked and
 may be any value, and the `password` must be either a [personal access token](../../../api/index.md#personalproject-access-tokens),
-a [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md).
+a [CI/CD job token](../../../ci/jobs/ci_job_token.md), or a [deploy token](../../project/deploy_tokens/index.md).
 
 ## Publish a package file
 

doc/user/packages/helm_repository/index.md

@@ -27,7 +27,7 @@ To authenticate to the Helm repository, you need either:
 
 - A [personal access token](../../../api/index.md#personalproject-access-tokens).
 - A [deploy token](../../project/deploy_tokens/index.md).
-- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token).
+- A [CI/CD job token](../../../ci/jobs/ci_job_token.md).
 
 ## Publish a package
 

doc/user/packages/terraform_module_registry/index.md

@@ -16,7 +16,7 @@ as a Terraform module registry.
 To authenticate to the Terraform module registry, you need either:
 
 - A [personal access token](../../../api/index.md#personalproject-access-tokens) with at least `read_api` rights.
-- A [CI/CD job token](../../../api/index.md#gitlab-cicd-job-token).
+- A [CI/CD job token](../../../ci/jobs/ci_job_token.md).
 
 ## Publish a Terraform Module