majiayu000 GitHub CLI Agentic Patterns
Optimized gh commands for AI agent consumption using JSON output and structured field selection.
Core Principle
Always use --json <fields> for machine-readable output. The --jq filter is built-in (no jq installation required).
Pull Request Operations
Check Status
# Get all check statuses
gh pr checks $PR_NUMBER --json name,state,conclusion,detailsUrl
# Filter to failed only
gh pr checks $PR_NUMBER --json name,state,conclusion --jq '.[] | select(.conclusion == "FAILURE")'
Fields: name, state, conclusion, detailsUrl, startedAt, completedAt
PR Details
# Essential PR info
gh pr view $PR_NUMBER --json number,title,state,mergeable,statusCheckRollup
# Full context
gh pr view $PR_NUMBER --json number,title,body,state,author,labels,assignees,reviewDecision,mergeable,statusCheckRollup
Key Fields:
| Field | Description |
|---|---|
mergeable |
MERGEABLE, CONFLICTING, UNKNOWN |
reviewDecision |
APPROVED, CHANGES_REQUESTED, REVIEW_REQUIRED |
statusCheckRollup |
Array of check statuses |
List PRs
# Open PRs
gh pr list --json number,title,author,labels
# PRs by author
gh pr list --author @me --json number,title,state
# PRs needing review
gh pr list --search "review-requested:@me" --json number,title
Workflow Run Operations
Run Details
# Get run status with jobs
gh run view $RUN_ID --json conclusion,status,jobs,createdAt,updatedAt
# List recent runs
gh run list --json databaseId,status,conclusion,name,createdAt -L 10
Status Values: queued, in_progress, completed
Conclusion Values: success, failure, cancelled, skipped, neutral
Watch Run Until Completion
# Watch and wait for run to complete (blocking, no timeout needed)
gh run watch $RUN_ID --compact --exit-status
# Find and watch latest run
RUN_ID=$(gh run list -L 1 --json databaseId --jq '.[0].databaseId')
gh run watch $RUN_ID --compact --exit-status
See gh-workflow-monitoring skill for comprehensive workflow watching patterns.
Failed Logs
# Get only failed step logs (most useful for debugging)
gh run view $RUN_ID --log-failed
# Full logs (verbose)
gh run view $RUN_ID --log
Workflow Triggers
# Trigger workflow manually
gh workflow run $WORKFLOW_NAME
# Trigger with inputs
gh workflow run $WORKFLOW_NAME -f param1=value1 -f param2=value2
# List workflows
gh workflow list --json name,state,path
Issue Operations
Issue Details
# Full issue context
gh issue view $ISSUE_NUMBER --json number,title,body,state,labels,assignees,comments
# Minimal
gh issue view $ISSUE_NUMBER --json number,title,state,labels
List Issues
# Open issues
gh issue list --json number,title,labels,assignees
# By label
gh issue list --label "bug" --json number,title
# Assigned to me
gh issue list --assignee @me --json number,title,state
Repository Operations
# Get repo info
gh repo view --json nameWithOwner,defaultBranchRef,description
# Just owner/name
gh repo view --json nameWithOwner --jq '.nameWithOwner'
API Direct Access
For operations not covered by subcommands:
# Get specific data
gh api repos/{owner}/{repo}/actions/runs --jq '.workflow_runs[:5]'
# With pagination
gh api repos/{owner}/{repo}/issues --paginate --jq '.[].number'
Agentic Optimizations
| Context | Command |
|---|---|
| CI diagnosis | gh pr checks $N --json name,state,conclusion,detailsUrl |
| Get failure logs | gh run view $ID --log-failed |
| PR merge status | gh pr view $N --json mergeable,reviewDecision,statusCheckRollup |
| Quick issue list | gh issue list --json number,title,labels -L 10 |
| Workflow trigger | gh workflow run $NAME |
Error Handling in Context
Always include fallback for context expressions:
- PR checks: !`gh pr checks $PR --json name,state,conclusion 2>/dev/null || echo "[]"`
- Run status: !`gh run view $ID --json status,conclusion 2>/dev/null || echo "{}"`
Field Reference
PR Fields
number, title, body, state, author, labels, assignees, reviewDecision, mergeable, statusCheckRollup, headRefName, baseRefName, isDraft, url, createdAt, updatedAt
Issue Fields
number, title, body, state, author, labels, assignees, comments, milestone, url, createdAt, updatedAt, closedAt
Run Fields
databaseId, name, status, conclusion, jobs, createdAt, updatedAt, url, headBranch, headSha, event
Job Fields (within runs)
name, status, conclusion, startedAt, completedAt, steps