davesnx/setup/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 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 and follow it for unresolved merge, rebase, or cherry-pick conflicts. This mode uses Git directly and does not require a GitHub PR.

Scripts

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.