GitHub Operations

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

Quick Reference

Issue Operations

Create issue with labels and milestone

gh issue create --title "Bug: API returns 500" --body "..." --label "bug" --milestone "Sprint 5"

List and filter issues

gh issue list --state open --label "backend" --assignee @me

Edit issue metadata

gh issue edit 123 --add-label "high" --milestone "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_SKILL_DIR}/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

gh pr list --json number,reviewDecision,statusCheckRollupState
--jq '[.[] | select(.reviewDecision == "APPROVED" and .statusCheckRollupState == "SUCCESS")]'

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.

Rules Quick Reference

Rule Impact What It Covers

issue-tracking-automation (load ${CLAUDE_SKILL_DIR}/rules/issue-tracking-automation.md ) HIGH Auto-progress from commits, sub-task completion, session summaries

issue-branch-linking (load ${CLAUDE_SKILL_DIR}/rules/issue-branch-linking.md ) MEDIUM Branch naming, commit references, PR linking patterns

Batch Issue Creation

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

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
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_SKILL_DIR}/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

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
stacked-prs
Manage dependent PRs with rebase coordination
ork:issue-progress-tracking
Automatic issue progress updates from commits

Key Decisions

Decision Choice Rationale

CLI vs API gh CLI preferred Simpler auth, better UX, handles pagination automatically

Output format --json with --jq Reliable parsing for automation, no regex parsing needed

Milestones vs Epics Milestones for time Milestones have due dates and progress bars, epics for topic grouping

Projects v2 fields GraphQL mutations gh project commands limited, GraphQL required for custom fields

Milestone lifecycle Close, don't delete Preserves history and progress tracking

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>") :

File Content

issue-management.md

Bulk operations, templates, sub-issues

pr-workflows.md

Reviews, merge strategies, auto-merge

milestone-api.md

REST API patterns for milestone CRUD

projects-v2.md

Custom fields, GraphQL mutations

graphql-api.md

Complex queries, pagination, bulk operations

cli-vs-api-identifiers.md

NAME vs NUMBER footguns, milestone/project ID mapping

Examples

Load: Read("${CLAUDE_SKILL_DIR}/examples/automation-scripts.md")

Ready-to-use scripts for bulk operations, PR automation, milestone management

github-operations

Safety Notice

Copy this and send it to your AI assistant to learn