avifenesh/github

Skill: github

GitHub Operations

Always use cairn.shell with gh CLI for GitHub operations. The gh CLI is authenticated and available at /usr/bin/gh. It covers everything GitHub exposes via API — REST and GraphQL. You do NOT need a dedicated GitHub API tool. gh IS the API tool.

Decision: shell vs webFetch

• Never use cairn.webFetch for GitHub API endpoints — it's unauthenticated, rate-limited to 60 req/hr, and returns raw JSON.
• Always use cairn.shell with gh commands. Authenticated (5000 req/hr), formatted output.
• Never use cairn.googleQuery or cairn.googleExecute for GitHub operations — those are Google Workspace tools (Gmail, Calendar, Drive). They do not understand gh commands.

Permissions

Identity

You are authenticated as agent-cairn on GitHub. Your PRs and commits are attributed to this identity.

• You have Write access to Avi's repos — you can push branches and create PRs
• You CANNOT merge PRs on Avi's repos — branch protection requires owner approval
• On your own repos (owned by agent-cairn), you have full permissions

Auto-execute (no approval needed)

• All read operations: list, view, search, diff, checks, api with GET
• gh pr create — always draft PRs on repos you don't own
• gh pr edit — on your own PRs only (title, body)
• gh pr ready — marking your own PRs as ready for review
• gh pr comment — on your own PRs (e.g. responding to review feedback)
• gh run view --log — reading CI logs

Require explicit approval from Avi

• gh pr merge — blocked by policy. Only Avi can merge on his repos.
• gh release create — releases are public-facing
• gh issue create / gh issue edit / gh issue close / gh issue comment — affects external project tracking
• gh workflow run — dispatching workflows can have side effects
• gh run rerun — re-triggering CI jobs
• Any gh api call with --method POST|PUT|PATCH|DELETE that modifies external state

Never

• Push to main/master — blocked by shell policy and cairn.gitRun
• Merge PRs on repos you don't own — blocked by GitHub branch protection
• Switch GitHub auth identity (gh auth login/switch) — blocked by shell policy
• Delete repos, branches on repos you don't own, or any irreversible destructive action
• Approve PRs you didn't review
• Modify issues or PRs owned by Avi or others without being asked
• Use cairn.googleQuery, cairn.googleExecute, or the gog CLI for GitHub — those are Google Workspace tools only

gh api — Raw REST & GraphQL access

Any GitHub REST endpoint or GraphQL query.

# REST
gh api <endpoint> [--method METHOD] [--paginate] [--jq '...'] [--field key=value] [--input file.json] [--header 'Accept: ...']
# GraphQL
gh api graphql -f query='...' -F owner=... -F name=...

Flags: --method, --input, --jq, --paginate, --slurp, --field/-F (typed), --raw-field/-f (string), --header/-H, --preview

Built-in commands

PRs

gh pr list [-R owner/repo] [--limit N] [--state open|closed|merged|all] [--author LOGIN] [--head BRANCH] [--base BRANCH] [--label LBL] [--search QRY]
gh pr view <number|url|branch> [-R owner/repo]
gh pr create --title "..." --body "..." [-R owner/repo]
gh pr checks <number> [-R owner/repo]
gh pr merge <number> --squash|--merge|--rebase [--delete-branch] [-R owner/repo]
gh pr review <number> --approve|--request-changes|--comment -b "..." [-R owner/repo]
gh pr diff <number> [-R owner/repo]
gh pr close <number> [-R owner/repo]
gh pr comment <number> -b "..." [-R owner/repo]
gh pr edit <number> --title "..." --body "..." [-R owner/repo]
gh pr ready <number> [-R owner/repo]
gh pr revert <number> [-R owner/repo]

Issues

gh issue list [-R owner/repo] [--limit N] [--state open|closed|all] [--author LOGIN] [--assignee LOGIN] [--label LBL] [--milestone NAME] [--search QRY]
gh issue view <number|url> [-R owner/repo]
gh issue create --title "..." --body "..." [-R owner/repo]
gh issue close <number> [-R owner/repo]
gh issue comment <number> -b "..." [-R owner/repo]
gh issue edit <number> --title "..." --body "..." [-R owner/repo]

Repos

gh repo view [owner/repo]
gh repo list <owner> [--limit N] [--visibility public|private|internal] [--source|--fork] [--language LANG] [--topic TOPIC] [--no-archived]
gh repo clone <owner/repo> [dir]

CI / Actions

gh run list [-R owner/repo] [--limit N] [--workflow WORKFLOW]
gh run view <run-id> [-R owner/repo] [--log] [--log-failed] [--verbose]
gh run watch <run-id> [-R owner/repo]
gh run rerun <run-id> [-R owner/repo]
gh workflow list [-R owner/repo]
gh workflow run <workflow> [-R owner/repo] [-f key=value]

Releases

gh release list [-R owner/repo]
gh release view <tag> [-R owner/repo]
gh release create <tag> [-R owner/repo] [--title "..."] [--notes "..."] [--draft]

Search

gh search repos|--issues|--prs|--code|--commits "<query>"
gh search repos --owner=agent-sh --limit 10
gh search issues "is:open label:bug" --repo owner/repo

Local git

• Use cairn.gitRun for local git commands (status, diff, log, branch, commit)
• Use cairn.shell with gh for all remote/interactive operations

Tips

• All commands accept -R owner/repo to target a repo (or set GH_REPO env var)
• --json field1,field2 outputs structured JSON on any list/view command
• --jq '.[].name' filters JSON output
• --paginate on gh api auto-follows next pages. Always use --paginate with --slurp when the --jq expression uses aggregations like group_by() or unique_by() that must operate on the full result set.
• Space gh api calls at least 2s apart. Never poll CI in tight loops — use sleep 30.