gh run watch: Usage, Options & Common CI Errors

Block until a workflow run finishes - and fail your job if it failed.

gh run watch follows a run until it completes, refreshing its status live. With --exit-status it propagates the run’s success or failure as the command’s exit code, which is how you gate one pipeline on another.

What it does

gh run watch <run-id> polls a run and updates the terminal until it finishes. The crucial flag for automation is --exit-status: it makes gh exit nonzero if the watched run concluded in failure, so a calling job fails too. --interval controls the poll frequency.

Common usage

# Watch a run live
gh run watch 1234567890

# CI gate: block, then fail this job if the run failed
gh run watch 1234567890 --exit-status

# Watch the latest run and tighten the poll interval
RUN_ID=$(gh run list --limit 1 --json databaseId --jq '.[0].databaseId')
gh run watch "$RUN_ID" --interval 10 --exit-status

Common error in CI: watch exits 0 even though the run failed

A common mistake is gh run watch <id> succeeding (exit 0) even when the run failed, so the gating job goes green incorrectly. Fix: always add --exit-status when watching for a gate - without it, watch only reports status and exits 0 on completion regardless of conclusion. Combine with an explicit run ID from gh run list, since interactive resolution will not work in CI. Token needs actions: read.

Key options

Related guides