name: github description: Interact with GitHub through the `gh` CLI — issues, pull requests, CI runs, releases, search, and raw API queries. Use for any github.com or api.github.com task; `gh` is authenticated, reaches private repos, and returns structured JSON. compatibility: Requires the GitHub CLI (`gh`) installed and authenticated (`gh auth status`). Setup is documented in README.md in this directory. #

GitHub #

Use gh for GitHub work, not curl against api.github.com. It authenticates every request, reads private repositories, and formats its own output.

gh issue ...  gh pr ...  gh run ...  gh release ...  gh search ...  gh api ...

Discover specifics from the CLI: gh <command> --help prints examples plus the subcommand's valid --json fields, and gh help formatting covers --json/--jq/--template.

Habits that matter #

Say "me" with @me. Wherever a flag wants a login — --assignee, --add-assignee, --author — pass @me and let gh resolve it to whichever account is authenticated, personal or work, with no lookup round trip. Reach for gh api user --jq .login only when a literal login is unavoidable: telling the user which account is active, or a raw gh api path.
Target the repo explicitly. Inside a git checkout gh infers it; anywhere else pass --repo owner/repo on every command.
Project the output. --json number,title --jq '.[] | "#\(.number) \(.title)"' plus --limit, so a listing or log fits the result budget.
Read CI with --log-failed, which returns only the failed steps of a run.
Reach for gh api when a subcommand stops short, using a relative path: gh api repos/owner/repo/pulls/55 --jq '.state, .user.login'. --paginate follows Link headers; -f sends strings, -F typed values.
Confirm before writing. For issue and PR creation, comments, closes, merges, pushes, and reruns, state the exact target and body and get a yes first, especially on repositories the user does not own.

Presenting issues and PRs before submitting #

gh issue create and gh pr create publish under the user's name the moment they run, so neither is part of "just do it" — they follow the same approval as a merge.

Draft it, show it, wait. Present the payload formatted for reading, not as raw command arguments: the title on its own line, the body as rendered markdown (a fenced block only if the body itself contains fences), then one line each for labels, assignee (@me), and base branch. Then stop — only run the create command after an explicit yes, and apply any edits the user asks for first.
Assign to yourself with @me. No account guessing and no gh api user lookup: --assignee @me lands on whichever account gh is authenticated as.
Create PRs as drafts. Default to gh pr create --draft: it lets the user review the PR itself before anyone is pinged. Request reviewers only when it goes ready (gh pr edit <n> --add-reviewer ... alongside gh pr ready <n>), never at draft creation. Flipping the ready switch is usually the user's own move, but if they ask, run gh pr ready <n> for them.

Force pushing #

A force push rewrites history that a reviewer may already have read, so the default is: once a PR has been reviewed, never rewrite it.

# Check review state before rebasing, amending, or pushing --force to the PR branch
gh pr view <n> --json reviewDecision,reviews

Once a human has reviewed, add commits instead of rewriting. If reviews is non-empty, or reviewDecision is CHANGES_REQUESTED or APPROVED, push follow-up commits so the incremental diff and each anchored review comment survive. Squash at the end, or let the merge button squash.
An unreviewed, own-work PR is fair game. Empty reviews with REVIEW_REQUIRED means nobody has looked yet: rebasing onto the base branch or amending is safe.
Ask instead of guessing when reviews exist but the reviewer has asked for a rewrite, or when the repo requires linear history.
When it is authorized, git push --force-with-lease, never plain --force: it aborts if the remote moved since your last fetch instead of silently dropping someone's commits.
gh pr merge is not a force push. Prefer the platform's own merge/squash over rewriting the branch locally.