mediumFoundationSymptom-first#manual#blocked#pipeline#allow-failure

GitLab pipeline blocked - manual job with allow_failure: false

Pipeline shows 'Blocked' status and cannot proceed

Likely source:availabilitydeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Pipeline shows 'Blocked' status and cannot proceed
  • A job with 'when: manual' is preventing downstream jobs from running
  • Pipeline status is yellow (blocked) even though all automated jobs passed

By default, manual jobs have allow_failure: false, meaning they block the pipeline until manually triggered. Explicitly set allow_failure: true if the manual step should not block.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Manual job configuration

    grep -B2 -A10 'when: manual' .gitlab-ci.yml

  • Pipeline job dependency graph

    glab api /projects/<PROJECT_ID>/pipelines/<PIPELINE_ID>/jobs --jq '.[] | {name, status, when}'

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Job has 'when: manual' but no 'allow_failure: true'
  • Pipeline blocks on a deploy-to-production step

Confirm before fixing

grep -A5 'when: manual' .gitlab-ci.yml | grep 'allow_failure'
READ

Check allow_failure setting

Fix

sed -i '/when: manual/a\ allow_failure: true' .gitlab-ci.yml
CHANGE

Add allow_failure: true to let the pipeline pass

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
glab api /projects/<PROJECT_ID>/pipelines/<PIPELINE_ID>/jobs --jq '.[] | select(.when == "manual") | {name, status, allow_failure}'
READ

List all manual jobs

2
grep -B5 -A10 'when: manual' .gitlab-ci.yml
READ

Review the manual job definition

3
sed -i '/when: manual/a\ allow_failure: true' .gitlab-ci.yml
CHANGE

Make the manual job non-blocking

Prevention

  • Always set allow_failure: true on manual jobs that should not block the pipeline.
  • Use 'when: manual' only for deploy-to-production steps, not for intermediate CI stages.
  • Add pipeline status checks to merge request pipelines to catch blocked states early.

Related runbooks

Same stack, same failure family — worth a skim.

GitLab job stuck 'waiting for a runner' - tag mismatchhigh

Job stuck in 'pending' state with 'Waiting for a runner'

GitLab CIIntermediate2 causes
Open runbook
GitLab CI artifact download fails - expired or 403 forbiddenmedium

Downloading artifacts returns 403 Forbidden or 404 Not Found

GitLab CIFoundation2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.