Pipeline failure propagation — what happens when a dependency fails

When a job listed in needs: fails, the dependent is skipped by default. The default is right for most cases: a deploy that depends on a failed test should not run. But some jobs must run on failure (notifications) or cancellation (cleanup). Designing failure propagation is part of pipeline design.

The default: skip on failure

flowchart LR
    T["test"] -- fails --> D["deploy"]
    D -.skipped.-> X["(no run)"]

When test fails, deploy is skipped; the run is marked failed. Default propagates failure downstream; a job with no needs: is unaffected.

if: always()

notify:
  needs: [test]
  if: always()
  steps:
    - run: ./slack-notify.sh

Runs on every outcome. For notifications, audit.

if: failure()

diagnose:
  needs: [test]
  if: failure()
  steps:
    - run: ./collect-diagnostics.sh

Runs only on failure. For diagnostics, rollback.

if: success() and if: cancelled()

if: success() is the implicit default. if: cancelled() runs only when a predecessor was cancelled. For jobs that release resources on cancellation.

continue-on-error

continue-on-error marks a failure as success:

- name: Lint
  run: ./lint.sh
  continue-on-error: true

Step exits non-zero but job is success; dependents see success.

continue-on-error is not if: failure(). The first makes a failure look like success; the second makes a dependent run on failure.

flowchart LR
    subgraph N["Normal"]
        T1["test"] -->|fails| D1["deploy: skipped"]
    end
    subgraph F["continue-on-error"]
        T2["test"] -->|fails-as-success| D2["deploy: runs"]
    end
    subgraph I["if: failure()"]
        T3["test"] -->|fails| N3["notify: runs"]
    end

Combining the overrides

cleanup:
  needs: [build, test]
  if: failure() || cancelled()
  steps:
    - run: ./cleanup.sh
      continue-on-error: true

Runs only on failure or cancellation; cleanup step allowed to fail.

Production discipline

1. Design failure propagation deliberately.
2. if: always() for notifications/audit.
3. if: failure() for diagnostics/rollback.
4. continue-on-error sparingly; hides bugs.

Cross-course references

• Ansible for Production Sysadmins - Part XXXVII uses the same override in AWX.
• Linux for Production Sysadmins - Part XXX uses OnFailure= systemd.

Quiz