How to re-run only the failed jobs in GitHub Actions (web, CLI and API)
To re-run only the failed jobs in a GitHub Actions workflow run, open the run's summary page, open the Re-run jobs dropdown in the upper-right corner and click Re-run failed jobs. In a terminal, GitHub CLI does the same thing with gh run rerun RUN_ID --failed. Both also re-run any jobs that depend on the failed ones, and both work for up to 30 days after the run first started. Before you click, take a minute to check whether the failure is a known flake or a real break. A re-run tests the same commit again, so a pass afterwards does not mean anything was fixed.
Re-run failed jobs in the GitHub web interface
Use this route when a pull request shows a red check and you want to try again from the browser. It leaves the jobs that already passed alone, so you only wait for the parts that failed.
- Open the summary page of the workflow run that failed.
- In the upper-right corner of the workflow, open the Re-run jobs dropdown menu and click Re-run failed jobs.
- If you like, tick Enable debug logging. It turns on runner diagnostic logging and step debug logging for the re-run. This helps when the first log did not tell you enough.
- Read the confirmation dialog before you confirm. It lists every job that will run again, including jobs further down the chain that depend on the failed ones. One failed early job can bring a long test or deploy job back with it.
If you want to re-run just one job, hover over it in the left sidebar of a completed run. Each job listed there has a re-run icon. GitHub's announcement of partial re-runs gave the reason the feature exists: workflows can take a while to run, so when a small part fails, it is frustrating to wait for all of it to run again.
Re-run failed jobs with GitHub CLI
The gh run rerun command reruns an entire run, only the failed jobs, or one specific job from a run. The --failed flag reruns only the failed jobs, including their dependencies. Replace RUN_ID with the ID of the workflow run:
gh run rerun RUN_ID --failedAdd --debug to rerun with debug logging. This is the CLI version of the Enable debug logging box in the web interface:
gh run rerun RUN_ID --failed --debugRe-run one specific job without a not-found error
The --job flag reruns one job ID from a run, including its dependencies. There is a catch that the GitHub CLI manual points out. The number in the browser URL of a job page is not the ID that --job expects. If you pass that number, the API returns a not-found error. Get the correct job IDs with this command instead:
gh run view RUN_ID --json jobs --jq '.jobs[] | {name, databaseId}'Use the databaseId field of the job you want, then run gh run rerun --job DATABASE_ID. Jobs that depend on it run again too.
Re-run failed jobs from a script with the REST API
Use the REST API when you want a bot, a chat command or an internal tool to start the re-run. The endpoint re-runs all of the failed jobs and their dependent jobs in a workflow run, using the ID of the workflow run:
POST /repos/{owner}/{repo}/actions/runs/{run_id}/rerun-failed-jobsIts enable_debug_logging parameter sets whether to enable debug logging for the re-run. The same API page also documents an endpoint that re-runs a single job and its dependent jobs.
Pick the token carefully. OAuth app tokens and personal access tokens (classic) need the repo scope to use these endpoints. GitHub's table of fine-grained personal access token permissions lists the rerun-failed-jobs endpoint under the Actions repository permission with write access, so a fine-grained token with Actions write access is the narrower choice.
What a re-run keeps from the original run
A re-run is not a fresh run. GitHub applies a few rules to every re-run, and they explain most of the confusion around re-running.
| Rule | What it means for you |
|---|---|
| Same commit and ref | The re-run uses the same GITHUB_SHA and GITHUB_REF as the original event that triggered the run. It tests exactly the same code. If you changed something, push a new commit. |
| Original actor's privileges | Re-runs use the privileges of the actor who first triggered the workflow, not the person who clicks re-run. |
| Time window | You can re-run a run, its failed jobs or specific jobs up to 30 days after the initial run. |
| Attempt limit | A workflow run can be re-run a maximum of 50 times. |
| Disabled workflows | You can't re-run a workflow run, or any of its jobs, while the workflow is disabled. |
The same-commit rule matters most. When a failed job passes on a re-run, the code did not get better. It shows that the same code can both fail and pass, which is what a flaky job is. That is useful to know, and it is also a reason not to re-run on reflex.
Decide whether a re-run is the right move
Re-running a real failure costs you runner time and a wait, and you still have the bug at the end. A few questions to ask before you click:
- Has this job failed and then passed on the same commit before? If so, it is probably a known flake. Still read the log if the failure could matter.
- Is the same job failing on the default branch too? Then your pull request probably did not cause it, and re-running will not fix it.
- Is this a new failure in a job that is normally stable? Read the log first. Your change may well have broken it.
- Does the log point to a timeout, a network call or a download from an outside service? Those failures are the usual candidates for a re-run.
You can answer these questions by hand by scrolling through the workflow's Actions history. A browser extension can also do the lookup for you. FlakeRadar, a Chrome extension that is not affiliated with or endorsed by GitHub, is one option. On a pull request it labels each failing GitHub Actions job as Known flake, New failure, Also failing on the default branch, or Not enough history. Each label shows counts and a time window taken from the repository's own Actions history. On a known flake, its Re-run failed jobs button can start the re-run for you. The button is off until you switch it on, needs a token with Actions: Read and write, and sends a re-run only when you click. It is free for public repositories with 30 days of history. Private repositories need the Pro plan. A known flake label is evidence, not a promise, so read the log when the failure matters.
Automatic retries, and why to keep them narrow
GitHub Actions does not provide a built-in way to rerun a failed workflow automatically. A common workaround, described by Gérald Barré, uses the workflow_run event to start a second workflow whenever a previous one fails.
If you set this up, keep it narrow. Retry once, not in a loop. Retry only on failures you know are transient, such as a network error in a known step. Keep a record of every automatic retry. An automatic retry that passes hides the flake from the team, and the flaky test stays in the suite. Re-runs also count toward the limit of 50 per workflow run.
Sources
- GitHub Docs: Re-running workflows and jobs
- GitHub CLI manual: gh run rerun
- GitHub REST API: Workflow runs endpoints
- GitHub Docs: Permissions required for fine-grained personal access tokens
- GitHub Blog: Save time with partial re-runs in GitHub Actions
- Gérald Barré: Automatically rerun failed GitHub Actions workflows
Questions
Does Re-run failed jobs also run the jobs that passed?
No. It re-runs the failed jobs plus any jobs that depend on them. Before the re-run starts, the confirmation dialog lists every job that will run again.
Why does gh run rerun --job give a not-found error?
You probably used the number from the job's browser URL. That is a different ID. Run gh run view RUN_ID --json jobs and use the databaseId field instead.
Does a re-run pick up my latest commit?
No. A re-run uses the same commit SHA and git ref as the original event. To test new code, push a commit.
How long can I wait before re-running a failed run?
GitHub allows re-runs up to 30 days after the initial run, and a workflow run can be re-run a maximum of 50 times.