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 ``` **Read a thread with `--json title,body,comments`, not `--comments`.** In a non-TTY context (every agent Bash call), `gh issue view N --comments` prints only the comments, with no title or body. When the issue has zero comments it prints nothing and exits 0, so an empty thread looks like an empty issue (observed on gh 2.102.0, #3125). `gh pr view --comments` likely behaves the same way, but that is unverified. ### 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` | | Full issue thread | `gh issue view $N --json title,body,comments` (non-TTY `--comments` omits the body) | | 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` | ## Failed Calls: Exit Code First, Output Second Three scripts misread a failed `gh` call as an answer (2026-10): a merge chain read a 504 as "PR not OPEN", `worktree-audit` parsed a 422 error body as data and classified branches with unpushed work as merged, and a retried `gh issue create` that had errored after creating the issue filed a duplicate. **`gh api` error bodies land on stdout, and `--jq` is skipped.** Observed on gh 2.102.0: ``` $ gh api repos/cli/cli/pulls/999999999 --jq '.state // "none"' {"message":"Not Found","documentation_url":"...","status":"404"} # stdout, filter not applied gh: Not Found (HTTP 404) # stderr; exit 1 ``` `2>/dev/null` hides only the second line, so a script that skips the exit-code check parses the error JSON as the result. Test the exit status before using the output. **A 5xx, timeout, or empty output is UNKNOWN state.** Re-query with backoff and fail if the state never resolves; never map the failure onto a state value: ```bash state= for delay in 2 4 8 16; do state=$(gh pr view "$N" --json state --jq .state) && break state=; sleep "$delay" done [ -n "$state" ] || { echo "PR #$N: state UNKNOWN after retries" >&2; exit 1; } ``` A 500 from `gh pr merge` has its own control: see `git-merge-hazards` ([merge-endpoint-failures.md](../git-merge-hazards/references/merge-endpoint-failures.md)). **After a create errors, look for the object before retrying.** The write can succeed server-side while the response is lost. List rather than search, since the search index lags new objects: ```bash gh issue list --state all -L 5 --json number,title,createdAt # newest first gh pr list --head "$BRANCH" --state all --json number,url ``` ## 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).