gh run rerun: Re-run Failed Workflow Jobs

By Kaveh Alemi·Latchkey

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

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

Flags

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.

- 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

Frequently asked questions

Related guides

References

• GitHub Actions documentation