github

# GitHub Raw `gh` first when you know the command; the scripts replace only the flows agents repeatedly get wrong. Scripts run TS directly (node ≥ 22.18, or ≥ 23.6 on older lines), no deps. ## Modes - **GitHub operations**: Use the optimized scripts and gotchas below for PR state, review threads, and GitHub Actions failures. - **Commit**: Mandatory before every `git commit`, unless the user says otherwise. Read [references/commit.md](references/commit.md) for message style, automated review of code diffs, staging, and final status checks. It applies the global agent rules for validation, isolation, and hooks. - **Merge conflicts**: Read [references/merge-conflicts.md](references/merge-conflicts.md) and follow it for unresolved merge, rebase, or cherry-pick conflicts. This mode uses Git directly and does not require a GitHub PR. ## Scripts | script | use for | |---|---| | `scripts/pr-snapshot.ts [pr] [-R o/r]` | full PR state in one call: meta, mergeability, checks, files, reviews, comments, thread counts. Use instead of hand-assembling `pr view --json` field sets or chaining view/checks/comments calls. | | `scripts/pr-threads.ts [pr] [-R o/r] [--all] [--author X] [--since ISO]` | the full review conversation: review bodies, issue comments, and unresolved inline threads (resolution state porcelain gh cannot get). Resolved/outdated threads are hidden by default, counted in the header; `--all` includes them. Read-only: never reply to or resolve threads unless explicitly told to. | | `scripts/ci-failures.ts [run-id] [--pr N] [--list] [-R o/r]` | failing checks → failing jobs/steps → log snippet each; full logs saved to files (paths printed); rg those instead of re-fetching. `--list [--workflow W] [-L n]` shows recent runs with conclusions; use it to find the failing run id instead of `gh run list --json` field sets. | Rule of thumb: pr-snapshot answers "what's the state of this PR", pr-threads answers "what did reviewers write". Neither replaces the other. All scripts: `--json` for structured output, `--help` for usage (includes the `--json` shape). Omit the PR number to use the current branch's PR. Default output is sized for context; pass `--full` only when a truncation marker (`[…+N chars]`) hides something you need. They exit 0 when the report succeeds even if CI is red or threads are unresolved. ## Gotchas (each one burned real sessions repeatedly) - `gh` and `git` run outside the Bash sandbox, with credentials, only when the call is the whole command. A pipe, `;`, `&&`, a redirect, `cd … &&`, or an env/export prefix runs the call inside the sandbox instead, where `~/.config/gh` and `~/.ssh` are denied (`gh auth login` or an SSH error). Run them alone; do not use `dangerouslyDisableSandbox` for this. - Never pipe gh into `head`: SIGPIPE can kill gh mid-write (spurious nonzero exit, shell-dependent) or silently truncate large output. Trim with `--jq '.[0:20]'` instead. - `gh pr diff` has no `--stat` and no positive pathspec (`--name-only` and `-e/--exclude` globs exist in gh ≥ 2.95). Per-file stats: `gh api 'repos/{owner}/{repo}/pulls/N/files' --jq '.[]|[.filename,.additions,.deletions]|@tsv'` Full diff: run `gh pr diff N` alone and read the output; a redirect makes gh run inside the sandbox, without credentials. - `gh pr checks` exits 1 = failing, 8 = pending by design; run it alone and read the table, not the exit code. - File at any ref, no base64 dance: `gh api 'repos/{owner}/{repo}/contents/PATH?ref=SHA' -H 'Accept: application/vnd.github.raw'` - `gh api` fills `{owner}/{repo}` from the cwd repo (`GH_REPO=o/r` overrides). Quote any api path containing `?` (zsh globs it), or use `-X GET -F per_page=100` (any `-f`/`-F` silently flips the request to POST without `-X GET`). - `--paginate` on any list endpoint (`/comments`, `/files`, `/reviews`); `--jq` already runs per page; don't add `--slurp`. - PR/comment bodies: `--body-file file.md` or a quoted heredoc. Never inline `--body "..."` containing backticks. - Field cheat-sheet: CI status on a PR = `statusCheckRollup` (pr view); steps live under `gh run view N --json jobs`; `gh search prs` fields ≠ `gh pr view` fields. - gh has no `-C`; pass `-R owner/repo` to every command, or cd first. - Branch rules live at `gh api 'repos/{owner}/{repo}/rulesets'` on modern repos; `/branches/main/protection` 404s unless classic protection is on AND you have admin ("Branch not protected" or plain "Not Found" both mean check rulesets; neither is a path error). - Branch drift: `gh api 'repos/{owner}/{repo}/compare/BASE...HEAD' --jq '{ahead_by,behind_by}'` - jq beyond one line: write the program to a file and `jq -f prog.jq`; inline zsh quoting breaks. - Don't sleep-poll runs or checks; `gh run watch ID` and `gh pr checks N --watch --fail-fast` exist; let the harness background them. Inside a `ci` skill watch, use its snapshot commands instead: a blocking watch there hides another provider's failure or a target change.