Github

---
name: github
description: 'Use when automating GitHub issues, pull requests, reviews, CI checks, labels, releases, or engineering collaboration loops through the GitHub CLI.'
zh_description: "用于通过 GitHub CLI 自动化 Issue、PR、Review、CI 检查、标签和发布协作。"
version: "1.0.0"
author: "seaworld008"
source: "in-house"
source_url: ""
tags: '["automation", "github", "workflow"]'
created_at: "2026-03-15"
updated_at: "2026-06-29"
quality: 2
complexity: "intermediate"
---

# GitHub

当任务涉及 GitHub 仓库协作（Issue/PR/CI/Review）时使用。GitHub 技能是连接本地代码环境与远程协作平台的桥梁，它通过封装 `gh` CLI 工具，使 Agent 能够执行从“创建 Issue 跟踪 Bug”到“合并经过评审的 PR”全生命周期的自动化管理。

## 安装

```bash
npx clawhub@latest install github
```

## 触发场景

- **创建、分配、更新 Issue 与 Milestone**：快速将用户提出的功能点转化为可跟踪的条目。
- **批量处理 PR 评论、状态和合并策略**：在多人评审的大型 PR 中，自动汇总反馈并提交合并请求。
- **读取 CI 失败日志并生成修复清单**：当 GitHub Actions 运行失败时，自动拉取日志并利用 `gh-fix-ci` 技能进行修复。
- **汇总仓库活动用于周报或复盘**：从 `gh pr list` 和 `gh issue list` 中提取数据，生成具有洞察力的协作报告。
- **发布管理 (Releases)**：自动生成 Release Note 并发布新的版本包。
- **权限与项目维护**：管理 Repo 的 Labels, Topics 以及 Collaborators。

## 推荐流程

1. **环境准备 (Setup)**：明确目标仓库（Owner/Repo）、当前分支、目标（如修复 CI 或处理 Review）。
2. **状态感知 (Sensing)**：拉取当前 PR / Issue / Workflow Run 的最新元数据。
3. **策略生成 (Planning)**：执行动作前先生成“变更预览”（Preview），描述将要修改的标签、关闭的 Issue 或触发的 Action，避免大规模误操作。
4. **动作执行 (Execution)**：调用 `gh` 指令执行具体动作。
5. **状态同步 (Sync)**：执行后回写结果（如回复评论、添加标签、同步状态到 `MEMORY.md`）。

### 本机 `gh` 认证优先

在任何 GitHub 自动化前，先执行：

```bash
gh auth status
```

如果仓库脚本需要 GitHub API，但环境里没有显式的 `GITHUB_TOKEN` / `GH_TOKEN`，优先复用本机 `gh auth token`，而不是直接走未认证请求。这样可以显著减少：

- `401 Unauthorized`
- 过早触发的 API rate limit
- 因匿名搜索受限导致的“误以为没有更新”

## 触发条件 / When to Use

- **代码提交前夕**：需要创建 PR 以启动团队评审。
- **CI/CD 构建失败**：当 GitHub Actions 报错时，Agent 自动响应。
- **团队协作同步**：需要快速查看当前仓库中有哪些 `Unresolved` 的 Issue。
- **发布周期点**：需要从 Git Commits 中提取变更日志（Changelog）并创建 Release。
- **安全审计**：定期扫描仓库的 Dependabot 警告并尝试自动修复。

## 核心能力 / Core Capabilities

### 1. 深度 Issue 管理 (Issue Lifecycle)
- **操作步骤**：
  1. 使用 `gh issue create` 创建结构化 Issue。
  2. 使用 `gh issue edit` 增加标签（Label）、里程碑（Milestone）和受指派人（Assignee）。
  3. 通过 `gh issue comment` 与协作者进行交互。
- **最佳实践**：为每一类 Issue 设计标准的模板（Bug Report, Feature Request），提高沟通效率。

### 2. PR 全链路自动化 (Pull Request Mastery)
- **操作步骤**：
  1. 创建 PR：`gh pr create --fill --draft`。
  2. 读取 Review 建议：`gh pr view --json reviews`。
  3. 执行合并：`gh pr merge --auto --squash`。
- **最佳实践**：在合并前，先运行 `gh pr checks` 确保所有的 CI 检查项均已通过。

### 3. Workflow 与 CI/CD 故障排查 (Actions/Workflow)
- **操作步骤**：
  1. 列出最近的运行记录：`gh run list --limit 5`。
  2. 如果失败，下载日志：`gh run view <run_id> --log`。
  3. 分析报错日志，定位到具体的 Step 和文件行号。
- **最佳实践**：结合客户端内置 Web Search 或 `deep-research`，检索该报错日志的官方文档、Issue 和可靠技术资料。

### 4. 仓库级数据汇总 (Activity Analytics)
- **操作步骤**：
  1. 使用 `gh api` 调用更底层的 GraphQL 或 REST API 获取历史统计数据。
  2. 统计 PR 合并周期（Lead Time）、Issue 关闭率等指标。

### 5. 周期性仓库维护 (Recurring Maintenance)

- 先 `git fetch origin --prune`，再做 discovery / upstream sync。
- 如果同时存在“小而确定的修复”和“大批量同步”，拆成两个 `codex/` 分支与两个 PR。
- 先合并聚焦 PR，再合并批量同步 PR，避免回滚时把不相关内容绑在一起。
- 对 warning 做分类：仓库质量回归要当场修，外部 API `403` / 上游路径 `404` 要单独记录并在 PR 里说明。

## 常用命令/模板 / Common Patterns

### 自动 Issue 转换模板 (Issue from Discussion)
```markdown
### 🚀 识别到的任务
- **标题**: [Feature] 支持 OAuth2 登录
- **标签**: `enhancement`, `high-priority`
- **里程碑**: `v2.0-Alpha`
- **描述**: 根据本轮 Slack 讨论，我们需要引入 Google 和 GitHub 的第三方授权登录。

### 执行的 CLI 命令
`gh issue create --title "[Feature] 支持 OAuth2 登录" --label enhancement --milestone v2.0-Alpha --body "..."`
```

### CI 修复辅助示例 (CLI)
```bash
# 查看最近一次失败的 workflow 详情并输出日志到 temp 文件
RUN_ID=$(gh run list --status failure --limit 1 --json databaseId -q '.[0].databaseId')
gh run view $RUN_ID --log > /tmp/ci-failure.log
```

## 进阶应用场景 / Advanced Use Cases

### 1. “无人值守”依赖升级
- Agent 定期运行 `gh-address-comments` 和 `github` 技能。当发现有 Dependabot 的 PR 时，自动运行测试，若通过则自动执行 `gh pr merge --squash`。

### 2. 跨仓库权限同步
- 在一个企业组织下，Agent 自动将所有符合特定 Topic 的仓库权限配置为统一的“开发小组可见”。

## 边界与限制 / Boundaries

- **认证安全 (Auth Scopes)**：默认使用最小权限 Token。严禁在非受信任环境中显式导出 `GITHUB_TOKEN` 环境变量。
- **破坏性操作红线**：删除分支、强制推送 (`--force`)、删除 Release 或批量关闭 Issue 必须经过人类二次确认。
- **API 速率限制 (Rate Limiting)**：短时间内大规模调用 `gh api` 或 `gh search` 可能触发 GitHub 的 Secondary Rate Limit。
- **告警解释**：不要把匿名 API 的 `401`、上游 fallback 探测时的中间 `404`、或短时网络故障误报成“仓库本身异常”；这类告警要和真实仓库回归分开汇报。
- **合并冲突 (Conflicts)**：GitHub CLI 无法直接处理复杂的代码行冲突，此时必须回退到本地 `git` 环境进行人工 rebase。
- **Workflow 自定义权限**：部分 Repo 限制了通过 CLI 触发 Actions 的权限。

## 最佳实践总结

1. **预览第一**：所有的 `gh` 变更动作必须先生成 Preview，告知用户“我将要在 GitHub 上执行什么”。
2. **两阶段提交**：特别是 `merge` 和 `delete` 动作，必须分两步确认。
3. **记忆化协作**：重要的 Issue ID 或 PR 链接同步到 `MEMORY.md` 以便后续引用。
4. **自动化与人工的边界**：代码审查（Review）建议主要由 LLM 提供参考，但最终的 `Approve` 动作应由人类执行。
5. **日志可追溯**：记录每一次 `gh` 操作的输出，方便事后审计。
6. **模板化管理**：充分利用 GitHub 仓库自带的 `.github/ISSUE_TEMPLATE` 提高规范度。
7. **分阶段合并**：周期性维护优先拆成“聚焦修复 PR”和“批量同步 PR”，降低审查与回滚成本。