mathews-tom/github

GitHub

All GitHub operations use the gh CLI. Prefer --json with --jq for structured, parseable output. Use --repo owner/repo when not inside a git repository with a configured remote. Use --web to open any resource in the browser.

Prerequisites and Auth

Installation

| Platform | Command | | ------------- | --------------------------- | | macOS | brew install gh | | Debian/Ubuntu | sudo apt install gh | | Windows | winget install GitHub.cli |

Authentication

gh auth login           # interactive OAuth login
gh auth status          # check current auth and active account

Required OAuth Scopes

| Scope | Grants Access To | | ------------- | -------------------------------------------- | | repo | Private repos, issues, PRs, commits, status | | read:org | Org membership, team listing | | workflow | Trigger and manage GitHub Actions workflows | | gist | Create and manage gists | | delete_repo | Delete repositories (not granted by default) | | admin:org | Manage org settings, teams, members | | project | Read/write access to ProjectV2 boards |

Add missing scopes without re-authenticating from scratch:

gh auth refresh --scopes repo,read:org,workflow

---

Reference Routing

| User intent | Load | | --------------------------------------------------------------- | ------------------------------------ | | Create/list/view/edit/close issues, add comments | references/issues.md | | Create/list/view/review/merge/edit/close pull requests | references/pull-requests.md | | List runs, view logs, trigger/rerun/watch workflows, artifacts | references/ci-actions.md | | Create/fork/clone/view/edit/archive/delete repositories | references/repos.md | | Create/list/view/edit/upload/delete releases | references/releases.md | | Search repos, issues, PRs, code, commits | references/search.md | | Raw REST/GraphQL via gh api, pagination, rate limit | references/api.md | | GraphQL cost model, bulk queries, mutations, rate limits | references/graphql-queries.md | | Multi-step workflow recipes (PR lifecycle, CI triage, releases) | references/automation-workflows.md | | Create/list/view/edit/delete gists | references/gists.md | | List orgs, teams, members | references/orgs.md |

Workflow Pattern

1. Identify user intent from the routing table above.
2. Load the matching references/<file>.md for command syntax and examples.
3. Execute the gh command with --repo owner/repo and --json/--jq as needed.
4. On error, consult the Error Handling table below.

---

Error Handling

| Error | Cause | Resolution | | ----------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | HTTP 401 Unauthorized | Token expired or revoked | Run gh auth login to re-authenticate | | HTTP 403 Forbidden | Insufficient permissions or rate limited | Check gh auth status for scopes; check gh api rate_limit | | HTTP 404 Not Found | Repo does not exist, is private without repo scope, or resource deleted | Verify repo name; run gh auth refresh --scopes repo | | HTTP 422 Unprocessable Entity | Invalid payload — missing required field, validation error | Check request body fields match API schema | | HTTP 429 Too Many Requests | REST rate limit exceeded (5000 req/hr authenticated) | Wait for X-RateLimit-Reset timestamp; reduce request frequency | | GraphQL rate limit exceeded | Used more than 5000 points/hr | Reduce query complexity or wait; see references/graphql-queries.md | | "no git remotes found" | Running gh outside a git repo without --repo | Add --repo owner/repo to the command | | Insufficient OAuth scopes | Token lacks required scope for the operation | Run gh auth refresh --scopes scope1,scope2 | | Duplicate issue/PR title | Not a real error — GitHub allows duplicates, but check before creating | Search with gh issue list or gh pr list first | | Archived repo blocks writes | Repo is archived; all write operations fail | Unarchive with gh repo edit owner/repo --archived=false or use a different repo |

Enable debug logging to see raw HTTP requests and responses:

GH_DEBUG=api gh pr list --repo owner/repo

---

Calibration Rules

1. Prefer --json over parsing text output. Text output formats are unstable across gh versions. Always use --json field1,field2 to get machine-readable output.
2. Use --jq to minimize output before processing. Filter at the source rather than piping large JSON blobs to external tools. --jq runs server-side and reduces data transferred.
3. Prefer higher-level commands over raw API. Use gh issue create instead of gh api repos/.../issues -X POST. High-level commands handle auth, pagination, and error formatting automatically.
4. Use --repo consistently when outside a git directory. Never rely on implicit repo detection in scripts or CI environments. Always pass --repo owner/repo explicitly.
5. Use GraphQL only for nested or bulk data. For single-resource fetches and mutations with simple payloads, REST is faster to write, easier to debug, and predictable under rate limits.

---

Limitations

• Network required — all gh commands require internet access; no offline mode.
• GraphQL point budget — 5000 points/hr for authenticated users. Complex queries with high first/last values consume points faster. See references/graphql-queries.md.
• Secrets are write-only — gh secret set works, but there is no gh secret get. Secret values cannot be retrieved after creation.
• Org admin operations — managing org settings, teams, and SAML requires the admin:org scope, which is not granted by default.
• Artifact retention — workflow artifacts are retained for 90 days by default. Expired artifacts cannot be downloaded.