how to re-run a single failed GitHub Actions matrix job

TL;DR

You do not need to rerun a 20-leg matrix because one leg failed: GitHub lets you re-run just the failed jobs. Use the Re-run failed jobs button (or gh run rerun --failed), which re-executes only failed legs with the same matrix values. If the failure was flaky, the single re-run usually goes green without burning the other 19 legs' minutes.

Error / query

how to re-run a single failed GitHub Actions matrix job

Use this skill when

• One matrix leg failed and the rest passed
• You want to save CI minutes on re-runs
• A matrix leg flaked and needs one more try
• Debugging a specific matrix combination

Not for this skill when

• The job fails deterministically (fix the cause first)
• You are authoring the matrix strategy (different guide)
• You want to rerun everything (use re-run all jobs)

Steps

Step 1: Identify the failed leg

gh run view [run-id] --json jobs -q '.jobs[] | select(.conclusion=="failure") | .name'

Expected: the exact matrix leg name(s) that failed, e.g. test (ubuntu-latest, node-20). Confirm the others are green; if many legs failed, the problem is systemic, not leg-specific.

Step 2: Re-run only the failed jobs

gh run rerun [run-id] --failed

Expected: GitHub queues new attempts for the failed legs only, with identical matrix inputs. In the UI this is the Re-run failed jobs dropdown on the run page. Passed legs are untouched.

Step 3: Watch the re-run leg

gh run watch [run-id] --exit-status

Expected: the re-run leg executes and reports its conclusion. A flaky leg goes green; a real failure fails again with the same error, which tells you it was not flakiness.

Step 4: Decide based on the outcome

Green on re-run  -> it was flaky; consider quarantining or deflaking the test.
Red on re-run    -> real failure; fix the code or the matrix combination.
Red only on some re-runs -> intermittent; capture logs before they age out.

Expected: a clear next action. Do not re-run a third time hoping for luck; two failures is a signal.

Variant phrasings

"rerun failed matrix job github actions"

gh run rerun --failed (step 2) or the UI dropdown. Failed-only is the key.

"github actions rerun one job in matrix"

Same command. Matrix legs are jobs; failed-only rerun targets exactly them.

Why it happens

Matrix strategies fan out N jobs from one definition, and GitHub tracks each leg as an independent job with its own conclusion. The rerun-failed path reuses that granularity, so you pay for one leg instead of N. It exists precisely because matrix failures are usually leg-specific (one OS, one version) rather than global.

Edge cases and pitfalls

• Re-run uses the same commit and inputs; if you pushed a fix, start a new run instead of re-running the old one.
• Failed-required-checks semantics: a re-run that goes green updates the check, but branch protection may need the new run to complete before merge.
• gh run rerun without --failed reruns everything; the flag is the whole point.
• Logs from the original failed attempt stay available; compare attempt logs to spot what changed between runs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_BCg5TAaIJKgA4IvaCmIbCQ