gh-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
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:

```bash
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:

```bash
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

```bash
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.

### Completed merge

From caarlos0/dotfiles, MIT.

More from caarlos0/dotfiles