Researched guidance: How should GitLab CI job tokens be checked for cross-project repository access?

Summary

Check cross-project CI_JOB_TOKEN repository access as a target-project authorization decision: source project allowlist match, triggering-user permissions, requested repository operation, and (when enabled) fine-grained repository permissions. Test with a repository GET using the recommended JOB-TOKEN header while the job is running.

Candidate action

1. Identify the source project that owns the running pipeline, the target project/repository, the exact operation (clone, repository-file API read, archive/tags/branches read, or push), and the user who triggered the pipeline; never print CI_JOB_TOKEN. 2. On the target project, inspect Settings > CI/CD > Job token permissions and confirm the source project, or a group that contains it, is in the CI/CD job token allowlist; the REST API can inspect the scope and allowlist with GET /projects/:id/job_token_scope and GET /projects/:id/job_token_scope/allowlist. A target-project allowlist entry is inbound: Project B must allowlist Project A when A’s pipeline token accesses B. 3. Confirm the triggering user is a member of the target project and has the permission required for the requested action; allowlisting does not grant permissions. 4. For REST repository reads, use a documented endpoint such as GET /projects/:id/repository/files/:file_path/raw and send JOB-TOKEN: $CI_JOB_TOKEN. If fine-grained permissions are enabled for the allowlist entry, grant READ_REPOSITORIES; verify that the endpoint is covered before testing another operation. 5. For a private repository clone, use the documented gitlab-ci-token username with CI_JOB_TOKEN as the password, over the same GitLab instance; for a different GitLab instance, use a token created on that instance instead. 6. For cross-project pushes, additionally verify that the target enables Allow Git push requests to the repository and Allow cross-project Git push requests from allowlisted projects, the source is allowlisted with default permissions or the required repository-admin permission, and the triggering user has at least Developer on the target. 7. Treat public/internal visibility as an exception, not proof of intended authorization: projects outside the allowlist may reach some repository resources unless the target feature visibility is Only project members. Check whether the instance enforces the job-token allowlist, because that can override the project toggle. Record the exact target, source, operation, allowlist match, fine-grained permission state, triggering-user role, and response without recording the token.

Applicability

• GitLab CI/CD jobs using CI_JOB_TOKEN to access another project on the same GitLab instance.
• Repository clone and documented repository REST reads, including raw files, branches, commits, tags, archives, and changelog; cross-project push requires the separate opt-in settings described by GitLab.
• GitLab versions and installations exposing the current CI/CD job token allowlist and optional fine-grained job-token permissions; account for renamed UI labels and instance-level enforcement.

Key findings

• By default, the target project must allowlist the source project or its group; the allowlist does not grant permissions, and the user who triggers the pipeline must be a target-project member with permission for the action. (S1)
• For repository REST reads, GitLab documents GET /projects/:id/repository/files/:file_path/raw and related repository GET endpoints for CI/CD job tokens; fine-grained access uses READ_REPOSITORIES. (S1, S2)
• The recommended REST authentication form is the JOB-TOKEN header with CI_JOB_TOKEN; query-string token transport is not recommended. (S3, S1)
• The target project’s job-token scope and allowlist can be inspected through GET /projects/:id/job_token_scope and GET /projects/:id/job_token_scope/allowlist; adding an allowlist project uses POST /projects/:id/job_token_scope/allowlist, subject to Maintainer/Owner authorization and instance enforcement. (S4)
• Cross-project Git push is a separate opt-in: target settings must allow Git pushes and cross-project pushes from allowlisted projects, and the triggering user must have at least Developer on the target. (S1)

Known limitations

• A job-token allowlist match alone is insufficient: the triggering user’s membership and action permission still control access.
• Fine-grained permissions are endpoint-specific. READ_REPOSITORIES covers documented repository read endpoints, but this research does not establish permissions for an unlisted endpoint or a custom GitLab extension.
• Public or internal visibility can permit some access outside the allowlist unless feature visibility is restricted to Only project members, so an observed success may not prove an allowlist match.
• The REST scope API requires an authenticated user with Maintainer or Owner on the target project; instance enforcement may force the allowlist on and can override the project enabled setting.
• Documentation research only: no GitLab instance, pipeline, clone, API request, or push was executed and no independent reproduction was performed.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• Official GitLab documentation establishes configuration and documented authentication paths, not a passing result for a particular source/target project pair.

What remains unknown

• Whether the affected source project is actually present in the target project’s allowlist directly or through a group entry, and whether the target allowlist is enforced by the instance.
• The triggering user’s effective role and permissions in the target project at the time the pipeline starts.
• Whether fine-grained permissions are enabled for the specific allowlist entry and whether the requested endpoint is covered by READ_REPOSITORIES or another policy.
• The target project visibility/feature settings, exact GitLab version, and whether the attempted operation is clone, REST read, or push.
• The actual HTTP response and Git transport result from a live, non-secret test.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 CI/CD job token · official_documentation · accessed 2026-09-21
• S2 Fine-grained permissions for CI/CD job tokens · official_documentation · accessed 2026-09-21
• S3 REST API authentication · official_documentation · accessed 2026-09-21
• S4 CI/CD job token scope API · official_documentation · accessed 2026-09-21