GitLab CI "needs:project" / Multi-Project Trigger Errors

needs:project pulls artifacts from a job in another project’s pipeline, and trigger:project starts a downstream pipeline there. Both fail when the project, ref, or job is wrong, or permissions are missing.

What this error means

A job using needs:project fails to fetch the cross-project artifact, or a trigger:project bridge errors because the downstream project/ref is unreachable or the job token lacks access.

Job log / bridge

This job could not start because it could not retrieve the needed artifacts.
needs:project 'group/upstream' ref 'main' job 'package': not found or not accessible

Common causes

Wrong project, ref, or job name

needs:project must name an existing project, a ref that has a successful pipeline, and the exact job that produced the artifact. Any mismatch yields "not found".

Job token lacks cross-project access

Downloading artifacts from another project requires the CI/CD job token of the current project to be allowed in the upstream project’s token access list.

No successful upstream pipeline for that ref

If the named ref has no recent successful pipeline (or the artifact expired), there is nothing to fetch.

How to fix it

Reference a real upstream job and ref

Name the upstream project, ref, and artifact-producing job exactly.

.gitlab-ci.yml

consume:
  needs:
    - project: group/upstream
      job: package
      ref: main
      artifacts: true
  script:
    - ls dist/

Allow the job token across projects

In the upstream project, open Settings → CI/CD → Token Access.
Add the consuming project to the allowlist so its job token can read artifacts.
Confirm the upstream ref has a recent successful pipeline whose artifacts have not expired.

How to prevent it

Pin needs:project to a stable ref (tag) with reliable successful pipelines.
Maintain the job-token allowlist between linked projects.
Keep upstream artifact expiry long enough for downstream consumers.