github-cli-patterns

name	github-cli-patterns
description	Use when working with gh CLI. Provides patterns for PRs, issues, reviews, and repository operations.
version	1.0.0
author	JacobPEvans

GitHub CLI Patterns

Common GitHub CLI (gh) command patterns. Single source of truth to reduce duplication across commands and agents.

PR Operations

List and View

# List: gh pr list [--state STATE] [--author USER] [--label LABEL] [--limit N] [--json FIELDS]
gh pr list --state open --json number,title,headRefName
gh pr list --author @me --state open --json number,title,mergeable,statusCheckRollup

# View: gh pr view <PR_NUMBER> [--json FIELDS]
gh pr view <PR_NUMBER> --json title,body,state,mergeable
gh pr view <PR_NUMBER> --json number,title,state,mergeable,statusCheckRollup,reviews,reviewDecision,headRefName
gh pr view <PR_NUMBER> --json headRefName --jq '.headRefName'  # Get branch name

Create

# Template: gh pr create [--title TEXT] [--body TEXT] [--draft] [--base BRANCH]
gh pr create --fill  # Auto-fill from commits
gh pr create --draft --title "WIP: Feature" --body "Not ready for review"
gh pr create --base develop --title "Hotfix" --body "Emergency fix"

Check Status

gh pr checks <PR_NUMBER>  # View status
gh pr checks <PR_NUMBER> --watch  # Wait for completion
gh pr checks <PR_NUMBER> --watch --fail-fast  # Exit on first failure

Other Operations

gh pr checkout <PR_NUMBER>  # Checkout locally
gh pr diff <PR_NUMBER>  # Show changes
gh pr view <PR_NUMBER> --json files --jq '.files[].path'  # Get changed files

Issue Operations

# List: gh issue list [--state STATE] [--label LABEL] [--assignee USER] [--limit N] [--json FIELDS]
gh issue list --state open --json number,title,labels,state,createdAt
gh issue list --search "-label:ai:created" --limit 20  # Exclude AI-created

# View: gh issue view <ISSUE_NUMBER> [--json FIELDS]
gh issue view <ISSUE_NUMBER> --json title,body,labels,comments

# Create: gh issue create [--title TEXT] [--body TEXT] [--label LABELS]
gh issue create --title "Bug" --body "Description" --label "bug,priority:high"
gh issue create --title "..." --body "..." --label "ai:created"  # AI-created (requires human review)

# Close: gh issue close <ISSUE_NUMBER> [--comment TEXT]
gh issue close <ISSUE_NUMBER> --comment "Fixed in PR #123"

# Comment
gh issue comment <ISSUE_NUMBER> --body "Comment text"

Review Operations

# Submit review
gh pr review <PR_NUMBER> --approve [--body TEXT]
gh pr review <PR_NUMBER> --request-changes --body "Please address..."
gh pr review <PR_NUMBER> --comment --body "Looks good overall"

# View reviews
gh pr view <PR_NUMBER> --json reviews,reviewDecision

# Add comment
gh pr comment <PR_NUMBER> --body "Comment text"

# Line-level comments (via API)
gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments \
  -f body="Comment" -F commit_id="<SHA>" -F path="file.js" -F line=42

Repository Operations

# View current repo
gh repo view --json nameWithOwner,description,defaultBranchRef
gh repo view --json nameWithOwner --jq '.nameWithOwner'  # Get owner/repo
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'  # Get default branch

# List repos
gh repo list <USERNAME> --limit 100 --json name,description,updatedAt

Workflow and Check Operations

# List runs
gh run list --limit 20

# View run
gh run view <RUN_ID>  # Details
gh run view <RUN_ID> --log  # Logs
gh run watch <RUN_ID>  # Wait for completion

# Rerun
gh run rerun <RUN_ID> --failed  # Failed jobs only
gh run rerun <RUN_ID>  # Entire workflow

API Operations

For GraphQL operations, use the github-graphql skill.

IMPORTANT: gh pr view --json does NOT support reviewThreads. Use GraphQL instead:

# GraphQL (required for reviewThreads) - see github-graphql skill for full patterns
gh api graphql --raw-field 'query=query { repository(owner: "{OWNER}", name: "{REPO}") { pullRequest(number: {NUMBER}) { reviewThreads(last: 100) { ... } } } }'

# REST API
gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>
gh api repos/<OWNER>/<REPO>/issues/<ISSUE_NUMBER>

JSON Processing

# Extract field: --jq '.field'
gh pr view <PR_NUMBER> --json state --jq '.state'

# Extract array: --jq '.[] | "\(.field1): \(.field2)"'
gh pr list --json number,title --jq '.[] | "\(.number): \(.title)"'

# Filter: --jq '.[] | select(.field == "VALUE") | .field'
gh pr list --json number,state --jq '.[] | select(.state == "OPEN") | .number'

# Count: --jq '. | length'
gh pr list --json number --jq '. | length'

Common Patterns

Check PR Merge-Readiness

gh pr view <PR_NUMBER> --json state,mergeable,statusCheckRollup,reviewDecision

STATE=$(gh pr view <PR_NUMBER> --json mergeable --jq '.mergeable')
if [ "$STATE" = "MERGEABLE" ]; then echo "Ready to merge"; fi

Get PR Author

gh pr view <PR_NUMBER> --json author --jq '.author.login'

Watch CI with Exit Code

gh pr checks <PR_NUMBER> --watch
if [ $? -eq 0 ]; then echo "Passed"; else echo "Failed"; fi

Authentication

gh auth status  # Check auth (safe for automation)
gh auth login  # Login interactively

Error Handling

Error	Meaning	Solution
HTTP 404: Not Found	PR/issue doesn't exist	Verify number
HTTP 401: Unauthorized	Not authenticated	Run gh auth login
HTTP 403: Forbidden	Insufficient permissions	Check repo access
Resource not found	Invalid owner/repo	Verify repository name
GraphQL error	Invalid query	Check syntax

Best Practices

1. Use --json for programmatic parsing
2. Use jq for extraction, not text parsing
3. Check auth before operations: gh auth status
4. Use specific field queries to reduce data transfer
5. Use --watch for long-running ops
6. Handle errors with exit code checking
7. Use --limit when listing to control size
8. Filter at query time when possible

Related Skills

• github-graphql - GraphQL query patterns
• pr-health-check - PR status validation
• pr-thread-resolution-enforcement - Review thread resolution