## 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
```text
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
```bash
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
```bash
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
```bash
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
```text
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