gh-cli-agentic

# GitHub CLI Agentic Patterns ## When to Use This Skill | Use this skill when... | Use the alternative when... | |---|---| | Querying PRs, issues, runs, or repo metadata with `gh` and need JSON output | Use `git-cli-agentic` for porcelain-mode local git queries (status, diff, log) | | Inspecting PR checks, mergeable status, or fetching failed CI logs | Use `gh-workflow-monitoring` to actively watch a run until it completes | | Resolving a github.com URL into an `gh api` call or working with sub-issues | Use `git-issue-hierarchy` for sub-issue add/remove/dependency-graph operations | | Looking up label, repo, or workflow metadata via `gh` JSON commands | Use `github-labels` to actually apply or create labels on issues/PRs | 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). ### `gh api` sends every field as a string unless you use `-F` `-f key=value` types the value as a **string**, so an endpoint expecting a number rejects it: ``` gh api -X POST repos/O/R/issues/2380/sub_issues -f sub_issue_id=5471095685 Invalid property /sub_issue_id: "5471095685" is not of type `integer`. (HTTP 422) ``` `-F key=value` reads the value as a typed literal (number, boolean, null, or `@file`) and the identical call succeeds. Observed 2026-09-16: six sub-issue links failed this way before the flag changed. The error quotes the value and names the property, so it reads as a bad id — the id was right and the flag was wrong. Use `-F` for every numeric id (`sub_issue_id`, `after_id`) and `-f` for free text. ## Pull Request Operations ### Check Status ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 # With sub-issue progress gh issue view $ISSUE_NUMBER --json number,title,state,subIssuesSummary ``` ### List Issues ```bash # 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 ``` ### Issue Types ```bash # Create issue with type (requires repo/org with issue types configured) gh issue create --title "..." --body "..." --type "Bug" gh issue create --title "..." --body "..." --type "Feature" gh issue create --title "..." --body "..." --type "Task" ``` ### Sub-Issues ```bash # List sub-issues of a parent gh api repos/{owner}/{repo}/issues/{parent}/sub_issues --jq '.[].number' # Add existing issue as sub-issue gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -F sub_issue_id={child_id} # Remove sub-issue gh api repos/{owner}/{repo}/issues/{parent}/sub_issues/{sub_issue_id} -X DELETE # Reprioritize sub-issue (move after another sub-issue) gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -X PATCH \ -F sub_issue_id={id} -F after_id={after_id} # Get sub-issue summary via issue view gh issue view {N} --json title,subIssuesSummary # Returns: {"total": 5, "completed": 3, "percentCompleted": 60} ``` ## Repository Operations ```bash # 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: ```bash # 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` | | Sub-issue progress | `gh issue view $N --json title,subIssuesSummary` | | List sub-issues | `gh api repos/{o}/{r}/issues/{N}/sub_issues --jq '.[].number'` | | Add sub-issue | `gh api repos/{o}/{r}/issues/{N}/sub_issues -F sub_issue_id=M` | | Transfer issue | `gh issue transfer N target-repo` | | Create dev branch | `gh issue develop N --checkout` | | Workflow trigger | `gh workflow run $NAME` | ## Error Handling in Context Use `2>/dev/null` to suppress errors in context expressions (do NOT use `||` fallbacks - blocked by Claude Code 2.1.7+): ```markdown - PR checks: !`gh pr checks $PR --json name,state,conclusion` - Run status: !`gh run view $ID --json status,conclusion` ``` For custom issue fields, issue management (transfer/pin/lock/develop), GitHub URL resolution (file contents, diffs, patches), and complete JSON field lists, see [REFERENCE.md](REFERENCE.md).