Back to Details

github-operations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Operations

GitHub操作

Comprehensive GitHub CLI (
gh
) operations for project management, from basic issue creation to advanced Projects v2 integration and milestone tracking via REST API.
全面的GitHub CLI（
gh
）项目管理操作指南，从基础议题创建到通过REST API实现的Projects v2高级集成与里程碑跟踪。

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
  • 创建和管理GitHub议题与拉取请求（PRs）
  • 操作GitHub Projects v2自定义字段
  • 通过REST API管理里程碑（迭代、发布）
  • 使用
    gh
    实现批量操作自动化
  • 运行GraphQL查询以完成复杂操作

Quick Reference

快速参考

Issue Operations

议题操作

bash
undefined
bash
undefined

Create issue with labels and milestone

创建带标签和里程碑的议题

gh issue create --title "Bug: API returns 500" --body "..." --label "bug" --milestone "Sprint 5"
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
gh issue list --state open --label "backend" --assignee @me

Edit issue metadata

编辑议题元数据

gh issue edit 123 --add-label "high" --milestone "v2.0"
undefined
gh issue edit 123 --add-label "high" --milestone "v2.0"
undefined

PR Operations

PR操作

bash
undefined
bash
undefined

Create PR with reviewers

创建带指定评审人的PR

gh pr create --title "feat: Add search" --body "..." --base dev --reviewer @teammate
gh pr create --title "feat: Add search" --body "..." --base dev --reviewer @teammate

Watch CI status and auto-merge

监控CI状态并自动合并

gh pr checks 456 --watch gh pr merge 456 --auto --squash --delete-branch
gh pr checks 456 --watch gh pr merge 456 --auto --squash --delete-branch

Resume a session linked to a PR (CC 2.1.27)

恢复与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.
claude --from-pr 456 # 恢复包含PR上下文（差异、评论、评审状态）的会话 claude --from-pr https://github.com/org/repo/pull/456

> **提示（CC 2.1.27版本）**：通过`gh pr create`创建的会话会自动与PR关联。使用`--from-pr`可恢复包含完整PR上下文的会话。

Milestone Operations (REST API)

里程碑操作（REST API）

bash
undefined
bash
undefined

List milestones with progress

列出带进度的里程碑

gh api repos/:owner/:repo/milestones --jq '.[] | "(.title): (.closed_issues)/(.open_issues + .closed_issues)"'
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"
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
undefined
gh api -X PATCH repos/:owner/:repo/milestones/5 -f state=closed
undefined

Projects v2 Operations

Projects v2操作

bash
undefined
bash
undefined

Add issue to project

向项目中添加议题

gh project item-add 1 --owner @me --url https://github.com/org/repo/issues/123
gh project item-add 1 --owner @me --url https://github.com/org/repo/issues/123

Set custom field (requires GraphQL)

设置自定义字段（需要GraphQL）

gh api graphql -f query='mutation {...}' -f projectId="..." -f itemId="..."

---
gh api graphql -f query='mutation {...}' -f projectId="..." -f itemId="..."

---

JSON Output Patterns

JSON输出模式

bash
undefined
bash
undefined

Get issue numbers matching criteria

获取符合条件的议题编号

gh issue list --json number,labels --jq '[.[] | select(.labels[].name == "bug")] | .[].number'
gh issue list --json number,labels --jq '[.[] | select(.labels[].name == "bug")] | .[].number'

PR summary with author

包含作者信息的PR摘要

gh pr list --json number,title,author --jq '.[] | "(.number): (.title) by (.author.login)"'
gh pr list --json number,title,author --jq '.[] | "(.number): (.title) by (.author.login)"'

Find ready-to-merge PRs

查找可合并的PR

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

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

---

Key Concepts

核心概念

Milestone vs Epic

里程碑 vs 史诗（Epic）

MilestonesEpics
Time-based (sprints, releases)Topic-based (features)
Has due dateNo due date
Progress barTask list checkbox
Native REST APINeeds workarounds
Rule: Use milestones for "when", use parent issues for "what".
里程碑史诗（Epic）
基于时间（迭代、发布）基于主题（功能）
有截止日期无截止日期
进度条任务列表复选框
原生REST API支持需要变通方案
规则：用里程碑管理「时间节点」，用父议题管理「内容范围」。

Projects v2 Custom Fields

Projects v2自定义字段

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.
Projects v2使用GraphQL来设置自定义字段（状态、优先级、领域）。基础的
gh project
命令可用于列出和添加项目项，但字段更新需要GraphQL变更操作。

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
  1. 脚本编写始终使用
    --json
     - 配合
    --jq
    解析以确保可靠性
  2. 自动化使用非交互模式 - 使用
    --title
    、
    --body
    等参数
  3. 批量操作前检查速率限制 - 执行
    gh api rate_limit
    查看
  4. 使用 heredoc 处理多行内容 - 
    --body "$(cat <<'EOF'...EOF)"
  5. 在PR中关联议题 - 使用
    Closes #123
    、
    Fixes #456
    格式
  6. 使用ISO 8601日期格式 - 里程碑截止日期使用
    YYYY-MM-DDTHH:MM:SSZ
    格式
  7. 关闭而非删除里程碑 - 保留历史记录

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
  • create-pr
    - 创建格式规范且指定评审人的拉取请求
  • review-pr
    - 借助专用Agent进行全面PR评审
  • release-management
    - 遵循语义化版本和变更日志的GitHub发布流程
  • stacked-prs
    - 管理依赖PR并协调变基操作
  • issue-progress-tracking
    - 通过提交记录自动更新议题进度

Key Decisions

关键决策

DecisionChoiceRationale
CLI vs APIgh CLI preferredSimpler auth, better UX, handles pagination automatically
Output format--json with --jqReliable parsing for automation, no regex parsing needed
Milestones vs EpicsMilestones for timeMilestones have due dates and progress bars, epics for topic grouping
Projects v2 fieldsGraphQL mutationsgh project commands limited, GraphQL required for custom fields
Milestone lifecycleClose, don't deletePreserves history and progress tracking
决策选择理由
CLI vs API优先使用gh CLI认证更简单、用户体验更好、自动处理分页
输出格式配合
--jq
使用
--json
自动化解析更可靠，无需正则表达式
里程碑 vs 史诗里程碑用于时间管理里程碑支持截止日期和进度条，史诗用于主题分组
Projects v2字段设置使用GraphQL变更gh project命令功能有限，自定义字段需GraphQL支持
里程碑生命周期关闭而非删除保留历史记录和进度跟踪信息

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
  • 议题管理 - 批量操作、模板、子议题
  • PR工作流 - 评审、合并策略、自动合并
  • 里程碑API - 里程碑增删改查的REST API模式
  • Projects v2 - 自定义字段、GraphQL变更
  • GraphQL API - 复杂查询、分页、批量操作

Examples

示例

  • Automation Scripts - Ready-to-use scripts for bulk operations, PR automation, milestone management
  • 自动化脚本 - 可直接使用的批量操作、PR自动化、里程碑管理脚本