From 5cbf9700ed8ee4f0b9bcab9350248e56837ecb0a Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Wed, 8 May 2024 18:01:06 -0400 Subject: [PATCH 1/4] Updates CI/CD job token docs --- doc/ci/jobs/ci_job_token.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 685967eb8c8180..5ece61ad32acd1 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -69,41 +69,42 @@ jobs. ## Control job token access to your project -You can control which projects can use a job token to authenticate and access your project's resources. +You can control which groups or projects can use a job token to authenticate and access your project's resources. 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 +your project. To allow another group or project to authenticate with a job token from the other project's pipeline: -- You must [add the project to the job token allowlist](#add-a-project-to-the-job-token-allowlist). +- You must [add the group or project to the job token allowlist](#add-a-group-or-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. 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). -### Add a project to the job token allowlist +### Add a group or 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. +> - Adding groups to the job token allowlist [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415519) in GitLab 17.0. -You can add projects to your job token allowlist to allow access your project's resources +You can add groups or 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. -Add projects to the allowlist only when cross-project access is needed. +Add groups or projects to the allowlist only when cross-project access is needed. 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. +- You must not have more than 200 groups and projects added to the allowlist. -To add a project to the allowlist: +To add a group or project to the allowlist: 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Settings > CI/CD**. @@ -111,8 +112,8 @@ To add a project to the allowlist: 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**. +1. Select **Add group or project**. +1. Input the path to the group or project to add to the allowlist, and select **Add project**. You can also add a project to the allowlist [with the API](../../api/graphql/reference/index.md#mutationcijobtokenscopeaddproject). -- GitLab From be250f79989358ad12347bb134dbf05c35447a4a Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Wed, 8 May 2024 18:49:00 -0400 Subject: [PATCH 2/4] Updates link references --- doc/api/project_job_token_scopes.md | 12 ++++++------ doc/architecture/blueprints/runway/index.md | 2 +- doc/ci/debugging.md | 2 +- doc/ci/jobs/ci_job_token.md | 6 +++--- doc/ci/pipelines/downstream_pipelines.md | 6 +++--- doc/user/packages/workflows/project_registry.md | 2 +- 6 files changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/api/project_job_token_scopes.md b/doc/api/project_job_token_scopes.md index 3c6a53cbddb91f..761820784c4cbd 100644 --- a/doc/api/project_job_token_scopes.md +++ b/doc/api/project_job_token_scopes.md @@ -34,7 +34,7 @@ If successful, returns [`200`](rest/index.md#status-codes) and the following res | Attribute | Type | Description | |--------------------|---------|-------------| -| `inbound_enabled` | boolean | Indicates if the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) is enabled. | +| `inbound_enabled` | boolean | Indicates if the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#add-a-group-or-project-to-the-job-token-allowlist) is enabled. | | `outbound_enabled` | boolean | Indicates if the CI/CD job token generated in this project has access to other projects. [Deprecated and planned for removal in GitLab 18.0](../update/deprecations.md#default-cicd-job-token-ci_job_token-scope-changed). | Example request: @@ -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#add-a-project-to-the-job-token-allowlist) (job token scope) of a project. +Patch the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#add-a-group-or-project-to-the-job-token-allowlist) (job token scope) of a project. ```plaintext PATCH /projects/:id/job_token_scope @@ -67,7 +67,7 @@ Supported attributes: | Attribute | Type | Required | Description | |-----------|----------------|----------|-------------| | `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | -| `enabled` | boolean | Yes | Indicates if the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#add-a-project-to-the-job-token-allowlist) should be enabled. | +| `enabled` | boolean | Yes | Indicates if the [**Limit access _to_ this project** setting](../ci/jobs/ci_job_token.md#add-a-group-or-project-to-the-job-token-allowlist) should be enabled. | If successful, returns [`204`](rest/index.md#status-codes) and no response body. @@ -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#add-a-project-to-the-job-token-allowlist) (job token scope) of a project. +Fetch the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#add-a-group-or-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#add-a-project-to-the-job-token-allowlist) of a project. +Add a project to the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#add-a-group-or-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#add-a-project-to-the-job-token-allowlist) of a project. +Remove a project from the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#add-a-group-or-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 98d9e7548819c7..2313d953335dba 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-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-group-or-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 681141e78746ba..d78c6163573c72 100644 --- a/doc/ci/debugging.md +++ b/doc/ci/debugging.md @@ -462,7 +462,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#add-a-project-to-the-job-token-allowlist). +registry to the target project's [job token allowlist](jobs/ci_job_token.md#add-a-group-or-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/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 5ece61ad32acd1..5ff451154e7c5c 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -22,8 +22,8 @@ with an action like pushing a commit, triggering a manual job, or being the owne This user must 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). +You can use a job token to authenticate with GitLab to access another group or project's resources (the target project). +By default, the job token's group or project must be [added to the target project's allowlist](#add-a-group-or-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. @@ -191,7 +191,7 @@ proposes to change this behavior. NOTE: 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) +in GitLab 17.0. Project maintainers or owners should configure the [**Limit access _to_ this project**](#add-a-group-or-project-to-the-job-token-allowlist) setting instead. Control your project's job token scope by creating an allowlist of projects which diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 2243e5547576f7..3450902756dff0 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -491,7 +491,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-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-group-or-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: @@ -544,7 +544,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-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-group-or-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: @@ -888,4 +888,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-allowlist). +To resolve this, [add the downstream project to the job token scope allowlist](../jobs/ci_job_token.md#add-a-group-or-project-to-the-job-token-allowlist). diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 2678e92ed566fb..56a209df0c4c75 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#add-a-project-to-the-job-token-allowlist). + in this project's [job token allowlist](../../../ci/jobs/ci_job_token.md#add-agroup-or-project-to-the-job-token-allowlist). If the project is private, downloading packages requires authentication as well. -- GitLab From 8e70e0d214bb1ab7a13f02c4ebc4bfb3cc20b7e1 Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Wed, 8 May 2024 19:11:47 -0400 Subject: [PATCH 3/4] Fix link typo --- doc/user/packages/workflows/project_registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md index 56a209df0c4c75..2d1aa1d369a6d5 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#add-agroup-or-project-to-the-job-token-allowlist). + in this project's [job token allowlist](../../../ci/jobs/ci_job_token.md#add-a-group-or-project-to-the-job-token-allowlist). If the project is private, downloading packages requires authentication as well. -- GitLab From f62afd9ab4aeca9df4078bfb980c65b18ed9e198 Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Thu, 9 May 2024 18:50:37 +0000 Subject: [PATCH 4/4] Adds review feedback --- doc/ci/jobs/ci_job_token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 5ff451154e7c5c..caa3402985407c 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -115,7 +115,7 @@ To add a group or project to the allowlist: 1. Select **Add group or project**. 1. Input the path to the group or project to add to the allowlist, and select **Add project**. -You can also add a project to the allowlist [with the API](../../api/graphql/reference/index.md#mutationcijobtokenscopeaddproject). +You can also add a group or project to the allowlist [with the API](../../api/graphql/reference/index.md#mutationcijobtokenscopeaddgrouporproject). ### Limit job token scope for public or internal projects -- GitLab