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

# 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

# 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

# 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

# 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:

# 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:

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:

# 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)

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:

# 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

# 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

# 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

# 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bug-ops
• Source: bug-ops/zeph
• License: MIT
• Homepage: https://bug-ops.github.io/zeph/

Install and usage instructions live in the source repository linked above.