Watch a GitHub Actions Run with gh run watch

Tabbing back to check a GitHub Actions run gets old fast: gh run watch sits and watches it for you. You will finish with a repeatable way to find a run, watch it until completion, and make a shell command fail when the run fails. Allow about ten minutes. You need GitHub CLI, access to the repository, and a shell. The examples use gh 2.87.3, the version resolved by gh on the machine used for this guide.

1. Check the installed command

Confirm which binary your shell will run, and read its local help:

$ command -v gh
/home/linuxbrew/.linuxbrew/bin/gh
$ gh version
gh version 2.87.3 (2026-02-23)
$ gh run watch --help

The command's synopsis is gh run watch <run-id>. The installed help also documents --compact, which only shows relevant or failed steps. The local compressed manpage lists the core options but not that newer display flag, so trust the command's own help when versions differ.

A version check matters here because GitHub CLI is often installed by more than one package manager. If command -v gh points somewhere unexpected, fix your PATH or invoke the intended absolute path before continuing.

2. Find the run ID

Run the list command from a checked-out repository with a GitHub remote, or name the repository explicitly. Limit the result while you are choosing a run:

$ gh run list --repo OWNER/REPOSITORY --limit 5
STATUS  TITLE                 WORKFLOW  BRANCH  EVENT  ID       AGE
...     ...                   ...       ...     ...    1234567  ...

Replace OWNER/REPOSITORY with a real value. Copy the numeric value in the ID column, not the workflow run number or a pull request number. Narrow the list with a documented filter such as --branch main or --status in_progress:

$ gh run list --repo OWNER/REPOSITORY --branch main --limit 3

If the command says it cannot determine the base repository, the current directory has no usable GitHub remote: keep the explicit --repo form, or switch to a checkout whose remote identifies the right repository. An authentication or permission error means gh auth status next; never paste a token into the command line.

3. Watch the run

Pass the copied run ID and repository to gh run watch:

$ gh run watch 1234567 --repo OWNER/REPOSITORY
Refreshing checks status every 3 seconds. Press Ctrl-C to quit.
... workflow and step progress ...

The default refresh interval is three seconds. The command keeps refreshing until the run completes, then hands the shell back. Output is live status, so names, timings and step results will differ from this example, and the command never changes the run.

For a busy workflow, cut the noise without changing what GitHub executes:

$ gh run watch 1234567 --repo OWNER/REPOSITORY --compact

Use --interval 10 when a slower refresh is preferable:

$ gh run watch 1234567 --repo OWNER/REPOSITORY --interval 10

The interval is in seconds and must be an integer. A very short interval just creates needless API traffic; it does not make a remote runner finish sooner.

4. Make the shell notice a failed run

Without an explicit status option, watching and judging are easy to confuse. Add --exit-status when a script or follow-up command must stop if the workflow conclusion was not successful:

$ gh run watch 1234567 --repo OWNER/REPOSITORY --exit-status
$ printf 'watch exit status: %s\n' "$?"
watch exit status: 0

On a successful run, the final status is zero. On a failed run, --exit-status makes the command return non-zero, but a non-zero result can also mean the command could not fetch or watch the run: read the diagnostic output before calling it a workflow failure.

This is the useful shell pattern:

$ gh run watch 1234567 --repo OWNER/REPOSITORY --exit-status && notify-send 'GitHub Actions run passed'

The notification fires only after a zero exit status. To handle both outcomes explicitly:

$ if gh run watch 1234567 --repo OWNER/REPOSITORY --exit-status; then
>   echo 'run passed'
> else
>   echo 'run failed or could not be watched' >&2
>   exit 1
> fi

5. Diagnose the common traps

The wrong repository: an ID only makes sense in its repository context. Keep --repo when a script may run outside the checkout, or when several repositories are involved.

The wrong number: a workflow run has a numeric database ID and may also show a display run number. Take the value shown as ID by gh run list. If unsure, list the run again with JSON fields and inspect the result:

$ gh run list --repo OWNER/REPOSITORY --limit 1 --json databaseId,status,conclusion
[{"databaseId":1234567,"status":"completed","conclusion":"success"}]

Stopping early: pressing Ctrl-C stops your local watch. It does not cancel the GitHub Actions run, and you can watch the same ID again later: do not use a cancellation command as a substitute for interrupting a display.

Authentication: the watch command needs permission to read the checks associated with the run. Fine-grained personal access tokens are not supported here because the installed help says the required checks:read permission cannot currently be created for that token type. Use the supported GitHub CLI authentication arrangement for the account and repository, and keep credentials out of scripts and process arguments.