# gh run rerun: Re-run Failed Workflow Jobs

> gh run rerun retries a workflow run, optionally only the failed jobs or with debug logging. Reference for --failed, --job, --debug, and CI permission errors.

Source: https://latchkey.dev/learn/command-reference/gh-run-rerun  
Updated: 2026-06-30

gh run rerun re-runs a workflow run, either entirely or just the jobs that failed.

For flaky-test recovery, gh run rerun --failed retries only what broke instead of burning minutes on the whole matrix.

## What it does

gh run rerun starts a new attempt of a workflow run. By default it re-runs all jobs; --failed re-runs only the failed ones, and --job re-runs a single job. --debug enables step debug logging for the new attempt.

## Common usage

```Terminal
gh run rerun 1234567890
gh run rerun 1234567890 --failed
gh run rerun --job 9876543210
gh run rerun 1234567890 --failed --debug
```

## Flags

| Flag | What it does |
| --- | --- |
| --failed | Re-run only the failed jobs |
| -j, --job <job-id> | Re-run a specific job by ID |
| -d, --debug | Enable step debug logging for the new run |
| <run-id> | The workflow run to re-run |
| -R, --repo <owner/repo> | Target a specific repository |

## In CI

Set GH_TOKEN and permissions: { actions: write }. Only the most recent attempt of a run can be re-run, and re-running consumes a new set of Actions minutes. --debug requires the token to have access to enable debug logging.

## Common errors in CI

"Resource not accessible by integration" or "HTTP 403" means the token lacks actions: write. "run ... cannot be rerun; its workflow file may be broken" means the workflow file at that commit no longer parses. Re-running an old attempt fails because only the latest attempt is eligible.

## Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

```.github/workflows/ci.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### gh run rerun: Re-run Failed Workflow Jobs?

For flaky-test recovery, gh run rerun --failed retries only what broke instead of burning minutes on the whole matrix.

### What it does?

gh run rerun starts a new attempt of a workflow run. By default it re-runs all jobs; --failed re-runs only the failed ones, and --job re-runs a single job. --debug enables step debug logging for the new attempt.

### In CI?

Set GH_TOKEN and permissions: { actions: write }. Only the most recent attempt of a run can be re-run, and re-running consumes a new set of Actions minutes. --debug requires the token to have access to enable debug logging.

### Common errors in CI?

"Resource not accessible by integration" or "HTTP 403" means the token lacks actions: write. "run ... cannot be rerun; its workflow file may be broken" means the workflow file at that commit no longer parses. Re-running an old attempt fails because only the latest attempt is eligible.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt