Merge branch 'docs-deprecate-new-permissions-doc-2' into 'master'

Docs deprecate "new" CI build permissions doc

See merge request gitlab-org/gitlab!55353

doc/api/README.md

@@ -125,7 +125,7 @@ There are several methods you can use to 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-ci-job-token) **(Specific endpoints only)**
+- [GitLab CI/CD job token](#gitlab-cicd-job-token) **(Specific endpoints only)**
 
 NOTE:
 Project access tokens are supported for self-managed instances on Free and
@@ -198,22 +198,50 @@ The primary user of this authentication method is the web frontend of GitLab
 itself, which can, for example, use the API as the authenticated user to get a
 list of their projects without needing to explicitly pass an access token.
 
-### GitLab CI job token
+### GitLab CI/CD job token
 
-With a few API endpoints you can use a [GitLab CI/CD job token](../user/project/new_ci_build_permissions_model.md#job-token)
-to authenticate with the API:
+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)
+  - [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)
-    (`$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`)
-- [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 is valid as long as the job is running.
+    (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`).
+- [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.
+
+#### 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.
 
 ### Impersonation tokens
 

doc/ci/variables/predefined_variables.md

@@ -59,7 +59,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/README.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/README.md#gitlab-ci-job-token) or download [dependent repositories](../../user/project/new_ci_build_permissions_model.md#dependent-repositories). 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](../../api/README.md#gitlab-cicd-job-token). 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 job tokens](../user/project/new_ci_build_permissions_model.md#job-token)
+  Although not needed for the MVC first iteration, the [CI/CD job tokens](../api/README.md#gitlab-cicd-job-token)
   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](../user/project/new_ci_build_permissions_model.md#job-token), which it uses to execute the job.
+After authentication with GitLab, the runner receives a [job token](../api/README.md#gitlab-cicd-job-token), 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,9 +79,9 @@ Malicious access to a runner's file system may expose the `config.toml` file and
 
 ## CI/CD job tokens
 
-The [CI/CD](../api/README.md#gitlab-ci-job-token) job token
+The [CI/CD](../api/README.md#gitlab-cicd-job-token) 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/README.md#gitlab-ci-job-token).
+access to a limited amount of API endpoints.
 API authentication uses the job token, by using the authorization of the user
 triggering the job.
 
@@ -105,4 +105,4 @@ 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/README.md#gitlab-ci-job-token).
+1. Limited to certain [endpoints](../api/README.md#gitlab-cicd-job-token).

doc/user/packages/generic_packages/index.md

@@ -21,13 +21,13 @@ Publish generic files, like release binaries, in your project’s Package Regist
 ## Authenticate to the Package Registry
 
 To authenticate to the Package Registry, you need either a [personal access token](../../../api/README.md#personalproject-access-tokens),
-[CI job token](../../../api/README.md#gitlab-ci-job-token), or [deploy token](../../project/deploy_tokens/index.md).
+[CI/CD job token](../../../api/README.md#gitlab-cicd-job-token), 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/README.md#personalproject-access-tokens),
-a [CI job token](../../../api/README.md#gitlab-ci-job-token), or a [deploy token](../../project/deploy_tokens/index.md).
+a [CI/CD job token](../../../api/README.md#gitlab-cicd-job-token), or a [deploy token](../../project/deploy_tokens/index.md).
 
 ## Publish a package file
 

doc/user/permissions.md

@@ -482,10 +482,6 @@ instance and project. In addition, all admins can use the admin interface under
 NOTE:
 In GitLab 11.0, the Master role was renamed to Maintainer.
 
-NOTE:
-GitLab 8.12 has a completely redesigned job permissions system.
-Read all about the [new model and its implications](project/new_ci_build_permissions_model.md).
-
 This table shows granted privileges for jobs triggered by specific types of
 users:
 
@@ -507,11 +503,6 @@ users:
 1. Only if the user is not an external one
 1. Only if the user is a member of the project
 
-### New CI job permissions model
-
-GitLab 8.12 has a completely redesigned job permissions system. To learn more,
-read through the documentation on the [new CI/CD permissions model](project/new_ci_build_permissions_model.md#new-ci-job-permissions-model).
-
 ## Running pipelines on protected branches
 
 The permission to merge or push to protected branches is used to define if a user can