Gh CLI

GitHub CLI

Use native gh commands before custom API queries or polling scripts. Spend time on the first actionable failure, not on repeated status reads.

Fetch once, with a clear target

• Reuse the repository, PR number, head SHA, run ID, and job ID already known. Pass -R OWNER/REPO to PR/run commands outside the target repository. For gh api, put the repository in the endpoint; it has no -R flag.
• Prefer gh pr checks, gh run view, and gh run list over rebuilding them with REST or GraphQL. Check subcommand help instead of guessing flags or JSON fields.
• Select only needed --json fields and use --jq for a compact result. Filter lists by commit, workflow, event, or branch before increasing --limit. Do not fetch a list again to recover an ID it already returned.
• Use gh api for data the native command does not expose. Use --method GET with query fields; adding -f or -F otherwise changes the method to POST. Paginate when the task needs the full set, not just a recent sample.

Wait for checks, not a timer

For PR merge readiness, start this immediately:

gh pr checks NUMBER -R OWNER/REPO --required --watch --fail-fast

--required is the default scope for merge blockers. Omit it only when the user asks for all checks, or when the task explicitly covers non-required checks. Do not wait for advisory checks before handling a required failure. Still report a known regression caused by this change, even if it is optional.

• Never use sleep N && gh ... to wait for CI, including before a native watcher. Do not replace --watch with a shell/Python loop or recurring status tool calls.
• If a required failure is already known, read its log now. Do not start another watcher or wait for unrelated jobs to finish.
• Run one watcher per target in an attached async shell, or let a synchronous tool wait on that same process. Reuse its shell ID and completion notification. Do useful independent work, or end the turn until notified. Do not repeatedly call read_bash, start duplicate watchers, or delegate an agent just to wait.
• Keep watch output live and preserve its exit status. Do not pipe it through head/tail, redirect errors away, or append || true. A failed watcher is not necessarily a failed check: inspect its error before acting.
• Use the native refresh interval. Set --interval only for a concrete latency or rate-limit need, not as another arbitrary delay.

For one workflow run, when waiting for the whole run is the actual task:

gh run watch RUN_ID -R OWNER/REPO --exit-status --compact

gh run watch has no --fail-fast; --exit-status reports failure when the run finishes. It is not a substitute for PR required-check fail-fast watching.

Interpret the result

For a structured snapshot, separate from watch mode:

gh pr checks NUMBER -R OWNER/REPO --required \
  --json name,bucket,state,link,workflow

• --watch cannot be combined with --json. In plain output, exit code 8 means pending checks. With --json, a successful fetch can return zero even when checks failed; inspect bucket, not just the process exit code.
• A cancelled check is not a pass. Watch mode can exit zero with cancelled checks, and --fail-fast does not treat cancellation as failure. Inspect the final states before claiming success. Keep skipped/neutral results distinct from passed tests.
• "No checks reported" and "no required checks reported" are not evidence of passing CI. Inspect the PR head, workflow triggers, and the PR's actual base-branch rules to distinguish missing checks from no required checks. Do not silently drop --required after an error.
• An auth, permission, API, or network error is not a CI result. Report it. Do not hide it in a retry loop or infer success from missing data.
• Native watching covers reported checks, not every push, review, or merge. Use gh wait below for those events. For other states with no watcher, make one focused read per scheduled pass if a schedule is already authorized. Stop it when the goal is met or the PR is closed. Do not invent an endless polling loop.

Wait for PR changes, merges, or commits

./setup links gh wait from gh/extensions/ and removes this checkout's links to the retired push/review extensions. Use gh wait instead of writing a polling loop or repeatedly reading PR status. Run one watcher per target in an attached async shell, or wait on the same synchronous process. Reuse its shell ID and completion notification, as with CI watchers. It checks immediately, then every 30 seconds, and prints nothing while waiting.

Any PR change or default-branch commit

gh wait NUMBER
gh wait https://github.com/OWNER/REPO/pull/NUMBER
gh wait

With a PR number, URL, or branch, gh wait takes a snapshot and exits on the next observed change: PR metadata updates, title/body edits, head/base changes, draft status, or review changes. Reviews are read across all pages, so changes to older reviews also count. It compares snapshots, not an event stream: changes reverted between polls can be missed. It does not watch CI checks or guarantee detection of every merge-queue transition.

With no argument, it uses the current branch's PR. On the repository's default branch (main, or its configured name), it instead waits for the remote branch head to differ from local HEAD at startup. An already different remote head counts, even if local HEAD is ahead or has diverged. It does not fetch, pull, or change the checkout. Update the checkout before starting another wait if you want to use the new head as the baseline. Detached HEAD requires an explicit PR.