GitHub Operations

gh

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)

# 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
gh api -X PATCH repos/:owner/:repo/milestones/5 -f state=closed

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

Projects v2 Custom Fields

gh project

Best Practices

1. Always use

   --json

   for scripting - Parse with

   --jq

   for reliability
2. Non-interactive mode for automation - Use

   --title

   ,

   --body

   flags
3. Check rate limits before bulk operations -

   gh api rate_limit

4. Use heredocs for multi-line content -

   --body "$(cat <<'EOF'...EOF)"

5. Link issues in PRs -

   Closes #123

   ,

   Fixes #456

6. Use ISO 8601 dates -

   YYYY-MM-DDTHH:MM:SSZ

   for milestone due_on
7. Close milestones, don't delete - Preserve history

Related Skills

• create-pr

  - Create pull requests with proper formatting and review assignments

• review-pr

  - Comprehensive PR review with specialized agents

• release-management

  - GitHub release workflow with semantic versioning and changelogs

• stacked-prs

  - Manage dependent PRs with rebase coordination

• issue-progress-tracking

  - Automatic issue progress updates from commits

Key Decisions

References

• Issue Management - Bulk operations, templates, sub-issues
• PR Workflows - Reviews, merge strategies, auto-merge
• Milestone API - REST API patterns for milestone CRUD
• Projects v2 - Custom fields, GraphQL mutations
• GraphQL API - Complex queries, pagination, bulk operations

Examples

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