GitHub CLI operations for issues, PRs, milestones, and Projects v2. Covers gh commands, REST API patterns, and automation scripts. Use when managing GitHub issues, PRs, milestones, or Projects with gh.
GitHub CLI operations for issues, PRs, milestones, and Projects v2. Covers gh commands, REST API patterns, and automation scripts. Use when managing GitHub issues, PRs, milestones, or Projects with gh.
Comprehensive GitHub CLI (gh) operations for project management, from basic issue creation to advanced Projects v2 integration and milestone tracking via REST API.
Overview
Creating and managing GitHub issues and PRs
Working with GitHub Projects v2 custom fields
Managing milestones (sprints, releases) via REST API
Automating bulk operations with gh
Running GraphQL queries for complex operations
CRITICAL: Task Management is MANDATORY (CC 2.1.16)
BEFORE doing ANYTHING else, create tasks to track progress:
# 1. Create main task IMMEDIATELY
TaskCreate(
subject="GitHub Operations: {target}",
description="Managing GitHub issues, PRs, milestones, or Projects",
activeForm="Managing GitHub resources"
)
# 2. Create subtasks matching the operation scope
TaskCreate(subject="Issue management", activeForm="Creating/updating issues")
TaskCreate(subject="PR management", activeForm="Managing pull requests")
TaskCreate(subject="Milestone tracking", activeForm="Updating milestones")
# 3. Set dependencies if operations are sequential
TaskUpdate(taskId="3", addBlockedBy=["2"])
TaskUpdate(taskId="4", addBlockedBy=["3"])
# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress") # When starting
TaskUpdate(taskId="2", status="completed") # When done
Quick Reference
Issue Operations
# Create issue with labels and milestone
gh issue create --title "Bug: API returns 500" --body "..." --label "bug" --milestone
gh issue list --state open --label --assignee @me
gh issue edit 123 --add-label --milestone
"Sprint 5"
# List and filter issues
"backend"
# Edit issue metadata
"high"
"v2.0"
PR Operations
# Create PR with reviewers
gh pr create --title "feat: Add search" --body "..." --base dev --reviewer @teammate
# Watch CI status and auto-merge
gh pr checks 456 --watch
gh pr merge 456 --auto --squash --delete-branch
# Resume a session linked to a PR (CC 2.1.27)
claude --from-pr 456 # Resume session with PR context (diff, comments, review status)
claude --from-pr https://github.com/org/repo/pull/456
Tip (CC 2.1.27): Sessions created via gh pr create are automatically linked to the PR. Use --from-pr to resume with full PR context.
Milestone Operations (REST API)
Footgun:gh issue edit --milestone takes a NAME (string), not a number. The REST API uses a NUMBER (integer). Never pass a number to --milestone. Load Read("${CLAUDE_PLUGIN_ROOT}/skills/github-operations/references/cli-vs-api-identifiers.md").
# List milestones with progress
gh api repos/:owner/:repo/milestones --jq '.[] | "\(.title): \(.closed_issues)/\(.open_issues + .closed_issues)"'# Create milestone with due date
gh api -X POST repos/:owner/:repo/milestones \
-f title="Sprint 8" -f due_on="2026-02-15T00:00:00Z"# Close milestone (API uses number, not name)
MILESTONE_NUM=$(gh api repos/:owner/:repo/milestones --jq '.[] | select(.title=="Sprint 8") | .number')
gh api -X PATCH repos/:owner/:repo/milestones/$MILESTONE_NUM -f state=closed
# Assign issues to milestone (CLI uses name, not number)
gh issue edit 123 124 125 --milestone "Sprint 8"
Projects v2 Operations
# Add issue to project
gh project item-add 1 --owner @me --url https://github.com/org/repo/issues/123
# Set custom field (requires GraphQL)
gh api graphql -f query='mutation {...}' -f projectId="..." -f itemId="..."
JSON Output Patterns
# Get issue numbers matching criteria
gh issue list --json number,labels --jq '[.[] | select(.labels[].name == "bug")] | .[].number'# PR summary with author
gh pr list --json number,title,author --jq '.[] | "\(.number): \(.title) by \(.author.login)"'# Find ready-to-merge PRs (statusCheckRollup is an ARRAY, so fold it first)
gh pr list --json number,reviewDecision,statusCheckRollup \
--jq '[.[] | select(.reviewDecision == "APPROVED"
and ([(.statusCheckRollup // [])[] | .conclusion // .state]
| length > 0 and all(IN("SUCCESS","SKIPPED","NEUTRAL"))))]'
Key Concepts
Milestone vs Epic
Milestones
Epics
Time-based (sprints, releases)
Topic-based (features)
Has due date
No due date
Progress bar
Task list checkbox
Native REST API
Needs workarounds
Rule: Use milestones for "when", use parent issues for "what".
Projects v2 Custom Fields
Projects v2 uses GraphQL for setting custom fields (Status, Priority, Domain). Basic gh project commands work for listing and adding items, but field updates require GraphQL mutations.
When creating multiple issues at once (e.g., seeding a sprint), use an array-driven loop:
# Define issues as an array of "title|labels|milestone" entries
SPRINT="Sprint 9"
ISSUES=(
"feat: Add user auth|enhancement,backend|$SPRINT""fix: Login redirect loop|bug,high|$SPRINT""chore: Update dependencies|maintenance|$SPRINT"
)
for entry in"${ISSUES[@]}"; do
IFS='|'read -r title labels milestone <<< "$entry"
NUM=$(gh issue create \
--title "$title" \
--label "$labels" \
--milestone "$milestone" \
--body "" \
--json number --jq '.number')
echo"Created #$NUM: $title"done
Tip: Capture the created issue number with --json number --jq '.number' so you can reference it immediately (e.g., add to Projects v2, link in PRs).
Best Practices
Always use --json for scripting - Parse with --jq for reliability
Non-interactive mode for automation - Use --title, --body flags
Check rate limits before bulk operations - gh api rate_limit. On CC ≥ 2.1.116, the Bash tool surfaces a rate-limit hint in the transcript when gh hits 403 — treat that hint as authoritative and back off, don't blind-retry. Before 2.1.116, agents had no signal and would burn all retry attempts in ~13 s.
Use heredocs for multi-line content - --body "$(cat <<'EOF'...EOF)"
Link issues in PRs - Closes #123, Fixes #456 — GitHub auto-closes on merge
Use ISO 8601 dates - YYYY-MM-DDTHH:MM:SSZ for milestone due_on
Close milestones, don't delete - Preserve history
--milestone takes NAME, not number - Load Read("${CLAUDE_PLUGIN_ROOT}/skills/github-operations/references/cli-vs-api-identifiers.md")
Never gh issue close directly - Comment progress with gh issue comment; issues close only when their linked PR merges to the default branch
2026 CLI changes — what to know
gh-copilot extension is retired
GitHub retired the gh-copilot extension in October 2025. Copilot is now a standalone binary:
# OLD — no longer supported
gh extension install github/gh-copilot # fails
gh copilot suggest "revert last commit"# fails# NEW — standalone `copilot` binary
copilot suggest "revert last commit"
copilot explain "git rebase -i HEAD~5"
Install from cli.github.com/copilot or via Homebrew (brew install github/gh/copilot). Authentication is shared with gh auth when both are installed.
gh agent-task (2026)
New subcommand for managing Copilot coding-agent tasks:
Pairs with the REST endpoint POST /repos/{owner}/{repo}/agent-tasks for CI-driven task creation.
Sub-issues (native, 2026)
Sub-issues are now a native GitHub concept — no extension required:
# List sub-issues of parent #123
gh api repos/{owner}/{repo}/issues/123/sub_issues
# Add an existing issue #456 as sub-issue of #123
gh api -X POST repos/{owner}/{repo}/issues/123/sub_issues \
-f sub_issue_id=$(gh api repos/{owner}/{repo}/issues/456 --jq .node_id)
# Remove a sub-issue relationship
gh api -X DELETE repos/{owner}/{repo}/issues/123/sub_issue \
-F sub_issue_id=<id>
The old gh-sub-issue third-party extension still works but is superseded. GraphQL sub-issue mutations still require the issue node_id (see references/cli-vs-api-identifiers.md).
Related Skills
ork:create-pr - Create pull requests with proper formatting and review assignments
ork:review-pr - Comprehensive PR review with specialized agents
ork:release-management - GitHub release workflow with semantic versioning and changelogs
ork:commit - Stacked-PR workflow and rebase coordination live in src/skills/commit/rules/ (stacked-pr-workflow, stacked-pr-rebase). There is no stacked-prs skill.
ork:issue-progress-tracking - Automatic issue progress updates from commits
What still stays ours, in full, in this skill: PR review / merge gating including
the statusCheckRollup array fold (references/pr-workflows.md); GraphQL queries,
pagination, and node-id lookup (references/graphql-api.md); the CLI-NAME vs
API-NUMBER identifier mapping for milestones and Projects v2
(references/cli-vs-api-identifiers.md); the sub-issue quick reference above; and
the rate-limit pre-flight guard (examples/automation-scripts.md). House rules with
their rationale are collected in references/ork-delta.md.
References
Load on demand with Read("${CLAUDE_PLUGIN_ROOT}/skills/github-operations/references/<file>"):
File
Content
ork-delta.md
House rules: hook contracts, close-don't-delete, rate-limit discipline, the file-set contract
NAME vs NUMBER footguns, milestone/project ID mapping
issue-management.md
Pointer stub: issue delta plus upstream links
milestone-api.md
Pointer stub: milestone delta plus upstream links
projects-v2.md
Pointer stub: Projects v2 delta plus upstream links
Examples
Load: Read("${CLAUDE_PLUGIN_ROOT}/skills/github-operations/examples/automation-scripts.md") - Rate-limit discipline for long gh loops, plus pointers for the bulk-loop recipes
