Rerun the Right GitHub Actions Jobs with gh run rerun

gh run rerun asks GitHub to run a failed job again, and picking the wrong scope can quietly redeploy or re-bill more than you meant to. Budget about ten minutes if you already have the run ID and permission to rerun it. The examples use GitHub CLI 2.87.3, installed here on 23 September 2026.

1. Check the installed command

Confirm the gh binary is the one on your path and inspect the local command contract:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
$ gh run rerun --help

The installed subcommand accepts an optional run ID, --failed, --job with a string value, --debug, and the inherited --repo option. The help output is the useful version check when a machine has more than one GitHub CLI installation.

2. Identify the run before changing it

Use gh run list to find a recent run, or take the number from your normal Actions record. Inspect the candidate first:

$ gh run list --repo OWNER/REPO --limit 10
$ gh run view RUN_ID --repo OWNER/REPO
Run workflow: build
Status: failure
Conclusion: failure

Replace OWNER/REPO and RUN_ID with real values. The exact list and view output depends on the repository and your account. Check the workflow name, commit, branch and failed jobs, not just the numeric ID. If the run is from another repository, keep --repo OWNER/REPO on every command so the default repository cannot surprise you.

These inspection commands are read-only. If they report an authentication or permission error, fix that with your normal GitHub CLI login and repository access process; rerunning a run you cannot inspect is a poor recovery plan.

3. Rerun the whole run

Use the run ID with no selection flag when every job should execute again:

$ gh run rerun RUN_ID --repo OWNER/REPO

A successful request normally returns to the shell without listing each new job. Verify the new attempt by viewing the run:

$ gh run view RUN_ID --repo OWNER/REPO

Look for the new attempt or updated status in the output. A rerun repeats workflow work, so review any job with side effects before using this form. It is not an undo operation, and it does not remove the failed attempt from the Actions history.

4. Rerun only failed jobs

When successful jobs do not need to run again, add --failed:

$ gh run rerun RUN_ID --repo OWNER/REPO --failed

The installed manpage defines this as rerunning only failed jobs, including dependencies. That dependency detail matters: a job needed by a failed job can be scheduled too. Treat the command as a small recovery run, not a guarantee that exactly one failed job will execute.

$ gh run view RUN_ID --repo OWNER/REPO

If the failure was caused by an expired secret, an unavailable runner, a changed input or a real code defect, rerunning may only reproduce it. Fix the cause first when a rerun would repeat an unsafe deployment or consume a limited external resource.

5. Find the correct ID for one job

The --job option takes a job database ID. Do not use the number copied from a job URL. GitHub's URL commonly ends with a number such as /jobs/123456789, but the CLI documentation warns this URL number can produce an API 404 NOT FOUND when passed to --job.

Ask the run view for each job's name and databaseId:

$ gh run view RUN_ID --repo OWNER/REPO --json jobs --jq '.jobs[] | {name, databaseId}'
{"name":"test","databaseId":987654321}
{"name":"deploy","databaseId":987654322}

The names and numbers above are examples. Copy the databaseId for the exact job you intend to repeat. If several jobs have similar names, use the complete object and check the workflow and run context before you continue.

6. Rerun one job and its dependencies

Pass the selected database ID to --job:

$ gh run rerun RUN_ID --repo OWNER/REPO --job 987654321

The command reruns that specific job, including dependencies. It does not accept the job display name, a URL, or the URL path number merely because it looks like a job ID. If GitHub returns 404 NOT FOUND, stop rather than trying random numbers: fetch databaseId again, confirm the repository and run, and retry only with the verified value.

There is no local rollback command for a rerun. To recover from an accidental request, let the scheduled jobs finish, or cancel the new run through the normal GitHub Actions controls after confirming cancellation is safe. A cancellation can leave partial external changes, so it is not a substitute for a deployment rollback plan.

7. Add debug logging only when needed

Use --debug when the CLI request itself needs diagnostic logging:

$ gh run rerun RUN_ID --repo OWNER/REPO --failed --debug

Debug output can expose request details in a terminal log. Keep it out of shared tickets unless you have reviewed it for repository names, URLs and other sensitive context. The flag does not make a workflow job more verbose; it enables debug logging for the rerun command itself.