diff --git a/doc/api/project_job_token_scopes.md b/doc/api/project_job_token_scopes.md index 3c6a53cbddb91fb8d8002de2603ed22a155b1e40..761820784c4cbdc600b6aacbdb5b944a972c72a1 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 98d9e7548819c737cb1c06a7cd236ba606b8da16..2313d953335dba96a18962d7139ef630d066688c 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 681141e78746ba62c4f3a64ed624ec94869ddeee..d78c6163573c72140bb45842135b8c41b6b80b20 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 685967eb8c81807e3913ef6cdf13b7811a9311b9..caa3402985407cae2395bae63136e75aa14eaa73 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. @@ -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,10 +112,10 @@ 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). +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 @@ -190,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 2243e5547576f77185aef251e2a4156a21f34dd7..3450902756dff01ce15fc9221a11d1638a2b4a22 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 2678e92ed566fbac4b80c9a6f77b2c4270bb6181..2d1aa1d369a6d506b371c6fc538081f5aceab0c2 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-a-group-or-project-to-the-job-token-allowlist). If the project is private, downloading packages requires authentication as well.