github

What this skill does

# GitHub CLI Expert

Comprehensive guidance for working with the GitHub CLI (`gh`) including common pitfalls, GraphQL patterns, and self-improvement workflows.

## Purpose

To provide reliable, tested patterns for GitHub operations and prevent repeating known mistakes with the `gh` CLI. This skill automatically loads when using `gh` commands and continuously improves by documenting solutions to new issues.

## When to Use

This skill triggers automatically when:
- Running any `gh` command (pr, api, issue, repo, etc.)
- Working with pull requests, reviews, or issues
- Encountering `gh` CLI errors or unexpected behavior
- Needing GraphQL queries for GitHub operations

## Prerequisites

### GitHub CLI Version

**CRITICAL**: Many features require a recent `gh` CLI version. Before using this skill:

1. **Check current version:**
   ```bash
   gh --version
   ```

2. **Compare with latest release:**
   - Check https://github.com/cli/cli/releases for the current stable version
   - If your version is >6 months old, upgrade

3. **Upgrade `gh` CLI:**

   **Preferred method (mise):**
   ```bash
   mise use -g gh@latest
   ```

   **Alternative (apt):**
   ```bash
   sudo apt update && sudo apt install -y gh
   ```

   **Why mise is preferred:**
   - Always gets the latest version (apt repos lag behind)
   - No sudo required
   - Consistent across environments

4. **Verify upgrade:**
   ```bash
   gh --version
   # Should show version 2.80+ (as of Dec 2025)
   ```

**Known version issues:**
- `gh < 2.20`: Limited GraphQL mutation support
- `gh < 2.40`: Missing `--body-file` flag on `gh pr edit`
- `gh < 2.50`: Incomplete review thread APIs

## ⛔ PR Comments Prohibition (CRITICAL)

**NEVER leave comments directly on GitHub PRs.** This is strictly forbidden:

- ❌ `gh pr review --comment` - FORBIDDEN
- ❌ `gh pr comment` - FORBIDDEN
- ❌ `gh api` mutations that create new reviews or PR-level comments - FORBIDDEN
- ❌ Responding to human review comments - FORBIDDEN

**The ONLY permitted interaction with review threads:**
- ✅ Reply to EXISTING threads created by **GitHub Copilot only** using `addPullRequestReviewThreadReply`
- ✅ Resolve Copilot threads using `resolveReviewThread`

**Never respond to or interact with human reviewer comments.** Only automated Copilot feedback should be addressed.

## ⛔ PR Merge Requirements (CRITICAL — BLOCKING)

**NEVER run `gh pr merge` without verifying ALL of the following gates. No exceptions for PR size, urgency, or any other reason.**

| Gate | Verification | Blocking? |
|------|-------------|-----------|
| CI checks ALL green | `gh pr checks <NUMBER>` — every check must show `pass` | ⛔ YES |
| Copilot review RECEIVED | `gh api repos/{owner}/{repo}/pulls/<NUMBER>/reviews --jq '.[] \| select(.user.login == "copilot-pull-request-reviewer[bot]")'` — must return a review | ⛔ YES |
| Copilot comments RESOLVED | All Copilot review threads resolved (0 unresolved) | ⛔ YES |
| CodeRabbit review received (if GitHub App configured) | Check reviews for `coderabbitai[bot]` | ⛔ YES |
| CodeRabbit comments resolved (if GitHub App configured) | All threads resolved | ⛔ YES |
| Codecov passing | `codecov/patch` and `codecov/project` checks pass | ⛔ YES |

> **CodeRabbit is run primarily LOCALLY (via the `cr` CLI) BEFORE the PR is opened** — see `fx-dev:coderabbit-review` (Mode 1) and `fx-dev:dev` Step 4.5. The PR-level CodeRabbit gate above applies only when the repo's CodeRabbit GitHub App also auto-reviews PRs (a `CodeRabbit` check appears). If a clean local `cr` review ran and the App is not configured, the CodeRabbit gate is already satisfied.

**If Copilot review has NOT been received:** WAIT. Poll every 60 seconds for up to 15 minutes. Do NOT merge without it.

**Incident context:** A "small follow-up" PR was merged without waiting for Copilot review. Copilot found 5 real bugs (timing drift, race conditions, missing tests) that shipped to main. PR size is NEVER a reason to skip review gates.

## ⛔ Release PR Prohibition (CRITICAL)

**NEVER merge release PRs.** This includes PRs created by:

- ❌ release-please (`chore(main): release X.Y.Z`)
- ❌ semantic-release
- ❌ changesets (`Version Packages`)
- ❌ Any automated versioning/release bot

Release PRs control package versioning. Merging them autonomously can publish unintended major/minor versions, which is irreversible. **The user must always merge release PRs manually.**

If a workflow requires a new version to be published (e.g., updating a dependency after an upstream PR merges), STOP and inform the user:

> A release PR exists. Please merge it manually when ready, then confirm so I can proceed.

## Core Principles

### 1. Verify All Operations

Always verify that `gh` commands produced the expected result:

```bash
# After editing PR description
gh pr edit 13 --body-file /tmp/pr-body.md
gh pr view 13 --json body -q .body | head -20  # Verify it worked

# After resolving threads
gh api graphql -f query='mutation { ... }'
gh api graphql -f query='query { ... }' --jq '.data'  # Verify resolution
```

### 2. Prefer GitHub API for Complex Operations

For multi-step operations or data transformations, use `gh api graphql` directly:

```bash
# More reliable than chaining CLI commands
gh api graphql -f query='...' --jq '.data.repository.pullRequest'
```

### 3. Use Correct Methods for Each Task

Check `references/known-issues.md` before attempting operations that have failed before. Common issues include:

- PR description updates with heredocs
- Review thread resolution vs. PR comments
- Command substitution in heredoc strings

### 4. Follow Messaging Conventions

**Be Direct and Concise:**
- All PR descriptions, commit messages, and comments must be direct and to the point
- Eliminate unnecessary prose and filler content
- Focus on what changed and why, not how the work was organized

**Use Conventional Formats:**
- **Commit messages**: Follow conventional commit format (`feat:`, `fix:`, `refactor:`, `docs:`, etc.)
- **PR titles**: Use conventional commit format (e.g., `feat: add user authentication`)
- **Branch names**: Use conventional naming (e.g., `feat/user-auth`, `fix/login-bug`)
- **Comments**: Use conventional comment markers where applicable

**Content Rules:**
- Describe the work being done and changes being made
- **Never mention** in the title: implementation phases, waves, steps of a process, project management terminology, workflow stages, or change-doc numbers
- **Never include** in the title: "Phase 1", "Step 2", "Part 3", "Wave 4", "First iteration", "Initial implementation", "0004-..."
- These belong in the PR **body** (description) if anywhere — never the title

### ⛔ The `#<number>` PR-Title Rule (CRITICAL — BLOCKING)

**A `#` immediately followed by a number — `#4`, `(#4)`, `#123` — in a PR title is a latent reference to PR/issue #N in the target repo.** The title bar itself renders it as plain text, so it looks harmless — but on **squash merge with GitHub's default commit-message setting, the PR title becomes the merge commit's subject line**, and `#N` in a *commit message* DOES auto-link and create a hard cross-reference to PR/issue #N. So a title saying `(#4)` to mean "implementation wave 4" ends up permanently cross-linking your merged commit (and the PR) to whatever PR/issue #4 happens to be. This has repeatedly created messy, wrong cross-links on `main`.

**Rules — no exceptions:**

1. **NEVER put `#<number>` in a PR title to mean anything other than a real PR/issue reference.** Implementation waves, phases, steps, parts, iterations, change-doc numbers (`0004`), and task numbers are FORBIDDEN as `#N` in titles.
2. **A `#<number>` is allowed in a title ONLY if N is a genuine, existing PR or issue in the target repo that this PR is actually about** — and even then, prefer putting the reference in the body (`Closes #123`). If you're not certain the number maps to a real PR/issue on this exact repo, do NOT write it.
3. **Do NOT pre-add a `(#N)` suffix.** When squash-merg