GitHub Actions / Events, execution, and data boundaries / Lesson 5

needs, matrices, and failure behavior

Expand deliberate test combinations and keep mandatory evidence visible through failures.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Calculate a matrix and review include or exclude effects.
Explain needs, fail-fast, max-parallel, and optional experimental combinations.

Dependencies express eligibility

By default, separate jobs do not have a textual ordering guarantee. A job with needs waits for the listed dependencies and can consume their declared outputs. Dependency failures or skips affect downstream eligibility unless explicit conditions change the behavior. Parcel’s package gate should depend on the required test evidence, while an independent documentation check can run separately. A final diagnostic job may need to observe failures, but it must not convert them into release readiness merely because its own report upload succeeds.

Expansion creates multiple executions

A matrix defines combinations such as two operating systems and two fixture modes, creating four job variations before exclusions or additions. Keep each dimension tied to a risk: operating-system differences, runtime support, or format compatibility. Adding dimensions mechanically can multiply cost without adding useful coverage. Review the expanded combinations rather than only the YAML. The complete local program below computes a Cartesian product and removes a declared unsupported pair. It models combination arithmetic, not the full semantics of Actions include and exclude merging.

python Count a synthetic matrix

from itertools import product
all_pairs = list(product(["linux", "windows"], ["plain", "unicode"]))
selected = [p for p in all_pairs if p != ("windows", "unicode")]
print(len(all_pairs))
print(selected)

Expected output

4
[('linux', 'plain'), ('linux', 'unicode'), ('windows', 'plain')]

The excluded pair is a teaching assumption, not a real platform limitation. Actions include entries have additional documented merge behavior and should be reviewed using the official matrix reference.

Cancellation and optionality are separate controls

strategy.fail-fast controls whether a failing matrix execution cancels other queued or in-progress executions under its documented behavior. continue-on-error allows a designated execution to fail without failing the workflow in the same way as a required execution. max-parallel limits simultaneous matrix jobs. These controls solve different problems and should not be copied as a bundle. An experimental runtime may be informational, but a required supported runtime must remain authoritative. Cancellation can reduce cost while also removing diagnostic evidence from other combinations.

Name the dimensions and bound concurrency

The following fragment runs two named fixture modes with a declared parallelism limit. It leaves fail-fast false so both synthetic checks can report. That choice is appropriate for comparative diagnostics, not a universal rule for every large matrix. The run command prints the selected mode only; it is deliberately not presented as a meaningful application test. A real job would use the mode as validated input to a complete fixture test and retain separate results for each execution.

yaml A matrix job fragment

strategy:
  fail-fast: false
  max-parallel: 2
  matrix:
    mode: [plain, unicode]
steps:
  - name: Show fixture mode
    env:
      PARCEL_MODE: ${{ matrix.mode }}
    run: printf "%s\n" "$PARCEL_MODE"

The enclosing job must choose an appropriate runner and shell. Each variation receives one mode value. This fragment neither tests Parcel nor executes a matrix on GitHub.

Aggregate results without losing identity

Each matrix job needs a recognizable name and collision-free artifact naming when producing files. A shared output name written by several matrix executions can be ambiguous or completion-order dependent. Prefer explicit per-combination artifacts and a reviewed aggregation job when the downstream decision needs all results. State what happens when an expected combination is missing, canceled, or intentionally excluded. A green summary should represent the declared required set, not simply the subset that happened to finish or publish last.

Common errors and fixes

An experimental failure cancels required evidence unexpectedly.

Why it happens: fail-fast and continue-on-error interactions were not reviewed.
How to fix it: Define required and experimental combinations explicitly.
Prevent it next time: Exercise failure and cancellation cases before relying on the summary.

Matrix uploads overwrite or collide under one artifact name.

Why it happens: Per-combination identity was omitted from output selection.
How to fix it: Use distinct names and an explicit aggregation contract.
Prevent it next time: Review expanded matrix names and produced artifacts together.

max-parallel is treated as a guarantee of available runners.

Why it happens: A concurrency ceiling was confused with capacity reservation.
How to fix it: Measure eligible runner availability and queueing separately.
Prevent it next time: Keep scheduling limits and capacity assumptions distinct.

Check your understanding

1. Three OS values and two runtime values create how many jobs before filtering?

Show worked solution

Six combinations. Exclusions can remove combinations and includes can modify or add entries according to Actions rules. Inspect the expanded set rather than assuming the final count remains a simple product after those rules.

2. Should a report-only aggregation job make a failed required matrix green?