GitLab CI_JOB_TOKEN: access another project, and fix "not found"
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:
- 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.
- 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.
- 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 asurl = ../other-project.gitfor 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_STRATEGYtonormal, orrecursivefor nested submodules, so the runner fetches them before the job starts. - For SSH URLs like
git@gitlab.com:group/project.git, setGIT_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.base64wrapped the long token. Usebase64 -w0.403 Forbiddenin long-running jobs, on GitLab 18.8 or earlier with JWT-format job tokens turned on: jobs withneeds, in child pipelines, or silent for about six minutes. Fixed in GitLab 18.9.denied: requested access to the resource is deniedfor 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
- GitLab docs — GitLab CI/CD job token
- GitLab docs — Add a group or project to the job token allowlist
- GitLab docs — Using Git submodules with GitLab CI/CD
- GitLab docs — Fine-grained permissions for CI/CD job tokens
- GitLab docs — Job troubleshooting: You are not allowed to download code
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.