github

# GitHub CLI Operations IMPORTANT: Always use `gh` CLI for ALL GitHub interactions. Never use `curl` with GitHub API directly — `gh api` handles authentication, pagination, and rate limiting automatically. ## Quick Reference | Category | Command | Details | |---|---|---| | Auth | `gh auth status` | Check login state | | Auth | `gh auth login` | Interactive login | | Repos | `gh repo view` | View current repo | | Repos | `gh repo create NAME` | Create new repo | | Repos | `gh repo clone OWNER/REPO` | Clone a repo | | Repos | `gh repo fork OWNER/REPO` | Fork a repo | | Issues | `gh issue list --limit 10` | [references/issues.md](references/issues.md) | | Issues | `gh issue create --title T --body B` | Create issue | | PRs | `gh pr list --limit 10` | [references/pull-requests.md](references/pull-requests.md) | | PRs | `gh pr create --title T --body B` | Create PR | | PRs | `gh pr merge N` | Merge PR | | Search | `gh search repos "QUERY"` | [references/search.md](references/search.md) | | Releases | `gh release list --limit 5` | [references/releases.md](references/releases.md) | | Workflows | `gh run list --limit 10` | [references/workflows.md](references/workflows.md) | | API | `gh api repos/OWNER/REPO` | [references/api.md](references/api.md) | | Gists | `gh gist list --limit 10` | [references/gists.md](references/gists.md) | | Labels | `gh label list` | List repo labels | | Install | `brew install gh` | [references/install.md](references/install.md) | ## Authentication ```bash # Interactive login (browser or token) gh auth login # Login with token (non-interactive, CI) echo "$TOKEN" | gh auth login --with-token # Check auth status gh auth status # Switch between accounts gh auth switch # Refresh token scopes gh auth refresh --scopes read:project # Logout gh auth logout ``` Environment variable auth (overrides stored credentials): | Variable | Purpose | |---|---| | `GH_TOKEN` / `GITHUB_TOKEN` | Auth token for github.com | | `GH_ENTERPRISE_TOKEN` | Auth token for GitHub Enterprise | ## Repository Workflows ```bash # Create a new repo (interactive) gh repo create my-project --public --clone # Create from template gh repo create my-project --template OWNER/TEMPLATE --clone --public # Fork and clone gh repo fork OWNER/REPO --clone # Clone gh repo clone OWNER/REPO # View repo details gh repo view OWNER/REPO gh repo view OWNER/REPO --json name,description,stargazerCount # Archive / delete gh repo archive OWNER/REPO gh repo delete OWNER/REPO --yes # Set default repo (for commands outside a git directory) gh repo set-default OWNER/REPO # Rename gh repo rename NEW-NAME ``` ## Pull Request Workflow ```bash # Create PR (current branch -> default branch) gh pr create --title "Title" --body "Description" # Create PR with specific base gh pr create --base develop --title "Title" --body "Body" # Create draft PR gh pr create --draft --title "WIP: Feature" --body "Body" # List open PRs gh pr list --limit 20 # View PR details gh pr view 123 gh pr view 123 --json state,reviews,checks # Check PR status (checks, reviews) gh pr checks 123 # Review a PR gh pr review 123 --approve gh pr review 123 --request-changes --body "Fix X" gh pr review 123 --comment --body "Looks good" # Merge PR gh pr merge 123 --squash --delete-branch gh pr merge 123 --rebase gh pr merge 123 --merge # Close without merging gh pr close 123 # View PR diff gh pr diff 123 # Checkout a PR locally gh pr checkout 123 # Edit PR metadata gh pr edit 123 --add-label "bug" --add-reviewer "user" gh pr edit 123 --milestone "v1.0" # View PR comments gh api repos/OWNER/REPO/pulls/123/comments ``` ## Issue Triage ```bash # List open issues gh issue list --limit 20 gh issue list --label "bug" --assignee "@me" gh issue list --state closed --limit 10 # Create issue gh issue create --title "Bug: X" --body "Steps to reproduce..." gh issue create --label "bug,critical" --assignee "@me" # View issue gh issue view 456 gh issue view 456 --json title,body,labels,comments # Close / reopen gh issue close 456 --reason "completed" gh issue reopen 456 # Edit issue gh issue edit 456 --add-label "priority:high" --milestone "v2.0" # Transfer issue to another repo gh issue transfer 456 OWNER/OTHER-REPO # Pin / unpin gh issue pin 456 gh issue unpin 456 # Comment on issue gh issue comment 456 --body "Working on this" # List issue comments gh api repos/OWNER/REPO/issues/456/comments ``` ## Search Never use `curl` or browser for GitHub search. Use `gh search` subcommands: ```bash # Search repositories gh search repos "cli language:rust stars:>100" --limit 10 --sort stars # Search code gh search code "fn parse language:rust repo:OWNER/REPO" --limit 10 gh search code "filename:Cargo.toml org:ORG" --limit 10 # Search issues gh search issues "repo:OWNER/REPO is:open label:bug" --limit 10 # Search pull requests gh search prs "is:merged author:USER" --limit 10 --sort updated # Search commits gh search commits "fix memory repo:OWNER/REPO" --limit 10 --sort committer-date ``` Key qualifiers: `repo:`, `org:`, `language:`, `filename:`, `path:`, `extension:`, `is:`, `label:`, `author:`, `stars:`, `created:`, `in:`. Full qualifier reference: [references/search.md](references/search.md) ## Output Formatting ### JSON output (`--json`) Select specific fields to reduce output size: ```bash gh pr list --json number,title,state gh issue list --json number,title,labels,assignees gh repo view --json name,description,stargazerCount gh pr view 123 --json commits,files,reviews ``` ### JQ filtering (`--jq`) Filter and transform JSON output: ```bash # Get just PR titles gh pr list --json title --jq '.[].title' # Filter issues by label gh issue list --json number,title,labels \ --jq '.[] | select(.labels | any(.name == "bug"))' # Count open PRs by author gh pr list --json author --jq '[.[].author.login] | group_by(.) | map({(.[0]): length}) | add' # Extract specific nested fields gh pr view 123 --json reviews --jq '.reviews[].state' ``` ### Go templates (`--template`) ```bash gh issue list --template '{{range .}}#{{.number}} {{.title}}{{"\n"}}{{end}}' gh pr list --template '{{range .}}{{.number}}\t{{.state}}\t{{.title}}{{"\n"}}{{end}}' ``` ## API Access Use `gh api` for any GitHub REST or GraphQL endpoint not covered by built-in commands: ```bash # REST API (automatically authenticated) gh api repos/OWNER/REPO gh api repos/OWNER/REPO/contributors --paginate # POST with JSON body gh api repos/OWNER/REPO/issues -f title="Bug" -f body="Description" # GraphQL gh api graphql -f query='{ viewer { login } }' # With JQ filtering gh api repos/OWNER/REPO/releases --jq '.[0].tag_name' # Paginate automatically gh api repos/OWNER/REPO/issues --paginate --jq '.[].title' ``` Full API reference: [references/api.md](references/api.md) ## CI/CD and Workflows ```bash # List workflow runs gh run list --limit 10 gh run list --workflow build.yml --limit 5 # View run details gh run view RUN_ID gh run view RUN_ID --log # Watch a run in progress gh run watch RUN_ID # Rerun a failed run gh run rerun RUN_ID gh run rerun RUN_ID --failed # Trigger a workflow dispatch gh workflow run build.yml --ref main # List workflows gh workflow list # Manage repo secrets gh secret set SECRET_NAME --body "value" gh secret list # Manage repo variables gh variable set VAR_NAME --body "value" gh variable list # View action cache gh cache list gh cache delete KEY ``` Full workflows reference: [references/workflows.md](references/workflows.md) ## Environment Variables | Variable | Description | |---|---| | `GH_TOKEN` | Auth token (overrides stored credentials) | | `GITHUB_TOKEN` | Alternative to `GH_TOKEN` | | `GH_ENTERPRISE_TOKEN` | Token for GitHub Enterprise | | `GH_HOST` | Default GitHub hostname | | `GH_REPO` | Default repo in `[HOST/]OWNER/REPO` format | | `GH_EDITOR` | Editor for interactive commands | | `GH_BROWSER` | Browser for `gh browse` | | `GH_PAGER` | Pager for output (default: system pager) | | `GH_DEBUG` | Set to `1` or `api` for debug output | | `GH_NO_UPDATE_NOTIFIER` | Set to `1` to disable update notifications | | `GH_CONFIG_DIR` | Config directory (default: `~/.config/gh`) | | `NO_COLOR` | Disable color output | ## Configuration ```bash # View current config gh config list # Set default editor gh config set editor vim # Set default git protocol gh config set git_protocol ssh # Set default browser gh config set browser "firefox" # Set prompt (disable interactive prompts) gh config set prompt disabled # Per-host config gh config set git_protocol ssh --host github.example.com ``` ## Extensions ```bash # Browse available extensions gh ext browse # Install an extension gh ext install OWNER/gh-EXTENSION # List installed extensions gh ext list # Upgrade extensions gh ext upgrade --all gh ext upgrade OWNER/gh-EXTENSION # Remove an extension gh ext remove OWNER/gh-EXTENSION ``` ## Token-Saving Patterns - Always use `--limit N` or `| head -N` to cap output - Use `--json FIELD1,FIELD2` to select only needed fields - Use `--jq 'EXPRESSION'` to filter JSON responses - Combine `--json` and `--jq` to get minimal output in one call - Use `gh api --paginate` instead of manual pagination loops - Use `--web` to open in browser instead of fetching large content - Prefer `gh pr checks` over `gh run list` when checking a specific PR