github-operations

GitHub 操作

全面的 GitHub CLI（gh）操作指南，涵盖项目管理，从创建基本 Issue 到通过 REST API 集成高级 Projects v2 功能和跟踪里程碑。

概览

• 创建和管理 GitHub Issue 和 PR
• 使用 GitHub Projects v2 自定义字段
• 通过 REST API 管理里程碑（冲刺、版本发布）
• 使用 gh 自动执行批量操作
• 执行 GraphQL 查询以完成复杂操作

---

重要：任务管理为必需项（CC 2.1.16）

在进行任何其他操作之前，先创建任务以跟踪进度：

# 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

快速参考

Issue 操作

# 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 操作

# 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

提示（CC 2.1.27）： 通过 gh pr create 创建的会话会自动关联到 PR。使用 --from-pr 恢复会话并加载完整的 PR 上下文。

里程碑操作（REST API）

易踩坑点： gh issue edit --milestone 接受的是名称（字符串），而不是数字。REST API 使用的是编号（整数）。切勿向 --milestone 传入数字。加载 Read("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 操作

# 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 输出模式

# 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"))))]'

---

关键概念

里程碑与 Epic

里程碑	Epic
基于时间（冲刺、版本发布）	基于主题（功能）
有截止日期	无截止日期
进度条	任务列表复选框
原生 REST API	需要变通方案

规则：用里程碑表示“何时”，用父 Issue 表示“做什么”。

Projects v2 自定义字段

Projects v2 使用 GraphQL 设置自定义字段（Status、Priority、Domain）。基本的 gh project 命令可用于列出和添加项目，但更新字段需要使用 GraphQL mutation。

---

规则快速参考

规则	影响	涵盖内容
issue-tracking-automation（加载 rules/issue-tracking-automation.md）	高	根据提交自动推进、子任务完成、会话摘要
issue-branch-linking（加载 rules/issue-branch-linking.md）	中	分支命名、提交引用、PR 关联模式

批量创建 Issue

一次创建多个 Issue 时（例如，为冲刺预先创建 Issue），请使用由数组驱动的循环：

# 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

提示： 使用 --json number --jq '.number' 获取新建 Issue 的编号，以便立即引用（例如，添加到 Projects v2 或在 PR 中关联）。

---

最佳实践

1. 脚本中始终使用 --json — 使用 --jq 解析，确保可靠性
2. 自动化时使用非交互模式 — 使用 --title、--body 标志
3. 批量操作前检查速率限制 — 使用 gh api rate_limit。在 CC ≥ 2.1.116 中，当 gh 遇到 403 时，Bash 工具会在 transcript 中显示速率限制提示 — 应将此提示视为权威信息并暂停操作，不要盲目重试。在 2.1.116 之前，Agent 无法获取此信号，可能会在约 13 秒内耗尽所有重试次数。
4. 多行内容使用 heredoc — --body "$(cat <<'EOF'...EOF)"
5. 在 PR 中关联 Issue — 使用 Closes #123、Fixes #456 — GitHub 会在合并时自动关闭 Issue
6. 使用 ISO 8601 日期 — 里程碑的 due_on 使用 YYYY-MM-DDTHH:MM:SSZ
7. 关闭里程碑，不要删除 — 保留历史记录
8. --milestone 接受名称，而非编号 — 加载 Read("references/cli-vs-api-identifiers.md")
9. 切勿直接运行 gh issue close — 使用 gh issue comment 留下进展评论；只有关联的 PR 合并到默认分支后，Issue 才会关闭

---

2026 年 CLI 变更 — 需要了解的内容

gh-copilot 扩展已停止维护

GitHub 已于 2025 年 10 月停止维护 gh-copilot 扩展。Copilot 现在是独立的二进制文件：

# 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"

从 cli.github.com/copilot 下载，或通过 Homebrew 安装（brew install github/gh/copilot）。两者均已安装时，认证信息会与 gh auth 共享。

gh agent-task（2026）

用于管理 Copilot 编码 Agent 任务的新子命令：

gh agent-task create --repo owner/repo --title "Fix flaky login test"
gh agent-task list --state open
gh agent-task view 42 --log          # stream agent log
gh agent-task watch 42                # live-follow until completion
gh agent-task cancel 42

该命令与 REST 端点 POST /repos/{owner}/{repo}/agent-tasks 配合，用于通过 CI 创建任务。

子议题（原生支持，2026）

子议题现已成为 GitHub 的原生概念——无需扩展：

# 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>

旧的第三方扩展 gh-sub-issue 仍可使用，但已被取代。GraphQL 子议题变更仍需要议题的 node_id（参见 references/cli-vs-api-identifiers.md）。

---

相关技能

• ork:create-pr - 以恰当的格式创建拉取请求并分配审阅者
• ork:review-pr - 使用专门的 Agent 进行全面的 PR 审查
• ork:release-management - 使用语义化版本控制和变更日志的 GitHub 发布工作流
• ork:commit - 堆叠式 PR 工作流和变基协调位于 src/skills/commit/rules/（stacked-pr-workflow、stacked-pr-rebase）中。没有 stacked-prs 技能。
• ork:issue-progress-tracking - 根据提交自动更新议题进度

关键决策

决策	选择	理由
CLI 与 API	优先使用 gh CLI	身份验证更简单，用户体验更好，并能自动处理分页
输出格式	使用 --json 和 --jq	自动化解析可靠，无需使用正则表达式解析
里程碑与史诗	按时间使用里程碑	里程碑有截止日期和进度条，史诗则用于按主题分组
Projects v2 字段	GraphQL 变更	gh project 命令功能有限，自定义字段需要 GraphQL
里程碑生命周期	关闭而非删除	保留历史记录和进度跟踪

上游内容覆盖（请勿重复编写）

以下主题已有一手文档。请从相应来源获取，而不要在此技能中扩充副本。

主题	来源
gh issue 批量创建 / 编辑 / 列表循环、模板、转移和置顶	https://cli.github.com/manual/gh_issue
跨仓库创建 / 编辑 / 克隆标签	https://cli.github.com/manual/gh_label
组织范围的议题搜索限定符	https://cli.github.com/manual/gh_search_issues
里程碑 REST CRUD：端点、负载字段、列表筛选和排序	https://docs.github.com/en/rest/issues/milestones
Projects v2 字段变更、值联合类型、字段和选项 ID 的查找	https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects
子议题端点负载和分页	https://docs.github.com/en/rest/issues/sub-issues
速率限制标头、重置规则、次级限制	https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api

以下内容仍由我们在此技能中完整维护： PR 审查 / 合并门控，包括 statusCheckRollup 数组折叠（references/pr-workflows.md）；GraphQL 查询、 分页和 node-id 查找（references/graphql-api.md）；里程碑和 Projects v2 的 CLI-NAME 与 API-NUMBER 标识符映射（references/cli-vs-api-identifiers.md）；上方的子议题快速参考；以及 速率限制预检守卫（examples/automation-scripts.md）。内部规则及其理由汇总于 references/ork-delta.md。

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
ork-delta.md	内部规则：钩子约定、关闭而非删除、速率限制规范、文件集约定
pr-workflows.md	审查、合并策略、自动合并、statusCheckRollup 折叠
graphql-api.md	复杂查询、分页、批量操作
cli-vs-api-identifiers.md	NAME 与 NUMBER 易错点、里程碑 / 项目 ID 映射
issue-management.md	指针存根：议题差异说明及上游链接
milestone-api.md	指针存根：里程碑差异说明及上游链接
projects-v2.md	指针存根：Projects v2 差异说明及上游链接

示例

加载：Read("examples/automation-scripts.md") - 长时间运行的 gh 循环中的速率限制规范，以及批量循环配方的指针