GitLab CI_JOB_TOKEN: access another project, and fix "not found"

By Melih Toksari, developer of MergeBell · Updated · 4 min read

Short answer

CI_JOB_TOKEN lets a GitLab CI job reach another project without a personal token, but only when three things hold: the other project's CI/CD job token allowlist includes your project or its group, the user who started the job is a member of the other project, and that user's role allows the action. Otherwise GitLab answers 404 or "The project you were looking for could not be found". Clone with gitlab-ci-token as the user. Only some API endpoints accept job tokens, and GraphQL doesn't. Pushing with the job token is off by default; a project turns it on under Job token permissions.

A job clones another private project, downloads its package or calls its API with $CI_JOB_TOKEN, and gets this:

remote: The project you were looking for could not be found or you don't have permission to view it.
fatal: repository 'https://gitlab-ci-token:[MASKED]@gitlab.com/group/project.git/' not found

Or a bare 404 Not Found from the API. GitLab usually answers “not found” rather than “forbidden”, so the message doesn’t tell you which check failed. Here are the checks in GitLab 19.5, and how to use the job token for each kind of access.

The three checks

For a job in project B to use its token on project A:

  1. A’s allowlist includes B. In project A, go to Settings › CI/CD › Job token permissions, select Add next to CI/CD job token allowlist, choose Group or project, and enter B’s path. By default a project’s allowlist holds only itself. You need the Maintainer or Owner role in A and, if B is private or internal, any role in B.
  2. The user who started the job is a member of A. The job token acts with the permissions of the person who started the job, or who owns the schedule or trigger.
  3. That user’s role allows the action, such as Reporter or higher to pull code.

A group on the allowlist covers every project in it and its subgroups, including ones created later. The allowlist grants no permissions of its own: it only lets members’ jobs use their access.

The token also stops working when the job ends, so it can’t be saved for later use.

Clone another project

git clone "https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_FQDN}/group/project.git"

The user is always gitlab-ci-token. This works even where HTTPS access to Git is turned off for the group or instance. CI_SERVER_FQDN is your GitLab’s host name, with the port if it isn’t the default, so the same line works on GitLab.com and on GitLab Self-Managed.

Submodules

  • Use relative URLs in .gitmodules, such as url = ../other-project.git for a project in the same group, so the runner clones the submodule over HTTPS with the job token. In projects that get forked, relative URLs can resolve to the fork, so use absolute HTTPS URLs there.
  • Set GIT_SUBMODULE_STRATEGY to normal, or recursive for nested submodules, so the runner fetches them before the job starts.
  • For SSH URLs like git@gitlab.com:group/project.git, set GIT_SUBMODULE_FORCE_HTTPS: "true" so the runner rewrites them to HTTPS.

The submodule project needs your project on its allowlist, and the user needs at least the Reporter role there.

fatal: could not read Username for 'https://gitlab.com': No such device or address

This one comes from Git commands you run yourself inside a submodule, or from nested submodules, because the runner’s Git settings aren’t passed on to them. On GitLab-hosted runners, submodules that point at https://gitlab.com also need the address rewritten. Pass both explicitly:

my-job:
  script:
    - cd path/to/submodule
    - git -c "include.path=$(git -C $CI_PROJECT_DIR config include.path)" -c "url.https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_FQDN}/.insteadOf=https://gitlab.com/" fetch origin

Call the API

curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --output file.txt \
  "$CI_API_V4_URL/projects/1234/packages/generic/my_package/0.0.1/file.txt"

The JOB-TOKEN header is the recommended way to send it. Only some endpoints accept a job token, among them:

  • packages, releases, deployments and environments;
  • job artifact downloads, and raw files from the repository;
  • reading merge requests and their notes;
  • triggering a pipeline, with POST /projects/:id/trigger/pipeline.

GraphQL never accepts job tokens. For other endpoints, use a project or group access token, stored as a masked CI/CD variable; token scopes explained covers which scope to give it.

Push with the job token

Pushing is off by default:

  • To the same project: turn on Allow Git push requests to the repository under Settings › CI/CD › Job token permissions. Only jobs from that project’s own pipelines can then push.
  • From another project: since GitLab 19.1, also turn on Allow cross-project Git push requests from allowlisted projects, keep the target’s allowlist on, and allowlist the source project with Read and write for Repositories, or with default permissions. The user who started the pipeline needs at least the Developer role in the target.

A push made with the job token doesn’t start a pipeline. GitLab warns against turning push on for pull mirrors.

Public and internal projects

Any project’s job token can fetch a public or internal project’s artifacts, container images, packages, releases, deployments, environments and repository, without an allowlist. To limit those to allowlisted projects, set each feature to Only Project Members under Settings › General › Visibility, project features, permissions.

Other job token errors

  • You are not allowed to download code from this project. An administrator who isn’t a direct member ran a protected manual job in a private project: cloning needs direct membership, even for administrators.
  • invalid character '\n' in string literal. base64 wrapped the long token. Use base64 -w0.
  • 403 Forbidden in long-running jobs, on GitLab 18.8 or earlier with JWT-format job tokens turned on: jobs with needs, in child pipelines, or silent for about six minutes. Fixed in GitLab 18.9.
  • denied: requested access to the resource is denied for a container image: pulls from another private project need its allowlist, as above, and pushes work only to the job’s own project. See GitLab container registry “denied”.

Signing in to Git outside CI is a different problem: see HTTP Basic: Access denied.

On your phone

MergeBell shows a job’s log live, with the token shown as [MASKED] just as in GitLab, and Retry reruns a job on the free tier: after you fix the allowlist, a retry is enough. The allowlist itself lives in Settings › CI/CD › Job token permissions in GitLab in a browser.

Frequently asked questions

Why does CI_JOB_TOKEN get "not found" for another GitLab project?

GitLab answers 404, or "The project you were looking for could not be found or you don't have permission to view it.", when the job token isn't allowed in. Check three things: the other project's CI/CD job token allowlist includes your project or its group, the user who started the job is a member of the other project, and that user's role there allows the action.

How do I add a project to the GitLab job token allowlist?

In the project being accessed, go to Settings › CI/CD › Job token permissions, select Add next to CI/CD job token allowlist, choose Group or project, and enter the path. You need the Maintainer or Owner role there and, if the project you add is private or internal, any role in it. A group entry covers every project in the group and its subgroups, including ones created later.

How do I clone another private GitLab repository in a CI job?

Use the job token as the password, with gitlab-ci-token as the user: git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/group/project.git. The other project must have yours on its job token allowlist, and the user who started the job needs at least the Reporter role there to pull code. For submodules, use relative URLs in .gitmodules and set GIT_SUBMODULE_STRATEGY.

Can CI_JOB_TOKEN push to a GitLab repository?

Only if the project turns on Allow Git push requests to the repository, under Settings › CI/CD › Job token permissions; it's off by default. Pushes from another project also need Allow cross-project Git push requests from allowlisted projects, available since GitLab 19.1. A push made with the job token doesn't start a pipeline.

Which GitLab APIs accept CI_JOB_TOKEN?

Only some REST endpoints, including packages, releases, deployments and environments, job artifact downloads, raw repository files, reading merge requests, and triggering a pipeline. GraphQL never accepts job tokens. For anything else, use a project or group access token stored as a masked CI/CD variable.

Sources

Checked against these pages on 4 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.

Do this from your phone with MergeBell

Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.

Get MergeBell for iPhoneGet MergeBell for Android

On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.