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
- Identify user intent from the routing table above.
- Load the matching
references/<file>.md for command syntax and examples.
- Execute the
gh command with --repo owner/repo and --json/--jq as needed.
- 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
- Prefer
--json over parsing text output. Text output formats are unstable across gh versions. Always use --json field1,field2 to get machine-readable output.
- 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.
- 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.
- 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.
- 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.
1---2name: github3description: GitHub CLI operations via `gh` for issues, PRs, Actions, releases, and REST/GraphQL API with `--json`/`--jq` parsing. Triggers on: "create an issue", "submit a PR", "check CI status", "why did CI fail", "merge a PR", or pasted GitHub URLs.4---56# GitHub78All GitHub operations use the `gh` CLI. Prefer `--json` with `--jq` for structured,9parseable output. Use `--repo owner/repo` when not inside a git repository with a10configured remote. Use `--web` to open any resource in the browser.1112## Prerequisites and Auth1314### Installation1516| Platform | Command |17| ------------- | --------------------------- |18| macOS | `brew install gh` |19| Debian/Ubuntu | `sudo apt install gh` |20| Windows | `winget install GitHub.cli` |2122### Authentication2324```bash25gh auth login # interactive OAuth login26gh auth status # check current auth and active account27```2829### Required OAuth Scopes3031| Scope | Grants Access To |32| ------------- | -------------------------------------------- |33| `repo` | Private repos, issues, PRs, commits, status |34| `read:org` | Org membership, team listing |35| `workflow` | Trigger and manage GitHub Actions workflows |36| `gist` | Create and manage gists |37| `delete_repo` | Delete repositories (not granted by default) |38| `admin:org` | Manage org settings, teams, members |39| `project` | Read/write access to ProjectV2 boards |4041Add missing scopes without re-authenticating from scratch:4243```bash44gh auth refresh --scopes repo,read:org,workflow45```4647---4849## Reference Routing5051| User intent | Load |52| --------------------------------------------------------------- | ------------------------------------ |53| Create/list/view/edit/close issues, add comments | `references/issues.md` |54| Create/list/view/review/merge/edit/close pull requests | `references/pull-requests.md` |55| List runs, view logs, trigger/rerun/watch workflows, artifacts | `references/ci-actions.md` |56| Create/fork/clone/view/edit/archive/delete repositories | `references/repos.md` |57| Create/list/view/edit/upload/delete releases | `references/releases.md` |58| Search repos, issues, PRs, code, commits | `references/search.md` |59| Raw REST/GraphQL via `gh api`, pagination, rate limit | `references/api.md` |60| GraphQL cost model, bulk queries, mutations, rate limits | `references/graphql-queries.md` |61| Multi-step workflow recipes (PR lifecycle, CI triage, releases) | `references/automation-workflows.md` |62| Create/list/view/edit/delete gists | `references/gists.md` |63| List orgs, teams, members | `references/orgs.md` |6465## Workflow Pattern66671. Identify user intent from the routing table above.682. Load the matching `references/<file>.md` for command syntax and examples.693. Execute the `gh` command with `--repo owner/repo` and `--json`/`--jq` as needed.704. On error, consult the Error Handling table below.7172---7374## Error Handling7576| Error | Cause | Resolution |77| ----------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |78| HTTP 401 Unauthorized | Token expired or revoked | Run `gh auth login` to re-authenticate |79| HTTP 403 Forbidden | Insufficient permissions or rate limited | Check `gh auth status` for scopes; check `gh api rate_limit` |80| 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` |81| HTTP 422 Unprocessable Entity | Invalid payload — missing required field, validation error | Check request body fields match API schema |82| HTTP 429 Too Many Requests | REST rate limit exceeded (5000 req/hr authenticated) | Wait for `X-RateLimit-Reset` timestamp; reduce request frequency |83| GraphQL rate limit exceeded | Used more than 5000 points/hr | Reduce query complexity or wait; see `references/graphql-queries.md` |84| "no git remotes found" | Running `gh` outside a git repo without `--repo` | Add `--repo owner/repo` to the command |85| Insufficient OAuth scopes | Token lacks required scope for the operation | Run `gh auth refresh --scopes scope1,scope2` |86| 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 |87| 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 |8889Enable debug logging to see raw HTTP requests and responses:9091```bash92GH_DEBUG=api gh pr list --repo owner/repo93```9495---9697## Calibration Rules98991. **Prefer `--json` over parsing text output.** Text output formats are unstable across `gh` versions. Always use `--json field1,field2` to get machine-readable output.1002. **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.1013. **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.1024. **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.1035. **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.104105---106107## Limitations108109- **Network required** — all `gh` commands require internet access; no offline mode.110- **GraphQL point budget** — 5000 points/hr for authenticated users. Complex queries with111 high `first`/`last` values consume points faster. See `references/graphql-queries.md`.112- **Secrets are write-only** — `gh secret set` works, but there is no `gh secret get`.113 Secret values cannot be retrieved after creation.114- **Org admin operations** — managing org settings, teams, and SAML requires the `admin:org`115 scope, which is not granted by default.116- **Artifact retention** — workflow artifacts are retained for 90 days by default. Expired117 artifacts cannot be downloaded.
mathews-tom