skip to content

In GitLab, a job in one project gets 404 Not Found using CI_JOB_TOKEN against another private project; what decides whether that call is allowed?

level: middleimportance: must knowfreq 36%

answer

  1. a token that dies with the job
  2. access of whoever started the pipeline
  3. the list lives on the target
  4. add the calling group or project
  5. only some REST endpoints accept it

basics

~20 s

A CI_JOB_TOKEN call into another GitLab project succeeds only if the target project's job token allowlist names the calling project or its group, the user who started the job has enough access in the target, and the endpoint accepts job tokens.

solid answer

~50 s

GitLab creates `CI_JOB_TOKEN` for each job; it is valid only while the job runs and carries the access level of the user who triggered the pipeline (for a schedule, its owner). Reaching another project needs three things: the **target** project's **CI/CD job token allowlist** must name the calling project or a group containing it (an entry only a Maintainer or Owner of the target can add); that user must be a member of the target with permission for the action, because the allowlist grants nothing by itself; and the endpoint must be one job tokens may use — a fixed set of REST endpoints, HTTPS Git clone as `gitlab-ci-token`, and the registries, but never GraphQL. Failures usually surface as `404 Not Found`. Since GitLab 18.0 the allowlist is enforced by default, so cross-project calls that once worked without an entry now need one.

code

bash · 7 lines
bash
# Runs in a job of acme/web; reads from the private project acme/shared-config
# SHARED_CONFIG_ID is a CI/CD variable you define with that project's numeric ID
curl --fail --header "JOB-TOKEN: $CI_JOB_TOKEN" \
  "$CI_API_V4_URL/projects/$SHARED_CONFIG_ID/repository/files/settings.json/raw"

# Clone the same project over HTTPS: user gitlab-ci-token, password the job token
git clone "https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/acme/shared-config.git"

go deeper

for a junior

Know that CI_JOB_TOKEN is a short-lived token GitLab gives each job, and that using it against another project needs that project's permission.

for a middle

Explain the three conditions for a cross-project call: the target's allowlist, the triggering user's own access, and an endpoint that accepts job tokens.

for a senior

Show how you would replace personal tokens in inherited pipelines with job tokens, using the authentication log to fill allowlists before relying on enforcement.

for a principal

Weigh group-wide allowlist entries against per-project ones, and decide how much cross-project reach, including job token pushes, an organisation should permit.

## What the job token is When a GitLab job is about to run, GitLab generates a unique token and exposes it to the job as the predefined variable `CI_JOB_TOKEN`. Three properties define it: - **Short-lived.** It is valid only while the job runs; when the job finishes (or is erased, or its project is being deleted) the token stops working. It is masked in job logs. - **Borrowed identity.** It gets the **same access level as the user who triggered the pipeline** — whoever pushed the commit, started a manual job, or owns the pipeline schedule. - **Narrow reach.** Even with that user's access, it can use fewer resources than a personal access token: a fixed list of REST API endpoints, HTTPS Git clone, and the project's container and package registries. Since **GitLab 19.0** the token is a JWT by default; a top-level group can switch back to the legacy format with **Enable JWT format for CI/CD job tokens** until 20.0. Scripts that pipe it through `base64` need `base64 -w0`, because the longer token gets wrapped. ## The three conditions for a cross-project call A job in project B calling project A succeeds only when all of these hold: 1. **A's allowlist names B**, or a group that contains B. The entry lives on the **target**, and adding it needs the Maintainer or Owner role in A. 2. **The triggering user is a member of A** with the permission the action needs. The allowlist adds no permissions to anyone; it only lets the token be used. 3. **The endpoint accepts job tokens.** Reading a file through the raw files endpoint, listing branches or tags, downloading job artifacts, using the packages and releases APIs are allowed; GraphQL is not. Failures rarely say which condition broke: an unauthorised clone, package download or API call usually answers `404 Not Found`, as if the project could not be found at all. ## The allowlist in detail | Entry | Effect | |---|---| | The project itself | always present; the default allowlist contains only this | | Another project | that project's jobs may use their tokens here | | A group | every project in the group and its subgroups at any depth, including projects created later | - An allowlist holds up to **200 groups and 200 projects**, counted separately. - **Public and internal** projects let non-allowlisted jobs fetch artifacts, use the registries, read releases, deployments, environments and the repository, unless those features are set to **Only project members**. - On GitLab Self-Managed and Dedicated, a Maintainer can select **All groups and projects** to switch the allowlist off, only when the administrator has not turned on **Enable and enforce job token allowlist for all projects**. That instance setting has been on by default since **18.0** on every offering. - Pushing is separate: **Allow Git push requests to the repository** lets the project's own jobs push, and since **19.1** **Allow cross-project Git push requests from allowlisted projects** extends that to allowlisted sources. A job token push triggers no pipeline. ## Replacing personal tokens in inherited pipelines Pipelines that call each other with personal access tokens carry a long-lived credential tied to one person. Moving them to job tokens: 1. Read each target project's **authentication log** (17.6 and later) to see which projects already authenticate with job tokens. 2. Add those projects, or their group, to the **target's** allowlist. 3. Check that the people who trigger the calling pipelines are members of the target with the right role; a schedule's owner counts here. 4. Replace the personal token in scripts with the `JOB-TOKEN` header or the `gitlab-ci-token` Git user, then revoke the personal token. 5. Keep the allowlist enforced; prefer project entries over broad group entries when only one caller needs access. ## What changed across releases | Release | Change | |---|---| | 15.9 | allowlist introduced and on for new projects; older projects could stay open | | 17.0 | groups can be added to the allowlist; the old outbound direction is no longer valid | | 17.6 | authentication log; administrators can enforce the allowlist | | 18.0 | enforcement of the allowlist on by default | | 19.0 | JWT format by default | | 19.1 | cross-project push from allowlisted projects generally available | Advice written before 18.0 that says "job tokens work against any project the user can see" describes a setup that no longer exists by default.

  • In GitLab, on which project do you add the entry so project B's jobs can use their job token against project A?
    On project A, the one being accessed. A Maintainer or Owner of A adds B, or a group containing B, to A's **CI/CD job token allowlist** under its job token permissions. Nothing is configured on B. A group entry covers every project in the group and its subgroups, including projects created later.
  • Before tightening job token access in GitLab, how do you find out which projects already use it against yours?
    Read the project's job token **authentication log**, added in 17.6, under its job token permissions. It lists other projects that authenticated with a job token, shows up to 100 events in the page, offers the full history as a CSV download, and can lag new authentications by up to five minutes.
  • In GitLab 19.4, can a job push to another project's repository with CI_JOB_TOKEN?
    Yes, since 19.1, if the target enables **Allow Git push requests to the repository** and **Allow cross-project Git push requests from allowlisted projects**, keeps its allowlist on with the source project (or its group) listed with default or `admin_repositories` permissions, and the user who started the pipeline has at least the Developer role there. Such a push triggers no pipeline in the target.

  • The allowlist sits on the calling project and lists where its jobs may go.
  • Adding a project to the allowlist gives its members access to your project.
  • A job token keeps working after the job finishes, like a personal access token.
  • The job token has fixed permissions of its own, whoever triggered the pipeline.
  • A job token can authenticate GraphQL API requests as well as REST ones.

Assumes GitLab 19.4: allowlist enforcement became the default in 18.0, job tokens use the JWT format by default since 19.0 (legacy format available until 20.0), and cross-project Git push from allowlisted projects is generally available since 19.1.