skip to content

With the GitHub CLI, how do you find out from the terminal why last night's scheduled workflow run failed, and rerun only what broke?

level: middleimportance: must knowfreq 44%

answer

  1. list, view, rerun, watch
  2. filter by workflow, event and status
  3. logs of the failed steps only
  4. failed jobs plus what they need

basics

~20 s

Find the run with gh run list filtered by workflow, event and status, read only the failing steps with gh run view <id> --log-failed, then gh run rerun <id> --failed and follow it with gh run watch <id> --exit-status.

solid answer

~40 s

Start with `gh run list --workflow nightly.yml --event schedule --status failure` to get the run ID (the list shows 20 runs by default). `gh run view <id>` summarises the jobs, and `-v` adds their steps. `gh run view <id> --log-failed` prints the log lines of just the failed steps, and `--job <id>` narrows it to one job. Logs are only available once the run has completed. To retry, `gh run rerun <id> --failed` reruns the failed jobs together with the jobs they depend on; `--debug` adds debug logging. `gh run watch <id> --exit-status` then follows the new attempt and exits non-zero if it fails, so it can gate a script. Since gh 2.87.0, `gh run view` also honours `--exit-status` together with `--log` or `--log-failed`.

code

bash · 11 lines
bash
# 1. Find last night's failed scheduled run
gh run list --workflow nightly.yml --event schedule --status failure --limit 3

# 2. Read only the failing steps
gh run view 9876543210 --log-failed

# 3. Rerun the failed jobs (and the jobs they need)
gh run rerun 9876543210 --failed

# 4. Follow the new attempt; non-zero exit if it fails again
gh run watch 9876543210 --exit-status

go deeper

for a junior

Recall the four commands, gh run list, view, rerun and watch, and that --log-failed shows only the failing steps.

for a middle

Explain the filters that find the right run, the difference between --failed and a full rerun, and why --exit-status matters in a script.

for a senior

Show how you would make this loop reliable in automation: exit statuses, attempts, job database IDs, debug reruns and keeping gh patched for untrusted logs.

for a principal

Weigh when a team should rerun a failure versus quarantine or fix it, and how rerun habits hide flaky jobs that cost CI time and trust.

## The situation A **workflow run** is one execution of a GitHub Actions workflow file. It contains one or more **jobs**, and each job is a sequence of **steps**. A nightly workflow, triggered by the `schedule` event, failed overnight. You want to know why and get it green again, without clicking through the browser. The GitHub CLI's `gh run` commands cover the whole loop: find, read, retry and watch. ## Step 1: find the run `gh run list` lists recent runs for the current repository (20 by default; `--limit` / `-L` changes that). Its filters narrow the list to the run you mean: - `--workflow` / `-w` takes a workflow's name or file name, such as `nightly.yml`. By name it skips disabled workflows unless you add `--all` / `-a`. - `--event` / `-e` filters on the triggering event, such as `schedule`, `push` or `pull_request`. - `--status` / `-s` filters on a status or conclusion: `failure`, `cancelled`, `in_progress`, `queued`, `success` and others. - `--branch` / `-b`, `--user` / `-u`, `--commit` / `-c` and `--created` filter by branch, triggering user, commit SHA and creation date. The help also says that for runs tied to a pull request, `gh pr checks` is the better entry point. ## Step 2: read only what failed `gh run view <run-id>` shows the run's summary: its jobs, their conclusions and any annotations. `--verbose` / `-v` lists every job's steps. Then there are three ways to read logs: | Flag | What it prints | When to use it | |---|---|---| | `--log-failed` | log lines from the failed steps only | the first look at a red run | | `--log` | the full log of the run, or of one job | when the cause is in an earlier, passing step | | `--job <id>` / `-j` | limits the view or the log to one job | large matrices with one failing leg | Points worth knowing: - `--log` and `--log-failed` cannot be combined, and neither can `--log` and `--web`. - Logs exist only for **completed** runs and jobs. On a run still in progress, gh says the logs will be available when it is complete. - `--attempt <n>` / `-a` views a specific attempt of a run that has been rerun. - gh downloads logs as an archive and maps them to jobs and steps. When the platform does not let it do that, it falls back to fetching each job's log separately and fails if more than 25 job logs are missing. Lines it cannot tie to a step appear under `UNKNOWN STEP`. - **gh 2.92.0** fixed a vulnerability that let a workflow log inject terminal escape sequences into `gh run view --log` and `--log-failed` output. That is a reason to keep gh current on machines that read untrusted logs. ## Step 3: rerun only what broke `gh run rerun <run-id>` reruns the run. The flags decide how much: 1. With no flags, it reruns the entire run. 2. `--failed` reruns only the failed jobs, **including their dependencies**: the jobs they need are run again too, so they get fresh inputs. 3. `--job <id>` / `-j` reruns one job and its dependencies. The ID is the job's database ID, not the number in the browser's job URL. The help warns that the URL number returns 404 and shows how to look up the right ID. 4. `--debug` / `-d` reruns with debug logging, for failures the normal log does not explain. A rerun is a new **attempt** of the same run, so the run ID stays the same and `--attempt` tells the attempts apart. ## Step 4: watch it and let the exit status speak `gh run watch <run-id>` redraws the run's progress every 3 seconds (`--interval` / `-i`) until it completes. `--compact` shows only the relevant or failed steps. On exit status: - Without `--exit-status`, `gh run watch` exits 0 whatever the run's conclusion. It reports progress and nothing more. - With `--exit-status`, it exits non-zero when the run does not succeed, so `gh run watch 9876543210 --exit-status && ./deploy-next.sh` is safe. - `gh run view <id> --exit-status` does the same for a single look. Since **gh 2.87.0** it is honoured together with `--log` and `--log-failed`. - The help for `gh run watch` notes that it cannot authenticate with a fine-grained personal access token, because such a token cannot carry the `checks:read` permission. Which token gh picks up is a configuration question for the authentication material. - With no run ID and no terminal, `gh run view`, `gh run watch` and `gh run rerun` stop with an error instead of prompting. ## What the CLI does not decide Why the nightly is scheduled when it is, how its jobs depend on each other and whether a step should retry are questions about writing the workflow file. The CLI reads runs and asks for reruns. The fix for a flaky step still goes into the workflow file.

  • `gh run rerun 9876543210 --job 4` returns 404 even though job 4 is visible in the browser. Why?
    `--job` expects the job's database ID, not the number in the browser's job URL. The help shows the lookup: `gh run view <run-id> --json jobs --jq '.jobs[] | {name, databaseId}'`, then pass that `databaseId` to `--job`.
  • Your script does `gh run watch $RUN && ./release.sh`, and a release went out after a failed run. What went wrong?
    Without `--exit-status`, `gh run watch` exits 0 when the run completes, whatever its conclusion, so the `&&` never blocked the release. Add `--exit-status`, which returns non-zero when the run does not succeed.
  • `gh run view 9876543210 --log` prints an error instead of a log. What is the likely reason?
    The run, or the job you selected, is still in progress. gh fetches logs only for completed runs and says they will be available when it is complete. Use `gh run watch` until it finishes, or look at another attempt with `--attempt`.

  • gh run rerun --failed reruns only the failed steps inside each job
  • gh run watch exits non-zero on a failed run without any extra flag
  • You can read a run's logs with gh while its jobs are still running
  • The job number in the browser URL is the ID gh run rerun --job expects
  • A rerun gets a brand-new run ID, so the old ID is useless afterwards

Assumes gh 2.102; since gh 2.87.0 gh run view honours --exit-status together with --log and --log-failed, and gh 2.92.0 fixed terminal escape-sequence injection in those log views.