git-gh-client

# GitHub CLI (gh) Client Skill Base skill for interacting with GitHub via the `gh` CLI tool. This skill is invoked by other git skills that need GitHub operations. ## Purpose Provides reusable GitHub CLI functionality: - ✅ Check if `gh` is installed and authenticated - 📋 **List all PRs for the repository** - 🔍 **Search and filter PRs** (by author, label, date, state, etc.) - 📄 Get PR details and metadata - ✅ Check PR status checks and CI/CD results - 📝 Create and manage pull requests ## Common Use Cases This skill is used both **directly** (when user asks to list/filter PRs) and **indirectly** (invoked by other skills): **Direct usage:** - "List all open PRs" → Shows all open PRs in current repo - "Find PRs by username" → Filters PRs by author - "Show PRs with label 'bug'" → Filters by label - "List recent PRs" → Shows PRs sorted by date **Invoked by other skills:** - `git-prepare-pull-request` - Creating PRs - `pr-review` - Reviewing PRs - `git-pull-request-status` - Checking PR status and CI/CD ## Phase 1: Check gh CLI Availability **ALWAYS check if gh is installed before attempting gh commands.** ### Check Installation ```bash which gh ``` ### Check Authentication ```bash gh auth status ``` ### If Not Installed Provide installation instructions: ```markdown The GitHub CLI (`gh`) is required for this operation. ## Installation **Linux (Debian/Ubuntu):** ```bash sudo apt install gh ``` **Linux (Fedora/RHEL/CentOS):** ```bash sudo dnf install gh ``` **macOS:** ```bash brew install gh ``` **Windows:** ```powershell winget install --id GitHub.cli ``` **Other platforms:** Visit https://cli.github.com/manual/installation ## Authentication After installation, authenticate with: ```bash gh auth login ``` Follow the prompts to authenticate with your GitHub account. ``` ### If Not Authenticated ```bash gh auth login ``` ## Phase 2: List and Filter Pull Requests **This is a CORE capability - used both directly by users and by other skills.** ### Basic PR Listing ```bash # List all PRs in the repository (defaults to open PRs) gh pr list # Show more PRs (default is 30) gh pr list --limit 100 # List with specific columns gh pr list --json number,title,author,createdAt,state # Pretty table format (human-readable) gh pr list | column -t ``` ### Filter by State ```bash # Open PRs only (default) gh pr list --state open # All closed PRs gh pr list --state closed # Only merged PRs gh pr list --state merged # All PRs (open, closed, merged) gh pr list --state all ``` ### Filter by Author ```bash # PRs by specific user gh pr list --author <username> # PRs by current user gh pr list --author @me # PRs by multiple authors (using search) gh pr list --search "author:user1 author:user2" ``` ### Filter by Label ```bash # PRs with single label gh pr list --label bug # PRs with multiple labels (ANY match) gh pr list --label "bug,priority:high" # PRs with specific label pattern gh pr list --search "label:enhancement" ``` ### Filter by Assignee/Reviewer ```bash # PRs assigned to user gh pr list --assignee <username> # PRs assigned to me gh pr list --assignee @me # PRs requesting review from user gh pr list --search "review-requested:username" # PRs reviewed by user gh pr list --search "reviewed-by:username" ``` ### Search by Keywords ```bash # Search in title and body gh pr list --search "keyword" # Search in title only gh pr list --search "in:title keyword" # Search in body only gh pr list --search "in:body keyword" # Multiple keywords (AND logic) gh pr list --search "keyword1 keyword2" ``` ### Filter by Date ```bash # PRs created in last 7 days gh pr list --search "created:>$(date -d '7 days ago' +%Y-%m-%d)" # PRs updated in last 24 hours gh pr list --search "updated:>$(date -d '1 day ago' +%Y-%m-%d)" # PRs created in specific date range gh pr list --search "created:2024-01-01..2024-01-31" # PRs created before a date gh pr list --search "created:<2024-01-01" ``` ### Advanced Filtering ```bash # Draft PRs gh pr list --search "is:draft" gh pr list --draft # PRs ready for review (not draft) gh pr list --search "is:open -is:draft" # PRs with merge conflicts gh pr list --search "is:open conflicts:>0" # PRs without tests gh pr list --search "is:open -label:has-tests" # PRs needing review gh pr list --search "is:open review:required" # Approved PRs gh pr list --search "is:open review:approved" # PRs with changes requested gh pr list --search "is:open review:changes_requested" # PRs by base branch gh pr list --base main gh pr list --base develop # PRs by head branch pattern gh pr list --search "head:feature/*" ``` ### Combined Filters (Real-World Examples) ```bash # My open PRs that need review gh pr list --author @me --state open --search "review:required" # Bug fixes waiting for approval gh pr list --label bug --search "is:open review:approved" # Recent PRs by specific author gh pr list --author username --search "created:>$(date -d '7 days ago' +%Y-%m-%d)" # High priority PRs with failures gh pr list --label "priority:high" --search "is:open status:failure" # PRs ready to merge (approved, no conflicts, checks passing) gh pr list --search "is:open review:approved status:success -conflicts:>0" ``` ### Sort and Format Output ```bash # Sort by creation date (newest first) gh pr list --json number,title,createdAt --jq 'sort_by(.createdAt) | reverse | .[] | "#\(.number) - \(.title)"' # Sort by updated date gh pr list --json number,title,updatedAt --jq 'sort_by(.updatedAt) | reverse | .[] | "#\(.number) - \(.title) (updated: \(.updatedAt))"' # Custom formatted output gh pr list --json number,title,author,state,createdAt --jq '.[] | "#\(.number) [\(.state)] \(.title) by @\(.author.login) (\(.createdAt[:10]))"' # CSV format for export gh pr list --json number,title,author,state,createdAt --jq -r ' ["Number","Title","Author","State","Created"], (.[] | [.number, .title, .author.login, .state, .createdAt]) | @csv' # Count PRs by label gh pr list --json labels --jq '[.[].labels[].name] | group_by(.) | map({label: .[0], count: length})' ``` ### Get PR Details ```bash # View PR summary (human-readable) gh pr view <PR_NUMBER> # IMPORTANT: Avoid deprecated fields # DO NOT request: projectCards, projectItems (deprecated) # Safe fields to request: gh pr view <PR_NUMBER> --json number,title,body,author,state,baseRefName,headRefName,createdAt,updatedAt,labels,reviews,files,commits # Get PR diff gh pr diff <PR_NUMBER> # Get PR commits gh pr view <PR_NUMBER> --json commits --jq '.commits[] | "\(.oid[0:7]) \(.messageHeadline)"' # Get changed files gh pr view <PR_NUMBER> --json files --jq '.files[] | .path' # Get PR checks (CI/CD status) gh pr view <PR_NUMBER> --json statusCheckRollup ``` **Common Error:** If you see "Projects (classic) is being deprecated" error: - This means you're requesting deprecated fields (projectCards, projectItems) - Solution: Only request the safe fields listed above ## Phase 3: PR Status Checks ### Using `gh pr checks` **IMPORTANT:** `gh pr checks` returns exit code 1 when ANY check fails. This is NORMAL behavior, NOT an error. **ALWAYS handle the exit code when using this command:** ```bash # ✅ RECOMMENDED: Use || true to ignore exit code gh pr checks <PR_NUMBER> || true # ✅ Or capture both output and exit code if gh pr checks <PR_NUMBER> 2>&1; then echo "All checks passed!" else echo "Some checks failed (see output above)" fi # ✅ Or capture output for parsing checks_output=$(gh pr checks <PR_NUMBER> 2>&1 || true) echo "$checks_output" # ✅ Store exit code separately gh pr checks <PR_NUMBER> check_exit_code=$? if [ $check_exit_code -eq 0 ]; then echo "All checks passed" else echo "Some checks failed (exit code: $check_exit_code)" fi ``` **Exit code behavior:** - Exit code 0 = All checks passed ✅ - Exit code 1 = One or more checks failed ❌ (this is NOT a command error!) - The output is always valid and shows check status regardless of exit code ### Alternative: Get Status Checks via JSON If you need programmatic parsing, use JSON: ```bash # Get status checks as JSON (doesn't use exit codes for check status) gh pr view <PR_NUMBER> --json statusCheckRollup --jq '.statusCheckRollup' ``` ### Parse Status Check Results The `statusCheckRollup` contains all CI/CD checks. Parse it to find failures: ```bash # Get failed checks gh pr view <PR_NUMBER> --json statusCheckRollup --jq ' .statusCheckRollup[] | select(.conclusion == "FAILURE" or .conclusion == "ERROR") | { name: .name, conclusion: .conclusion, detailsUrl: .detailsUrl } ' ``` ### Status Check Conclusions | Conclusion | Meaning | |------------|---------| | `SUCCESS` | Check passed | | `FAILURE` | Check failed | | `ERROR` | Check encountered an error | | `PENDING` | Check is running | | `SKIPPED` | Check was skipped | | `CANCELLED` | Check was cancelled | | `TIMED_OUT` | Check timed out | ### Get Check Run Details ```bash # List all check runs for a PR gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/checks --jq '.check_runs[] | {name, conclusion, output: .output.title}' ``` ### Get Workflow Run Logs If a GitHub Actions check failed, get the logs: ```bash # Get workflow runs for the PR's head SHA gh run list --branch <branch-name> --limit 10 # Get logs for a specific run gh run view <RUN_ID> --log # Get logs for failed jobs only gh run view <RUN_ID> --log-failed ``` ## Phase 4: Creating Pull Requests ### Create PR with Details ```bash # Interactive PR creation gh pr create # Create with title and body gh pr create --title "PR Title" --body "Description" # Create with template (heredoc for multi-line) gh pr create --title "Feature: Add new capability" --body "$(cat <<'EOF' ## Summary - Added feature X - Updated documentation ## Test Plan - [ ] Unit tests pass - [ ] Integration tests pass 🤖 Generated with Claude Code EOF )" # Create draft PR gh pr create --draft --title "WIP: Feature" --body "Work in progress" # Create with reviewers and assignees gh pr create --title "Fix bug" --body "..." --reviewer user1,user2 --assignee user3 # Create with labels gh pr create --title "Fix bug" --body "..." --label bug,priority:high # Create to different base branch gh pr create --base develop --head feature-branch --title "..." --body "..." ``` ### Auto-fill PR Details ```bash # Use commit messages to pre-fill gh pr create --fill # Use first commit as template gh pr create --fill-first ``` ## Phase 5: PR Management ### Update PR ```bash # Edit PR title/body gh pr edit <PR_NUMBER> --title "New title" gh pr edit <PR_NUMBER> --body "New description" # Add labels gh pr edit <PR_NUMBER> --add-label bug,priority:high # Add reviewers gh pr edit <PR_NUMBER> --add-reviewer user1,user2 # Mark as ready for review (convert from draft) gh pr ready <PR_NUMBER> # Convert to draft gh pr edit <PR_NUMBER> --draft ``` ### Merge PR ```bash # Merge when checks pass gh pr merge <PR_NUMBER> # Merge with specific strategy gh pr merge <PR_NUMBER> --merge # Create merge commit gh pr merge <PR_NUMBER> --squash # Squash and merge gh pr merge <PR_NUMBER> --rebase # Rebase and merge # Auto-merge when checks pass gh pr merge <PR_NUMBER> --auto