GitLab CI "Project ... not found or access denied" on include:project

include:project pulls a YAML file from another GitLab project. It fails if the project path is wrong, the file or ref does not exist, or the including pipeline lacks read access to the source project.

What this error means

Validation fails stating the project was not found or access was denied, or that the included file could not be fetched at the given ref.

gitlab-ci

This GitLab CI configuration is invalid:
Project 'my-group/ci-templates' not found or access denied!
Check the include:project, include:file, and include:ref values.

Common causes

Wrong project path or file path

The project: must be the full namespace/path, and file: must match the path in that repo at the given ref:.

CI job token lacks access

The source project may restrict CI job token access, or the including project is not on its allowlist.

Ref does not contain the file

The ref: (branch, tag, or SHA) may not contain the file, or defaults to the project default branch when omitted.

How to fix it

Set project, file, and ref precisely

Reference the exact path and ref, and confirm the file exists there.

.gitlab-ci.yml

include:
  - project: 'my-group/ci-templates'
    ref: 'main'
    file: '/templates/build.yml'

Grant CI job token access

In the source project, open Settings then CI/CD then Token Access.
Add the including project to the allowlist.
Confirm the user or token has at least Reporter access to read the file.

How to prevent it

Pin include:ref so template changes are deliberate.
Maintain the CI job token allowlist when adding new consumer projects.
Keep shared templates in a project with read access for all consumers.