| name | github |
| description | Work with GitHub through the `gh` CLI — read and file issues, open and review pull requests, watch CI runs, inspect diffs and releases, and call the REST/GraphQL API. Use whenever a task mentions a GitHub issue, PR, repository, workflow run, or a github.com URL. |
GitHub
Agent Directive
Use gh via the bash tool for anything on GitHub. Prefer it over raw git
for anything server-side (issues, PRs, runs, releases) and over hand-rolled
curl calls to api.github.com — gh already carries the auth, pagination,
and JSON shaping.
gh runs non-interactively here. Never invoke a command that would open an
editor, a pager, or a browser: always pass the content on the command line,
and set --web=false where a command offers it.
Reading
gh issue list --state open --limit 20
gh issue view 742 --comments
gh pr list --state open
gh pr view 750 --json title,body,state,mergeable,reviewDecision
gh pr diff 750
gh run list --branch main --limit 5
gh run view 30575448224 --log-failed
gh release view v1.2.0
--json <fields> turns any list or view into structured output — always
prefer it when you are going to parse the result. Pair it with --jq only if
jq is available; otherwise read the JSON directly.
gh pr list --json number,title,author --limit 50
gh api repos/{owner}/{repo}/commits --paginate
Writing
These change state on a real, shared service. Read the rules below before
using any of them.
gh issue create --title "..." --body "..."
gh issue comment 742 --body "..."
gh pr create --base main --head my-branch --title "..." --body "..."
gh pr comment 750 --body "..."
gh pr ready 751
Rules
- Ask before anything irreversible or outward-facing. Merging, closing,
force-pushing, deleting a branch, publishing a release, and editing someone
else's issue or PR all need explicit confirmation first. Creating a draft PR
or leaving a comment on your own work does not.
- Long bodies go through a file, not a shell string:
gh pr create --body-file /tmp/body.md. Backticks and $(...) in a
double-quoted --body are executed by the shell before gh ever sees them
— this has produced real, embarrassing commit and PR text.
- A draft PR is skipped by some CI setups. If checks never start, look at
the draft state before assuming CI is broken.
- Report failures verbatim. If
gh returns 403, 404, or a rate-limit
error, say exactly what it said. Never retry in a loop and never invent the
contents of an issue, PR, or run you could not read.
- Do not fabricate identifiers. If you need an issue or PR number you do
not have, list and find it.
Authentication
Bakin configures auth in one of two ways, and you do not need to set either
up:
- A
GH_TOKEN stored in Bakin's Settings → Integrations & Keys, injected
into the environment. gh picks it up automatically.
- Or nothing at all, in which case
gh uses the login the operator already
did on this machine (gh auth login).
Check with gh auth status. If gh reports it is not authenticated, or that
the token lacks a scope, report that honestly and stop — the fix belongs to
the operator in Bakin's settings, not to you. Never write a token into a
file, a command you echo, or a commit.
