GitLab CI Trigger Job Fails - Downstream Pipeline Failed

By Daniel Zoghalchali·Latchkey

A trigger job with strategy: depend mirrors the downstream pipeline status. When the child or multi-project pipeline fails, the trigger job fails too. The root cause lives in the downstream pipeline, not the trigger.

What this error means

The trigger job is red with a generic downstream failure message, while the actual error is in the linked child or multi-project pipeline.

The downstream pipeline failed.
trigger job 'deploy-service' failed because its downstream
pipeline (strategy: depend) finished with status: failed

Diagnose it: which rule matched, and on which runner?

GitLab evaluates rules: top to bottom and the first match wins, including one that sets when: never. A job that does not run, or runs when you did not expect it to, is nearly always matching an earlier rule than the one you are reading.

# validate the definition against the project
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/ci/lint" \
  --data-urlencode "content=$(cat .gitlab-ci.yml)"

# what the job actually sees
script:
  - env | grep -E "^CI_(PIPELINE_SOURCE|COMMIT_REF_NAME|RUNNER)" | sort

Common causes

A job in the downstream pipeline failed

With strategy:depend, any failed downstream job fails the trigger.

Downstream pipeline could not be created

An invalid downstream config or a transient coordinator hiccup can leave the trigger failed.

Transient infrastructure failure downstream

A momentary runner or network blip can fail a downstream job that would otherwise pass on retry.

How to fix it

Open and fix the downstream pipeline

Follow the link from the trigger job to the failed downstream pipeline and address the failing job there.

1. Click into the downstream pipeline from the trigger job.
2. Identify the failed downstream job and read its log.
3. Fix the root cause, then re-run the downstream (or the parent) pipeline.

Decide whether to propagate failure

Drop strategy:depend if the downstream result should not block the parent.

deploy-service:
  trigger:
    project: group/service
    strategy: depend   # remove to not propagate downstream failure

How to prevent it

• Use strategy:depend only when downstream success should gate the parent.
• Keep downstream pipelines independently green.
• Add retries to flaky downstream jobs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation