GitHub CLI (gh) — Workflow Guide
Contents
-
Behavior Guidelines
-
Core Workflows
-
JSON Scripting Patterns
-
Common Troubleshooting
-
References Loading Guide
Behavior Guidelines
-
Always check auth first — run gh auth status before complex operations. If not logged in, run gh auth login .
-
Prefer --json
- --jq for scripting — never parse human-readable gh output with grep/awk. Use structured JSON output.
-
Use --repo owner/repo for cross-repo ops — avoid cd-ing into directories when you can target repos directly.
-
Prefer gh pr create over manual push + web UI — it handles branch pushing, PR creation, and linking in one step.
-
Use --web to hand off to browser — when the user needs to fill forms or review visually, open in browser instead of guessing.
Core Workflows
Pull Requests
Create PR (interactive — fills title/body from commits)
gh pr create
Create with details
gh pr create --title "feat: add dark mode" --body "Closes #42"
Draft PR
gh pr create --draft --title "WIP: refactor auth"
Review and merge
gh pr review 123 --approve gh pr merge 123 --squash --auto
Check PR status
gh pr checks 123 gh pr list --author "@me"
Issues
Create issue
gh issue create --title "Bug: login fails" --label "bug" --assignee "@me"
List and filter
gh issue list --label "bug" --state open gh issue list --search "is:open label:bug created:>2024-01-01"
Close with comment
gh issue close 42 --comment "Fixed in #123"
CI / Actions
Watch current run
gh run watch
List failures
gh run list --branch main --status failure --limit 10
View logs
gh run view 12345678 --log
Re-run failed jobs
gh run rerun 12345678 --failed
Trigger workflow manually
gh workflow run deploy.yml --field environment=staging
JSON Scripting Patterns
List PR titles and numbers
gh pr list --json number,title --jq '.[] | "(.number): (.title)"'
Check if all PR checks passed
gh pr checks 123 --json name,state --jq '[.[] | select(.state != "SUCCESS")] | length == 0'
Find failing workflow runs
gh run list --json status,name,url --jq '.[] | select(.status == "failure") | .url'
Common Troubleshooting
Problem Fix
gh: command not found
brew install gh or see install guide
Not logged in
gh auth login
Permission denied gh auth refresh --scopes repo,workflow
Wrong repo targeted Add --repo owner/repo or cd into the repo
Stale token gh auth refresh
References Loading Guide
Situation Load
PR creation/review/merge details, issue templates, milestones references/prs-issues.md
Repo/Actions/Workflow management, secrets, caches references/repos-actions.md
Authentication, search syntax, API calls references/auth-search-api.md