gh run watch Command Reference

Stream a workflow run until it finishes, and fail if it fails.

gh run watch follows a workflow run live and returns when it completes. With exit-status it lets a triggering job block on, and inherit the result of, a downstream run.

What it does

gh run watch streams the progress of a run (by ID, or interactively chosen) until it concludes. With --exit-status it returns a nonzero exit code if the run failed, propagating the downstream result to the calling job.

Common flags and usage

[run-id]: the run to watch (omit to pick interactively)
--exit-status: exit nonzero if the run fails
--interval N: polling interval in seconds
--compact: show only failed steps

Example

shell

- name: Trigger and wait
  env:
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    gh workflow run deploy.yml --ref main
    RUN_ID=$(gh run list --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')
    gh run watch "${RUN_ID}" --exit-status

In CI

Always pass --exit-status when chaining pipelines so a failed downstream run fails the triggering job instead of passing silently. Resolve the run ID with gh run list right after dispatch.

Key takeaways

--exit-status makes a failed downstream run fail the watching job.
Resolve the run ID with gh run list right after a dispatch.
Use it to turn an async gh workflow run into a blocking step.