From e43364618e59e13af330b44c3d2e94029f949bd6 Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Mon, 5 Feb 2024 21:45:23 +0000
Subject: [PATCH] Revamp CI/CD token docs

Full rewrite of majority of job token docs. Move
some content out to correct page, reorganize and clarify
most sections in the page to help reduce confusion
and bring page up to standards
---
 .../15-9-insecure-ci-job-token.yml            |   2 +-
 .../16-3-CI-job-token-scope-update.yml        |   2 +-
 .../16-5-ci-job-token-limit-setting.yml       |   2 +-
 .../16-8-job-token-remove-scope-direction.yml |   2 +-
 doc/api/job_artifacts.md                      |  10 +-
 doc/api/project_job_token_scopes.md           |  10 +-
 doc/architecture/blueprints/runway/index.md   |   2 +-
 doc/ci/debugging.md                           |   2 +-
 doc/ci/git_submodules.md                      |   2 +-
 doc/ci/jobs/ci_job_token.md                   | 234 ++++++++----------
 doc/ci/jobs/job_artifacts.md                  |  19 ++
 doc/ci/pipelines/downstream_pipelines.md      |   6 +-
 doc/update/deprecations.md                    |   8 +-
 .../packages/workflows/project_registry.md    |   2 +-
 14 files changed, 152 insertions(+), 151 deletions(-)

diff --git a/data/deprecations/15-9-insecure-ci-job-token.yml b/data/deprecations/15-9-insecure-ci-job-token.yml
index f807c337de839..0c15130d24bc0 100644
--- a/data/deprecations/15-9-insecure-ci-job-token.yml
+++ b/data/deprecations/15-9-insecure-ci-job-token.yml
@@ -11,7 +11,7 @@
   body: |  # (required) Do not modify this line, instead modify the lines below.
     In GitLab 14.4 we introduced the ability to [limit your project's CI/CD job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#limit-your-projects-job-token-access) (`CI_JOB_TOKEN`) access to make it more secure. You can prevent job tokens **from your project's** pipelines from being used to **access other projects**. When enabled with no other configuration, your pipelines cannot access other projects. To use the job token to access other projects from your pipeline, you must list those projects explicitly in the **Limit CI_JOB_TOKEN access** setting's allowlist, and you must be a maintainer in all the projects.
 
-    The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#allow-access-to-your-project-with-a-job-token). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
+    The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
 
     As a result, the **Limit** setting is deprecated in preference of the better **Allow access** setting. In GitLab 16.0 the **Limit** setting will be disabled by default for all new projects. In projects with this setting currently enabled, it will continue to function as expected, but you will not be able to add any more projects to the allowlist. If the setting is disabled in any project, it will not be possible to re-enable this setting in 16.0 or later.
 
diff --git a/data/deprecations/16-3-CI-job-token-scope-update.yml b/data/deprecations/16-3-CI-job-token-scope-update.yml
index 5867cedcc539d..4c12831fded78 100644
--- a/data/deprecations/16-3-CI-job-token-scope-update.yml
+++ b/data/deprecations/16-3-CI-job-token-scope-update.yml
@@ -9,7 +9,7 @@
   stage: Verify  # (required) String value of the stage that the feature was created in. e.g., Growth
   issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/420678  # (required) Link to the deprecation issue in GitLab
   body: |  # (required) Do not modify this line, instead modify the lines below.
-    Starting in 16.6, projects that are **public** or **internal** will no longer authorize job token requests from projects that are **not** on the project's allowlist when [**Limit access to this project**](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#allow-access-to-your-project-with-a-job-token) is enabled.
+    Starting in 16.6, projects that are **public** or **internal** will no longer authorize job token requests from projects that are **not** on the project's allowlist when [**Limit access to this project**](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist) is enabled.
 
     If you have [public or internal](https://docs.gitlab.com/ee/user/public_access.html#change-project-visibility) projects with the **Limit access to this project** setting enabled, you must add any projects which make job token requests to your project's allowlist for continued authorization.
 #
diff --git a/data/deprecations/16-5-ci-job-token-limit-setting.yml b/data/deprecations/16-5-ci-job-token-limit-setting.yml
index aec1977551331..557d29fb47223 100644
--- a/data/deprecations/16-5-ci-job-token-limit-setting.yml
+++ b/data/deprecations/16-5-ci-job-token-limit-setting.yml
@@ -11,7 +11,7 @@
   body: |  # (required) Do not modify this line, instead modify the lines below.
     In GitLab 14.4 we introduced the ability to [limit your project's CI/CD job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#limit-your-projects-job-token-access) (`CI_JOB_TOKEN`) access to make it more secure. You can prevent job tokens **from your project's** pipelines from being used to **access other projects**. When enabled with no other configuration, your pipelines cannot access other projects. To use the job token to access other projects from your pipeline, you must list those projects explicitly in the **Limit CI_JOB_TOKEN access** setting's allowlist, and you must be a maintainer in all the projects.
 
-    The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#allow-access-to-your-project-with-a-job-token). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
+    The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
 
     The **Limit** setting was deprecated in 16.0 in preference of the better **Allow access** setting and **Limit** setting was disabled by default for all new projects. From this point forward, if the **Limit** setting is disabled in any project, it will not be possible to re-enable this setting in 16.0 or later.
 
diff --git a/data/deprecations/16-8-job-token-remove-scope-direction.yml b/data/deprecations/16-8-job-token-remove-scope-direction.yml
index 5c8fffe085cfa..ce521ba40830a 100644
--- a/data/deprecations/16-8-job-token-remove-scope-direction.yml
+++ b/data/deprecations/16-8-job-token-remove-scope-direction.yml
@@ -14,7 +14,7 @@
   body: |  # (required) Don't change this line.
     The `direction` GraphQL argument for the `ciJobTokenScopeRemoveProject` mutation is deprecated. Following the [default CI/CD job token scope change](https://docs.gitlab.com/ee/update/deprecations.html#default-cicd-job-token-ci_job_token-scope-changed) announced in GitLab 15.9, the `direction` argument will default to `INBOUND` and `OUTBOUND` will no longer be valid in GitLab 17.0. We will remove the `direction` argument in GitLab 18.0.
 
-    If you are using `OUTBOUND` with the `direction` argument to control the direction of your project's token access, your pipeline that use job tokens risk failing authentication. To ensure pipelines continue to run as expected, you will need to explicitly [add the other projects to your project's allowlist](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-scope-allowlist).
+    If you are using `OUTBOUND` with the `direction` argument to control the direction of your project's token access, your pipeline that use job tokens risk failing authentication. To ensure pipelines continue to run as expected, you will need to explicitly [add the other projects to your project's allowlist](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist).
 
 # ==============================
 # OPTIONAL END-OF-SUPPORT FIELDS
diff --git a/doc/api/job_artifacts.md b/doc/api/job_artifacts.md
index adae58c734143..ba2f4cc903a1c 100644
--- a/doc/api/job_artifacts.md
+++ b/doc/api/job_artifacts.md
@@ -12,7 +12,7 @@ DETAILS:
 
 Use the job artifacts API to download or delete job artifacts.
 
-Authentication with a [CI/CD job token](../ci/jobs/ci_job_token.md#download-an-artifact-from-a-different-pipeline)
+Authentication with a [CI/CD job token](../ci/jobs/job_artifacts.md#with-a-cicd-job-token)
 available in the Premium and Ultimate tier.
 
 ## Get job artifacts
@@ -32,7 +32,7 @@ GET /projects/:id/jobs/:job_id/artifacts
 |-------------------------------|----------------|----------|-------------|
 | `id`                          | integer/string | Yes      | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
 | `job_id`                      | integer        | Yes      | ID of a job. |
-| `job_token`                   | 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 in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
+| `job_token`                   | string         | No       | To be used with [triggers](../ci/jobs/job_artifacts.md#with-a-cicd-job-token) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
 
 Example request using the `PRIVATE-TOKEN` header:
 
@@ -102,7 +102,7 @@ Parameters
 | `id`                          | integer/string | Yes      | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
 | `job`                         | string         | Yes      | The name of the job. |
 | `ref_name`                    | string         | Yes      | Branch or tag name in repository. HEAD or SHA references are not supported. |
-| `job_token`                   | 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 in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
+| `job_token`                   | string         | No       | To be used with [triggers](../ci/jobs/job_artifacts.md#with-a-cicd-job-token) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
 
 Example request using the `PRIVATE-TOKEN` header:
 
@@ -165,7 +165,7 @@ Parameters
 | `artifact_path`               | string         | Yes      | Path to a file inside the artifacts archive. |
 | `id`                          | integer/string | Yes      | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
 | `job_id`                      | integer        | Yes      | The unique job identifier. |
-| `job_token`                   | 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 in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
+| `job_token`                   | string         | No       | To be used with [triggers](../ci/jobs/job_artifacts.md#with-a-cicd-job-token) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
 
 Example request:
 
@@ -212,7 +212,7 @@ Parameters:
 | `id`                          | integer/string | Yes      | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
 | `job`                         | string         | Yes      | The name of the job. |
 | `ref_name`                    | string         | Yes      | Branch or tag name in repository. `HEAD` or `SHA` references are not supported. |
-| `job_token`                   | 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 in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
+| `job_token`                   | string         | No       | To be used with [triggers](../ci/jobs/job_artifacts.md#with-a-cicd-job-token) for multi-project pipelines. It should be invoked only in a CI/CD job defined in the `.gitlab-ci.yml` file. The value is always `$CI_JOB_TOKEN`. The job associated with the `$CI_JOB_TOKEN` must be running when this token is used. Premium and Ultimate only. |
 
 Example request:
 
diff --git a/doc/api/project_job_token_scopes.md b/doc/api/project_job_token_scopes.md
index 8d87913a0433c..7f9a4a6e59b35 100644
--- a/doc/api/project_job_token_scopes.md
+++ b/doc/api/project_job_token_scopes.md
@@ -18,7 +18,7 @@ The authenticated user must have at least the Maintainer role for the project.
 
 ## Get a project's CI/CD job token access settings
 
-Fetch the [CI/CD job token access settings](../ci/jobs/ci_job_token.md#configure-cicd-job-token-access) (job token scope) of a project.
+Fetch the [CI/CD job token access settings](../ci/jobs/ci_job_token.md#control-job-token-access-to-your-project) (job token scope) of a project.
 
 ```plaintext
 GET /projects/:id/job_token_scope
@@ -56,7 +56,7 @@ Example response:
 
 > - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
 
-Patch the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#disable-the-job-token-scope-allowlist) (job token scope) of a project.
+Patch the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) (job token scope) of a project.
 
 ```plaintext
 PATCH /projects/:id/job_token_scope
@@ -83,7 +83,7 @@ curl --request PATCH \
 
 ## Get a project's CI/CD job token inbound allowlist
 
-Fetch the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) (job token scope) of a project.
+Fetch the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) (job token scope) of a project.
 
 ```plaintext
 GET /projects/:id/job_token_scope/allowlist
@@ -150,7 +150,7 @@ Example response:
 
 ## Add a project to a CI/CD job token inbound allowlist
 
-Add a project to the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) of a project.
+Add a project to the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) of a project.
 
 ```plaintext
 POST /projects/:id/job_token_scope/allowlist
@@ -191,7 +191,7 @@ Example response:
 
 ## Remove a project from a CI/CD job token inbound allowlist
 
-Remove a project from the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) of a project.
+Remove a project from the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) of a project.
 
 ```plaintext
 DELETE /projects/:id/job_token_scope/allowlist/:target_project_id
diff --git a/doc/architecture/blueprints/runway/index.md b/doc/architecture/blueprints/runway/index.md
index c55bfaf883cb5..98d9e7548819c 100644
--- a/doc/architecture/blueprints/runway/index.md
+++ b/doc/architecture/blueprints/runway/index.md
@@ -195,7 +195,7 @@ The goal of Runway is to not rely on long lived secrets or tokens inside the run
 
 #### Service projects to runway deployment projects
 
-This is handled by GitLab downstream pipeline triggers. Because of this, all permissions are handled within GitLab itself (and API calls to GitLab use short lived `CI_JOB_TOKEN`). We leverage [CI_JOB_TOKEN allowlists](../../../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-scope-allowlist) to allow deployment projects and service projects to interact in API calls (e.g. updating environments in the service project).
+This is handled by GitLab downstream pipeline triggers. Because of this, all permissions are handled within GitLab itself (and API calls to GitLab use short lived `CI_JOB_TOKEN`). We leverage [CI_JOB_TOKEN allowlists](../../../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) to allow deployment projects and service projects to interact in API calls (e.g. updating environments in the service project).
 
 #### Deployment project to GCP Cloud
 
diff --git a/doc/ci/debugging.md b/doc/ci/debugging.md
index 96dec6a4444cd..35d3891393349 100644
--- a/doc/ci/debugging.md
+++ b/doc/ci/debugging.md
@@ -295,7 +295,7 @@ These errors can happen if the following are both true:
   the private project's allowlist.
 
 To resolve this issue, add any projects with CI/CD jobs that fetch images from the container
-registry to the target project's [job token allowlist](jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token).
+registry to the target project's [job token allowlist](jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist).
 
 These errors might also happen when trying to use a [project access token](../user/project/settings/project_access_tokens.md)
 to access images in another project. Project access tokens are scoped to one project,
diff --git a/doc/ci/git_submodules.md b/doc/ci/git_submodules.md
index d1217808788c2..e6a818cd8b9cd 100644
--- a/doc/ci/git_submodules.md
+++ b/doc/ci/git_submodules.md
@@ -119,7 +119,7 @@ To make submodules work correctly in CI/CD jobs:
 If you use the [`CI_JOB_TOKEN`](jobs/ci_job_token.md) to clone a submodule in a
 pipeline job, the user executing the job must be assigned to a role that has
 [permission](../user/permissions.md#gitlab-cicd-permissions) to trigger a pipeline
-in the upstream submodule project. Additionally, [CI/CD job token access](jobs/ci_job_token.md#configure-cicd-job-token-access) must be properly configured in the upstream submodule project.
+in the upstream submodule project. Additionally, [CI/CD job token access](jobs/ci_job_token.md#control-job-token-access-to-your-project) must be properly configured in the upstream submodule project.
 
 ## Troubleshooting
 
diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md
index a4702c0ef8bfc..134fa0f07d6d1 100644
--- a/doc/ci/jobs/ci_job_token.md
+++ b/doc/ci/jobs/ci_job_token.md
@@ -10,58 +10,55 @@ DETAILS:
 **Tier:** Free, Premium, Ultimate
 **Offering:** SaaS, self-managed
 
-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-build-packages).
-  - [Packages API](../../api/packages.md) (project-level).
-  - [Container registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd)
-    (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`).
-  - [Container registry API](../../api/container_registry.md)
-    (scoped to the job's project).
-- [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
-  to [trigger a multi-project pipeline](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api).
-- [Update pipeline metadata](../../api/pipelines.md#update-pipeline-metadata)
-- [Releases](../../api/releases/index.md) and [Release links](../../api/releases/links.md).
-- [Terraform plan](../../user/infrastructure/index.md).
-- [Deployments](../../api/deployments.md).
-- [Environments](../../api/environments.md).
-
-The token has the same permissions to access the API as the user that caused the
-job to run. A user can cause a job to run by taking action like pushing a commit,
-triggering a manual job, or being the owner of a scheduled 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 cannot
-use the token anymore.
+When a CI/CD pipeline job is about to run, GitLab generates a unique token and makes it available
+to the job as the [`CI_JOB_TOKEN` predefined variable](../variables/predefined_variables.md).
+The token is valid only while the job is running. After the job finishes, the token access
+is revoked and you cannot use the token anymore.
+
+Use a CI/CD job token to authenticate with certain GitLab features from running jobs.
+The token receives the same access level as the user that triggered the pipeline,
+but has access to fewer resources than a personal access token. A user can cause a job to run
+with an action like pushing a commit, triggering a manual job, or being the owner of a scheduled pipeline.
+This user must be have a [role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions)
+to access the resources.
+
+You can use a job token to authenticate with GitLab to access another project's resources (the target project).
+By default, the job token's project must be [added to the target project's allowlist](#add-a-project-to-the-job-token-allowlist).
+
+If a project is public or internal, you can access some features without being on the allowlist.
+For example, you can fetch artifacts from the project's public pipelines.
+This access can also [be restricted](#limit-job-token-scope-for-public-or-internal-projects).
+
+| Feature                                                                                               | Additional details |
+|-------------------------------------------------------------------------------------------------------|--------------------|
+| [Container registry API](../../api/container_registry.md)                                             | The token is scoped to the container registry of the job's project only. |
+| [Container registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) | The `$CI_REGISTRY_PASSWORD` [predefined variable](../variables/predefined_variables.md) is the CI/CD job token. |
+| [Deployments API](../../api/deployments.md)                                                          | `GET` requests are public by default. |
+| [Environments API](../../api/environments.md)                                                        | `GET` requests are public by default. |
+| [Job artifacts API](../../api/job_artifacts.md#get-job-artifacts)                                    | `GET` requests are public by default. |
+| [Jobs API](../../api/jobs.md#get-job-tokens-job)                                                     | To get the job token's job. |
+| [Package registry](../../user/packages/package_registry/index.md#to-build-packages)                  |         |
+| [Packages API](../../api/packages.md)                                                                 | `GET` requests are public by default. |
+| [Pipeline triggers](../../api/pipeline_triggers.md)                                                   | Used with the `token=` parameter to [trigger a multi-project pipeline](../pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api). |
+| [Pipelines API](../../api/pipelines.md#update-pipeline-metadata)                                      | To update pipeline metadata. |
+| [Release links API](../../api/releases/links.md)                                                     |         |
+| [Releases API](../../api/releases/index.md)                                                           | `GET` requests are public by default. |
+| [Terraform plan](../../user/infrastructure/index.md)                                                 |         |
 
 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>
-```
-
-You can't use a job token to push to a repository, but [issue 389060](https://gitlab.com/gitlab-org/gitlab/-/issues/389060) proposes to change this behavior.
+to redesign the feature for more granular control of access permissions.
 
 ## GitLab CI/CD job token security
 
-To prevent the CI/CD job token from leaking, GitLab:
+If a job token is leaked, it could potentially be used to access private data accessible
+to the user that triggered the CI/CD job. To help prevent leaking or misuse of this token,
+GitLab:
 
 - Masks the job token in job logs.
 - Grants permissions to the job token only when the job is running.
 
-To prevent leaking the deploy token, you should also configure your [runners](../runners/index.md)
-to be secure:
+You should also configure your [runners](../runners/index.md) to be secure:
 
 - Avoid using Docker `privileged` mode if the machines are re-used.
 - Avoid using the [`shell` executor](https://docs.gitlab.com/runner/executors/shell.html) when jobs
@@ -70,64 +67,75 @@ to be secure:
 An insecure GitLab Runner configuration increases the risk that someone can steal tokens from other
 jobs.
 
-## Configure CI/CD job token access
+## Control job token access to your project
 
-You can control what projects a CI/CD job token can access to increase the
-job token's security. A job token might give extra permissions that aren't necessary
-to access specific private resources.
+You can control which projects can use a job token to authenticate and access your project's resources.
 
-When enabled, and the job token is being used to access a different project:
+By default, job token access is restricted to only CI/CD jobs that run in pipelines in
+your project. To allow another project to authenticate with a job token from the other
+project's pipeline:
 
-- The user that executes the job must be a member of the project that is being accessed.
+- You must [add the project to the job token allowlist](#add-a-project-to-the-job-token-allowlist).
+- The user that triggers the job must be a member of your project.
 - The user must have the [permissions](../../user/permissions.md) to perform the action.
-- The accessed project must have the project attempting to access it [added to the allowlist](#add-a-project-to-the-job-token-scope-allowlist).
 
-If a job token is leaked, it could potentially be used to access private data
-to the job token's user. By limiting the job token access scope, project data cannot
-be accessed unless projects are explicitly authorized.
+If your project is public or internal, some publicly accessible resources can be accessed
+with a job token from any project. These resources can also be [limited to only projects on the allowlist](#limit-job-token-scope-for-public-or-internal-projects).
 
-There is a proposal to add more strategic control of the access permissions,
-see [epic 3559](https://gitlab.com/groups/gitlab-org/-/epics/3559).
-
-NOTE:
-Because `CI_REGISTRY_PASSWORD` uses `CI_JOB_TOKEN` to authenticate, the access configuration
-also applies to `CI_REGISTRY_PASSWORD`.
-
-### Allow access to your project with a job token
+### Add a project to the job token allowlist
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), enabled by default.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.10.
+> - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
+
+You can add projects to your job token allowlist to allow access your project's resources
+with a job token for authentication. By default, the allowlist of any project only includes itself.
+
+For example, project A can add project B to project A's allowlist. CI/CD jobs
+in project B (the "allowed project") can now use CI/CD job tokens to
+authenticate API calls to access project A.
 
-Create an allowlist of projects which can access your project through
-their `CI_JOB_TOKEN`.
+Add projects to the allowlist only when cross-project access is needed.
 
-For example, project `A` can add project `B` to the allowlist. CI/CD jobs
-in project `B` (the "allowed project") can now use their CI/CD job token to
-authenticate API calls to access project `A`.
+Prerequisites:
+
+- You must have at least the Maintainer role in the current project. If the allowed project
+  is internal or private, you must have at least the Guest role in that project.
+- You must not have more than 200 projects added to the allowlist.
+
+To add a project to the allowlist:
 
-By default, the allowlist of any project only includes itself.
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Settings > CI/CD**.
+1. Expand **Token Access**.
+1. Ensure the **Limit access _to_ this project** toggle is enabled. Enabled by default in new projects.
+   It is a security risk to disable this feature, so project maintainers or owners should
+   keep this setting enabled at all times.
+1. Select **Add project**.
+1. Input the path to the project to add to the allowlist, and select **Add project**.
 
-It is a security risk to disable this feature, so project maintainers or owners should
-keep this setting enabled at all times. Add projects to the allowlist only when cross-project
-access is needed.
+You can also add a project to the allowlist [with the API](../../api/graphql/reference/index.md#mutationcijobtokenscopeaddproject).
 
 ### Limit job token scope for public or internal projects
 
-Projects can use a job token to authenticate with public or internal projects for
-the following actions without being added to the allowlist:
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/405369) in GitLab 16.6.
 
-- Fetch artifacts
-- Access the container registry
-- Access the package registry
-- Access releases, deployments, and environments
+Projects not in the allowlist can use a job token to authenticate with public or internal projects to:
 
-To limit access to these actions to only the projects on the allowlist, set the visibility
-of each feature to be only accessible to project members:
+- Fetch artifacts.
+- Access the container registry.
+- Access the package registry.
+- Access releases, deployments, and environments.
+
+You can limit access to these actions to only the projects on the allowlist by setting
+each feature to be only visible to project members.
 
 Prerequisites:
 
 - You must have the Maintainer role for the project.
 
+To set a feature to be only visible to project members:
+
 1. On the left sidebar, select **Search or go to** and find your project.
 1. Select **Settings > General**.
 1. Expand **Visibility, project features, permissions**.
@@ -135,19 +143,21 @@ Prerequisites:
    - The ability to fetch artifacts is controlled by the CI/CD visibility setting.
 1. Select **Save changes**.
 
-Triggering pipelines and fetching Terraform plans is not affected by feature visibility.
-
-### Disable the job token scope allowlist
+### Allow any project to access your project
 
 > - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
 
 WARNING:
-It is a security risk to disable the allowlist. A malicious user could try to compromise
+It is a security risk to disable the token access limit and allowlist. A malicious user could try to compromise
 a pipeline created in an unauthorized project. If the pipeline was created by one of
 your maintainers, the job token could be used in an attempt to access your project.
 
-You can disable the job token scope allowlist for testing or a similar reason,
-but you should enable it again as soon as possible.
+If you disable the **Limit access _to_ this project** setting, the allowlist is ignored.
+Jobs from any project could access your project with a job token if the user that
+triggers the pipeline has permission to access your project.
+
+You should only disable this setting for testing or a similar reason,
+and you should enable it again as soon as possible.
 
 Prerequisites:
 
@@ -161,41 +171,31 @@ To disable the job token scope allowlist:
 1. Toggle **Limit access _to_ this project** to disabled.
    Enabled by default in new projects.
 
-You can also disable the allowlist [with the API](../../api/graphql/reference/index.md#mutationprojectcicdsettingsupdate).
-
-### Add a project to the job token scope allowlist
-
-> - **Allow access to this project with a CI_JOB_TOKEN** setting [renamed to **Limit access _to_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
-
-You can add projects to the allowlist for a project. Projects added to the allowlist
-can make API calls from running pipelines by using the CI/CD job token.
-
-Prerequisites:
+You can also enable and disable the setting [with the API](../../api/graphql/reference/index.md#mutationprojectcicdsettingsupdate).
 
-- You must have at least the Maintainer role in the current project. If the allowed project
-  is internal or private, you must have at least the Guest role in that project.
-- You must not have more than 200 projects added to the allowlist.
+## Use a job token to clone a private project's repository
 
-To add a project:
+You can use the job token to authenticate and clone a repository from a private project
+in a CI/CD job. For example:
 
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Settings > CI/CD**.
-1. Expand **Token Access**.
-1. Verify **Limit access _to_ this project** is enabled.
-1. Under **Allow CI job tokens from the following projects to access this project**,
-   add projects to the allowlist.
+```shell
+git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>
+```
 
-You can also add a target project to the allowlist [with the API](../../api/graphql/reference/index.md#mutationcijobtokenscopeaddproject).
+You can't use a job token to push to a repository, but [issue 389060](https://gitlab.com/gitlab-org/gitlab/-/issues/389060)
+proposes to change this behavior.
 
-### Limit your project's job token access
+## Limit your project's job token access (deprecated)
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. [Deployed behind the `:ci_scoped_job_token` feature flag](../../user/feature_flags.md), disabled by default.
 > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.4.
 > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.6.
 
 NOTE:
-This feature is disabled by default for all new projects and is [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/383084)
-in GitLab 17.0. Project maintainers or owners should enable the access control instead.
+The [**Limit access _from_ this project**](#configure-the-job-token-scope-deprecated)
+setting is disabled by default for all new projects and is [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/383084)
+in GitLab 17.0. Project maintainers or owners should configure the [**Limit access _to_ this project**](#add-a-project-to-the-job-token-allowlist)
+setting instead.
 
 Control your project's job token scope by creating an allowlist of projects which
 can be accessed by your project's job token.
@@ -210,7 +210,7 @@ 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 project `B`, then `B` must be added to the allowlist for `A`.
 
-### Configure the job token scope
+### Configure the job token scope (deprecated)
 
 > - **Limit CI_JOB_TOKEN access** setting [renamed to **Limit access _from_ this project**](https://gitlab.com/gitlab-org/gitlab/-/issues/411406) in GitLab 16.3.
 
@@ -227,24 +227,6 @@ To configure the job token scope:
 1. Optional. Add existing projects to the token's access scope. The user adding a
    project must have the Maintainer role in both projects.
 
-## Download an artifact from a different pipeline
-
-DETAILS:
-**Tier:** Premium, Ultimate
-**Offering:** SaaS, self-managed
-
-You can use the CI/CD job token to authenticate with the [jobs artifacts API endpoint](../../api/job_artifacts.md)
-and fetch artifacts from a different pipeline. You must specify which job to retrieve 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
-```
-
 ## Troubleshooting
 
 CI job token failures are usually shown as responses like `404 Not Found` or similar:
diff --git a/doc/ci/jobs/job_artifacts.md b/doc/ci/jobs/job_artifacts.md
index bb9d6d5bee25d..14d9bf801ec56 100644
--- a/doc/ci/jobs/job_artifacts.md
+++ b/doc/ci/jobs/job_artifacts.md
@@ -256,6 +256,25 @@ Artifacts for [parent and child pipelines](../pipelines/downstream_pipelines.md#
 are searched in hierarchical order from parent to child. For example, if both parent and
 child pipelines have a job with the same name, the job artifacts from the parent pipeline are returned.
 
+### With a CI/CD job token
+
+DETAILS:
+**Tier:** Premium, Ultimate
+**Offering:** SaaS, self-managed
+
+You can use a [CI/CD job token](ci_job_token.md) to authenticate with the [jobs artifacts API endpoint](../../api/job_artifacts.md)
+and fetch artifacts from a different pipeline. You must specify which job to retrieve artifacts from,
+for example:
+
+```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
+```
+
 ## Browse the contents of the artifacts archive
 
 You can browse the contents of the artifacts from the UI without downloading the artifact locally,
diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md
index 354ae003d504c..e101155a13e88 100644
--- a/doc/ci/pipelines/downstream_pipelines.md
+++ b/doc/ci/pipelines/downstream_pipelines.md
@@ -446,7 +446,7 @@ upstream pipeline:
 Use [`needs:project`](../yaml/index.md#needsproject) to fetch artifacts from an
 upstream pipeline:
 
-1. In GitLab 15.9 and later, [add the downstream project to the job token scope allowlist](../jobs/ci_job_token.md#add-a-project-to-the-job-token-scope-allowlist) of the upstream project.
+1. In GitLab 15.9 and later, [add the downstream project to the job token scope allowlist](../jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) of the upstream project.
 1. In the upstream pipeline, save the artifacts in a job with the [`artifacts`](../yaml/index.md#artifacts)
    keyword, then trigger the downstream pipeline with a trigger job:
 
@@ -499,7 +499,7 @@ because the downstream pipeline attempts to fetch artifacts from the latest bran
 To fetch the artifacts from the upstream `merge request` pipeline instead of the `branch` pipeline,
 pass `CI_MERGE_REQUEST_REF_PATH` to the downstream pipeline using [variable inheritance](#pass-yaml-defined-cicd-variables):
 
-1. In GitLab 15.9 and later, [add the downstream project to the job token scope allowlist](../jobs/ci_job_token.md#add-a-project-to-the-job-token-scope-allowlist) of the upstream project.
+1. In GitLab 15.9 and later, [add the downstream project to the job token scope allowlist](../jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) of the upstream project.
 1. In a job in the upstream pipeline, save the artifacts using the [`artifacts`](../yaml/index.md#artifacts) keyword.
 1. In the job that triggers the downstream pipeline, pass the `$CI_MERGE_REQUEST_REF_PATH` variable:
 
@@ -843,4 +843,4 @@ Only trigger multi-project pipelines with tag names that do not match branch nam
 
 In GitLab 15.9 and later, CI/CD job tokens are scoped to the project that the pipeline executes under. Therefore, the job token in a downstream pipeline cannot be used to access an upstream project by default.
 
-To resolve this, [add the downstream project to the job token scope allowlist](../jobs/ci_job_token.md#add-a-project-to-the-job-token-scope-allowlist).
+To resolve this, [add the downstream project to the job token scope allowlist](../jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist).
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index 745d318c82ec5..81958f04e71f0 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -233,7 +233,7 @@ From GitLab 18.0 and later, the runner registration methods implemented by the n
 
 The `direction` GraphQL argument for the `ciJobTokenScopeRemoveProject` mutation is deprecated. Following the [default CI/CD job token scope change](https://docs.gitlab.com/ee/update/deprecations.html#default-cicd-job-token-ci_job_token-scope-changed) announced in GitLab 15.9, the `direction` argument will default to `INBOUND` and `OUTBOUND` will no longer be valid in GitLab 17.0. We will remove the `direction` argument in GitLab 18.0.
 
-If you are using `OUTBOUND` with the `direction` argument to control the direction of your project's token access, your pipeline that use job tokens risk failing authentication. To ensure pipelines continue to run as expected, you will need to explicitly [add the other projects to your project's allowlist](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-scope-allowlist).
+If you are using `OUTBOUND` with the `direction` argument to control the direction of your project's token access, your pipeline that use job tokens risk failing authentication. To ensure pipelines continue to run as expected, you will need to explicitly [add the other projects to your project's allowlist](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist).
 
 </div>
 
@@ -407,7 +407,7 @@ These three variables will be removed in GitLab 17.0.
 
 In GitLab 14.4 we introduced the ability to [limit your project's CI/CD job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#limit-your-projects-job-token-access) (`CI_JOB_TOKEN`) access to make it more secure. You can prevent job tokens **from your project's** pipelines from being used to **access other projects**. When enabled with no other configuration, your pipelines cannot access other projects. To use the job token to access other projects from your pipeline, you must list those projects explicitly in the **Limit CI_JOB_TOKEN access** setting's allowlist, and you must be a maintainer in all the projects.
 
-The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#allow-access-to-your-project-with-a-job-token). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
+The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
 
 The **Limit** setting was deprecated in 16.0 in preference of the better **Allow access** setting and **Limit** setting was disabled by default for all new projects. From this point forward, if the **Limit** setting is disabled in any project, it will not be possible to re-enable this setting in 16.0 or later.
 
@@ -1858,7 +1858,7 @@ Any API calls to change the rate limits for `user_email_lookup_limit` must use `
 - To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/420678).
 </div>
 
-Starting in 16.6, projects that are **public** or **internal** will no longer authorize job token requests from projects that are **not** on the project's allowlist when [**Limit access to this project**](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#allow-access-to-your-project-with-a-job-token) is enabled.
+Starting in 16.6, projects that are **public** or **internal** will no longer authorize job token requests from projects that are **not** on the project's allowlist when [**Limit access to this project**](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist) is enabled.
 
 If you have [public or internal](https://docs.gitlab.com/ee/user/public_access.html#change-project-visibility) projects with the **Limit access to this project** setting enabled, you must add any projects which make job token requests to your project's allowlist for continued authorization.
 
@@ -2308,7 +2308,7 @@ These three variables will be removed in GitLab 16.0.
 
 In GitLab 14.4 we introduced the ability to [limit your project's CI/CD job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#limit-your-projects-job-token-access) (`CI_JOB_TOKEN`) access to make it more secure. You can prevent job tokens **from your project's** pipelines from being used to **access other projects**. When enabled with no other configuration, your pipelines cannot access other projects. To use the job token to access other projects from your pipeline, you must list those projects explicitly in the **Limit CI_JOB_TOKEN access** setting's allowlist, and you must be a maintainer in all the projects.
 
-The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#allow-access-to-your-project-with-a-job-token). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
+The job token functionality was updated in 15.9 with a better security setting to [allow access to your project with a job token](https://docs.gitlab.com/ee/ci/jobs/ci_job_token.html#add-a-project-to-the-job-token-allowlist). When enabled with no other configuration, job tokens **from other projects** cannot **access your project**. Similar to the older setting, you can optionally allow other projects to access your project with a job token if you list those projects explicitly in the **Allow access to this project with a CI_JOB_TOKEN** setting's allowlist. With this new setting, you must be a maintainer in your own project, but only need to have the Guest role in the other projects.
 
 As a result, the **Limit** setting is deprecated in preference of the better **Allow access** setting. In GitLab 16.0 the **Limit** setting will be disabled by default for all new projects. In projects with this setting currently enabled, it will continue to function as expected, but you will not be able to add any more projects to the allowlist. If the setting is disabled in any project, it will not be possible to re-enable this setting in 16.0 or later.
 
diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md
index 95c9e02026089..262ff02199486 100644
--- a/doc/user/packages/workflows/project_registry.md
+++ b/doc/user/packages/workflows/project_registry.md
@@ -45,7 +45,7 @@ Let's take a look at how you might create one project to host all of your packag
    - A [personal access token](../../profile/personal_access_tokens.md).
    - A [CI/CD job token](../../../ci/jobs/ci_job_token.md) (`CI_JOB_TOKEN`) in a CI/CD job.
      Any projects publishing packages to this project's registry should be listed
-     in this project's [job token allowlist](../../../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token).
+     in this project's [job token allowlist](../../../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist).
 
    If the project is private, downloading packages requires authentication as well.
 
-- 
GitLab