diff options
Diffstat (limited to 'doc/ci/jobs/ci_job_token.md')
| -rw-r--r-- | doc/ci/jobs/ci_job_token.md | 41 |
1 files changed, 24 insertions, 17 deletions
diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index db916d8d125..3f1c72c2bd6 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -12,7 +12,7 @@ When a pipeline job is about to run, GitLab generates a unique token and injects You can use a GitLab CI/CD job token to authenticate with specific API endpoints: - Packages: - - [Package Registry](../../user/packages/package_registry/index.md#use-gitlab-cicd-to-build-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`). @@ -30,7 +30,7 @@ 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 can't +The token is valid only while the pipeline job runs. After the job finishes, you cannot use the token anymore. A job token can access a project's resources without any configuration, but it might @@ -76,39 +76,44 @@ be accessed unless projects are explicitly authorized. 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_TOKEN` uses `CI_JOB_TOKEN` to authenticate, the access configuration +also applies to `CI_REGISTRY_TOKEN`. + ### Allow access to your project with a job token -> [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. +> - [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. -Create an **inbound** allowlist of projects which can access your project through +Create an allowlist of projects which can access your project through their `CI_JOB_TOKEN`. -For example, project `A` can add project `B` to the inbound allowlist. CI/CD jobs +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`. If project `A` is public or internal, -the project can be accessed by project `B` without adding it to the inbound allowlist. +the project can be accessed by project `B` without adding it to the allowlist. -By default the inbound allowlist of any project only includes itself. +By default, the allowlist of any project only includes itself. 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. -### Disable the inbound job token scope allowlist +### Disable the job token scope allowlist WARNING: It is a security risk to disable the 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 inbound job token scope allowlist for testing or a similar reason, +You can disable the job token scope allowlist for testing or a similar reason, but you should enable it again as soon as possible. Prerequisite: - You must have at least the Maintainer role for the project. -To disable the inbound job token scope allowlist: +To disable the job token scope allowlist: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -118,9 +123,9 @@ To disable the inbound job token scope allowlist: You can also disable the allowlist [with the API](../../api/graphql/reference/index.md#mutationprojectcicdsettingsupdate). -### Add a project to the inbound job token scope allowlist +### Add a project to the job token scope allowlist -You can add projects to the inbound allowlist for a project. Projects added to the allowlist +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. Prerequisite: @@ -148,9 +153,9 @@ You can also add a target project to the allowlist [with the API](../../api/grap 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 16.0. Project maintainers or owners should enable the **inbound** access control instead. +in GitLab 16.0. Project maintainers or owners should enable the access control instead. -Control your project's job token scope by creating an **outbound** allowlist of projects which +Control your project's job token scope by creating an allowlist of projects which can be accessed by your project's job token. By default, the allowlist includes your current project. @@ -165,13 +170,13 @@ to make an API request to a private project `B`, then `B` must be added to the a If project `B` is public or internal, you do not need to add `B` to the allowlist to grant access. -### Configure the outbound job token scope +### Configure the job token scope Prerequisite: - You must not have more than 100 projects added to the token's scope. -To configure the outbound job token scope: +To configure the job token scope: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -237,10 +242,12 @@ CI job token failures are usually shown as responses like `404 Not Found` or sim While troubleshooting CI/CD job token authentication issues, be aware that: +- A [GraphQL example mutation](../../api/graphql/getting_started.md#update-project-settings) + is available to toggle the scope settings per project. - When the [CI/CD job token scopes](#configure-cicd-job-token-access) are enabled, and the job token is being used to access a different project: - The user that executes the job must be a member of the project that is being accessed. - 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 inbound allowlist](#add-a-project-to-the-inbound-job-token-scope-allowlist). + - The accessed project must have the project attempting to access it [added to the allowlist](#add-a-project-to-the-job-token-scope-allowlist). - The CI job token becomes invalid if the job is no longer running, has been erased, or if the project is in the process of being deleted. |