在本章中，我们将深入讨论 Claude Code 与 GitHub 的集成。这项集成涉及一系列配置步骤，包括安装 GitHub CLI、把它配置到 Claude Code 工作流中，以及选择 Claude Code 将要操作的仓库。
完成配置后，Claude Code 就可以直接在仓库中被使用。你可以在 Pull Request 和 Issue 中 @ 它，让它帮你审查代码、提出修复建议，并协助解决报告的问题。Claude Code 还可以参与 Pull Request 工作流，在 PR 被创建时自动审查变更。
当一个 Pull Request 被打开后，自动化执行依赖的是 GitHub Actions。GitHub Actions 是 GitHub 提供的无服务器工作流平台，通常被用于 CI/CD 任务。在这里，GitHub Actions 会执行一系列工作流，而这些工作流又会依赖 Claude Code CLI 和 Claude Code SDK。
如果你之前不熟悉 GitHub Actions，可以把它理解成一个“事件驱动的自动化系统”。这些事件可以包括：在 Issue 里 @Claude，或者新建一个 Pull Request。每类事件都可以根据项目需求，配置成触发特定工作流。
这些工作流本身，是通过 YAML 文件定义的，通常被称为 GitHub workflow files。这些文件描述了：哪些事件会触发某个动作，以及事件发生后应该执行哪些命令或脚本。
这套集成已经被用于真实生产系统。例如，Anthropic 就在它的多个开源仓库里，把 Claude Code 和 GitHub Actions 一起用于自动化处理 Issue 及相关工作流。一个公开示例可以参考 Anthropic 的 GitHub Actions workflows：https://github.com/anthropics/skills/actions。
本章将涵盖以下主题：
- 安装并配置 Claude Code 的 GitHub 集成
- 通过 Tag Claude Code 来解决 GitHub Issue
- 结合项目 Memory 重新运行 Issue Resolution
安装并配置 Claude Code 的 GitHub 集成
在这一节中，我们将使用另一个仓库来演示集成过程，这个仓库叫 IceBreaker（https://github.com/emarco177/IceBreaker），它是一个托管在 GitHub 上的开源项目。这里仅仅是为了演示方便。你完全可以跟着操作，把这套流程用在你自己的任何 GitHub 仓库上。
如果你打算用自己的仓库，请确保你拥有 管理员权限，因为安装 Claude GitHub App 和配置 workflow 都需要 admin 权限。
在开始安装之前，请先确认：你当前运行 Claude Code 的目录，本身已经是一个初始化完成、并且已经连接到 GitHub 的 Git 仓库。本章中，我们使用的 IceBreaker 仓库已经满足这些条件。也就是说，这套集成只能在一个有效的 GitHub 仓库内部工作。
要开始 GitHub 集成，请从桌面端打开 Claude Code，然后输入 /git。这时会出现 /install-github-app 命令。选择它之后，就会启动安装流程。
在 Claude Code 真正与 GitHub 账户集成之前，有两个前置条件必须满足：
第一，GitHub CLI（也就是 gh CLI）必须已经安装在本地。在这一刻，它还没安装，所以我们下一步先装它。
第二，GitHub CLI 必须已经登录并认证到一个 GitHub 账户。Claude Code 需要依赖这个已认证会话来与仓库交互。
安装前置依赖
GitHub CLI 的安装命令会根据操作系统而不同。下面示例使用的是 macOS + Homebrew。如果你用的是 Linux 或 Windows，请参考 GitHub CLI 官方安装文档，选择适合自己平台的安装方式：https://cli.github.com/
为了安装并认证 GitHub CLI，请按以下步骤操作：
打开一个新的终端窗口，运行以下命令安装 GitHub CLI：
brew install gh
安装完成后，通过下面命令确认 CLI 已经可用：
gh --help
然后运行下面命令，用 GitHub 账户认证 gh CLI：
gh auth login
在认证流程中，选择 HTTPS 作为连接方式，然后通过浏览器登录。系统会给你一个一次性代码，需要把它输入到浏览器中完成认证。如果你开启了双因素认证，还需要用你配置好的第二因子完成确认。
到这一步，GitHub CLI 就完成认证了，Claude Code 与 GitHub 集成所需的前置条件也都满足了。
安装 Claude GitHub App
前置条件搞定后，我们回到 Claude 里继续安装。由于终端此时已经没用了，可以把它关掉，然后按照提示在 Claude 里再按一次 Enter。接下来，系统会把你重定向到 GitHub 页面。
图 5.1 —— 安装 Claude GitHub App
在 GitHub 账户中开始集成 Claude Code。完成这个集成后，Claude 就能在仓库里评论、创建 Pull Request，并帮助解决 Issue。后面书里我们都会实际演示这些能力。
点击 Install 后，页面会跳回 Claude 的 Web 应用。回到终端，再按一次 Enter 继续。
安装 GitHub Workflow
安装这套集成时，还需要往仓库里添加一个 GitHub workflow。这个 workflow 会跑起真正处理 Claude 评论与操作的 pipeline。
安装过程中，你会看到两个可选项：
- Tag Claude：允许我们在 Issue 和 Pull Request 评论里
@Claude，然后通过 GitHub workflow 来执行 - Claude Code Review：当有新 Pull Request 被打开时，自动进行代码审查
这里我们选择第一个选项。
接下来，需要选择一种认证方式。因为 Claude 的运行会消耗 token，而这些 token 总得有人买单。你可以选择：
- 配置一个与 Claude 订阅绑定的长期有效 token
- 或提供一个 Anthropic API Key
前者适合中小规模使用，尤其是基于订阅配额来跑工作流时；后者则更适合高频、大规模自动化场景，因为这种场景通常会超过订阅上限。这里我们选择第一种，也就是与 Claude 订阅绑定的长期 token。
确认之后，我们授权这项集成。这个授权也会负责跟踪 token 使用，并将其记到对应的 Claude 订阅名下。
如果这个时候出现错误，原因通常是：你是在一个没有连接到 GitHub 仓库的目录中启动了 GitHub 集成。
解决方法很简单：打开一个新的终端，切换到一个已经初始化并连接到你 GitHub 账户的项目目录中。在这个例子里，我们用的是前面书中已经介绍过的 IceBreaker 目录，它本身已经配置好了 GitHub。
重新打开 Claude，重新进入 GitHub 安装流程，Claude 此时就应该能够正确识别当前仓库。打开配置弹窗，选择正确的账户，并授予仓库访问权限。确认后，返回 CLI，并再次用长期 token 的方式完成 Claude Code 配置。
创建 Pull Request
认证完成之后，Claude 会开始初始化这套集成：它会抓取仓库信息，并且自动创建一个 Pull Request。
图 5.2 —— 自动为 Claude GitHub Workflow 创建 Pull Request
这个 Pull Request 里会包含一些更新文件，它们都位于 .github 目录下面。这些文件就是用来配置 GitHub workflow 的 YAML 文件。我们现在打开这个 PR 来看。
这个 workflow 会让 Claude 可以在评论和 Issue 中被 @ 到，并通过 GitHub Actions 运行起来。GitHub Actions 负责提供 Claude 的计算执行环境，而 workflow 配置里会指定使用与我们账户绑定的 token。
从安全角度看，API Key 或 access token 都会被存成 GitHub Actions secret。这个过程在配置时会自动完成。只有拥有相应仓库权限的用户，才能触发这些 workflow。一旦 Claude 被 @，它就可以创建分支、提交 commit，并发布评论。
在合并这个 Pull Request 之前，新加上的 GitHub workflow 应该会自动先跑一遍。你可以在 GitHub Actions 标签页中看到 Claude Code workflow 正在执行。等它成功完成后，再继续合并。
在 workflow 执行期间，它会回头更新这个 Pull Request。Claude 会读取自己刚刚加进去的文件——具体来说，是 .github/workflows 目录下的两个 YAML 文件：claude.yaml 和 claude-code-review.yaml。它会审查这两个文件是否存在安全问题和代码质量问题，并把结果直接评论到 Pull Request 里。
在审查结束时，Claude Code 会给这个 Pull Request 一个 approve，表示它认为这些改动是可以接受的，如下图所示。
图 5.3 —— 所有检查通过后的 Pull Request 审核通过
现在，我们把这个 Pull Request 合并掉。合并完成后，仓库里就会出现一个之前并不存在的新目录：.github/workflows。这个目录中包含了刚才集成自动加入的两个 YAML 文件：
claude.yamlclaude-code-review.yaml
第一个 YAML 文件会展示 Claude workflow 的配置内容。文件中会包含一个叫 Run Claude Code 的步骤。认证 token 则通过一个名为 CLAUDE_CODE_OAUTH_TOKEN 的 secret 注入进来。敏感信息并不会被直接写进 workflow 文件本身，这样配置会更安全。
name: Claude Code
on:
issue_comment:
types: [created]
jobs:
claude:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@beta
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
下面是这个 workflow 文件的一个简化片段。
图 5.4 —— Claude GitHub Actions Workflow YAML 文件
到这里，这项集成就已经完成了。接下来你还可以继续做更细粒度的定制，比如选择使用哪个模型、定义 Claude 允许使用哪些工具，以及根据具体需求调整其他设置。
使用 Claude Code 来解决 GitHub Issue
在这一节中，我们会演示：当 GitHub 集成安装完成之后，如何通过在仓库 Issue 中 @Claude Code 来帮助解决问题。
首先，我们进入仓库的 Issues 页面。这里用来演示的是一个非常简单的问题，Issue 是由一个叫 happyLolonly 的用户提出来的。问题内容是：把变量名从 linkedin_username 改成 linkedin_url，因为这个变量实际保存的是 LinkedIn 的 URL，而不是用户名。
第一步，就是在这个 Issue 里 @Claude 并要求它处理这个问题：
@claude, can you fix this
一旦 Claude 被 tag，一个新的 GitHub Action 就会自动开始运行。在这个例子里，这个 action 的名字叫 small rename。也就是说，只要 Claude 被 mention，动作就会立刻触发。
打开这个 action，可以查看执行细节，并且实时看到日志流出来。不过这些日志大多是 JSON 输出，内容包括 tool call、tool input 和 tool output。对于深度调试来说它们很有价值，但对普通人而言并不友好，很难从高层面快速看懂。
因此，大多数情况下，与其盯着原始 logs，不如直接回到 Issue 本身去看。
Claude 的 To-do List 与上下文发现过程
回到 Issue 页面后，Claude 会生成一个待办事项列表，并随着执行进度不断更新。它首先做的第一件事，是尝试在仓库中寻找一个 CLAUDE.md 文件。
图 5.5 —— Issue 视图中 Claude 的待办清单与上下文发现过程
CLAUDE.md 文件的作用，是给 Claude 提供额外上下文。这些文件能帮助 Claude 理解当前仓库的技术栈、项目结构、编码规范，以及我们希望告诉它的其他偏好。这本质上就是上下文工程的一部分——我们有意识地给模型喂入更多有效信息，让它更准确地完成任务。
先剧透一下：在这个仓库中，并没有 CLAUDE.md 文件。这是有意为之，因为这里想展示一个很重要的事实：在 agentic AI workflow 里，事情并不会总是按预期运行，犯错是常态。
正因为如此，你必须仔细 review Claude 产生的改动，而不能盲信它。这个原则不仅适用于当前例子，而是适用于所有 agentic workflow。
审查 Claude 提出的改动
等 Claude 跑完它的 to-do list 之后，它会更新一个叫 linkedin.py 的文件。接着我们通过创建一个 Pull Request 的方式来查看 diff。
图 5.6 —— 审查包含 Claude 提议改动的 Pull Request
第一眼看过去，这个 Pull Request 的描述似乎很合理。但如果你进一步检查具体代码改动，就会发现：Claude 修改了一个属于第三方 API 请求 payload 的变量名。
图 5.7 —— 错误的变量改名破坏了第三方 API 契约
这就是问题所在。第三方 API 期望这个 payload 使用特定格式和特定变量名。Claude 直接改掉了它，就等于破坏了与外部 endpoint 的契约，代码会因此失效。
因此，这个 Pull Request 是错误的，不能接受。
理解 Claude 的工作方式
Claude 每次修改代码时，都会自动创建一个新分支来工作。这个分支通常遵循类似这样的命名约定：
claude/issue/<issue-number>
这点很关键，因为它意味着 Claude 从来不会直接在 main 分支上操作。
我们始终保有完全控制权，决定要不要 review、修改，或者 merge 它的改动。这种分支策略，也是把 agentic workflow 规模化的基础。实际工作中，我们甚至可以让多个 Claude 实例并行运行，每个实例都在自己的分支上独立工作。
这个思路会进一步连接到更高级的 workflow，比如 Git worktrees，后面书里会继续讲。
这个例子很好地展示了：用 Claude Code 解决 Issue，既有力量，也有限制。Claude 可以非常快地自动改代码，但如果没有足够上下文，它就可能引入破坏性变更。因此，Review 仍然不可省，而理解 Claude 是如何在独立分支上运行的，也会成为你后续扩展 agentic workflow 的关键认知。
通过 CLAUDE.md 为仓库补充上下文
这一节的目标，是要说明：当你显式地补上仓库上下文之后，Claude Code 在解决 Issue 时会变得更准确、更可靠。
那么，前面那个变量改名的 GitHub Issue，Claude 之所以失败，是不是因为它没有得到足够的仓库上下文？接下来，我们就来验证这个假设。
我们先回到桌面上的 GitHub 项目目录。用 Cursor 打开这个项目，并先执行一次 fetch，把最新变更拉下来。此时，前一步自动生成的 YAML 文件已经在本地了。接着我们打开 Claude。
初始化仓库上下文
在 Claude 中运行 /init 命令。正如前面提到过的，这个命令会生成一个 CLAUDE.md 文件，其中会包含仓库特定上下文，例如技术栈、项目结构以及其他相关信息。确认命令后，Claude 就会开始扫描仓库文件。这个过程不会太久，它会在扫描中逐步收集所需信息。
在初始化过程中，Claude 会请求执行某些命令的权限，比如列出文件。这里我们明确允许这些操作。随后，一个本地设置文件会被更新，把这些已批准命令加入白名单，这些权限会在当前本地会话期间持续有效。这样的授权模型，可以让你对 Claude 被允许执行的操作保持细粒度控制。
扫描完成后，Claude 会写出 CLAUDE.md 文件。
检查并提交 CLAUDE.md
我们找到这个新生成的 CLAUDE.md 文件，在源码目录中打开并检查内容。文件中包含了一份结构化的仓库摘要，看上去是正确的。
接下来，我们要求 Claude 把 CLAUDE.md 提交到 Git 仓库。Claude 会先准备一条 commit message，我们审阅并接受。随后这个 commit 会在本地创建，并 push 到远端仓库。
把这个文件提交进去，意味着仓库上下文被正式纳入版本控制，可以与团队共享，而且也能被 Claude Code 在自动化工作流里使用，例如在 GitHub Actions 里使用。
在 commit history 中，此时应该能看到一条新的记录，说明 CLAUDE.md 已经被加入仓库。
图 5.8 —— 将 CLAUDE.md 提交到仓库
现在，仓库上下文已经可用了。我们回到刚才那个 Claude 之前没处理对的 Issue。
再一次在 Issue 里 @Claude，并请它重新处理这个问题。这一次，我们额外给它一个提示，明确说明改动位于某个具体函数中。评论内容如下：
@claude, can you please address this issue? Please notice that you need to edit the function *ice_break_with**
新的 GitHub Actions pipeline 会立刻启动，说明 Claude Code 已经再次被触发。接着我们等待 workflow 跑完。
检查 Claude 这次的改动
Claude 会生成一个新的任务列表，并开始执行。虽然这个实验带有一点偏向性——因为我们额外提供了 hint——但它依然很好地展示了：补充正确上下文之后，结果会显著改善。
等 workflow 完成后，去检查 Claude 创建出来的那个分支。你会看到，变量名已经从 linkedin_username 改成了 linkedin_url，并且这次它在函数定义和调用位置都做了保持一致的修改。
和上一次不同的是，这次的改动没有破坏外部 API 的契约，因此不会把集成搞坏。也就是说，这一次逻辑是正确的。
现在，我们就可以为这次改动创建一个 Pull Request，标题可以写成：
Renamed linkedin_username to linkedin_url
这个标题也准确反映了改动范围。
图 5.9 —— 使用修正后变量名创建的 Pull Request
一旦这个 Pull Request 被打开，Claude Code review workflow 也会自动跑起来。Claude 会分析 diff 并执行代码审查，同时生成一份 review checklist 和对应发现。
这一套 review system 是完全可配置的。你还可以根据需要额外加入更多检查，比如 linter、测试执行，或者自定义校验规则。正因为可配置性这么高，Claude Code 才能更好地融入团队工程工作流。
审查最终会给出一个总体的 approval 结论，没有发现功能性问题。
既然 review 已经通过，这个 Pull Request 就可以被合并了。
总结
在本章中，我们探索了 Claude Code 如何与 GitHub 集成，以及它如何真正参与到实际开发工作流中。我们从安装必要工具开始，完成了 Claude GitHub App 的配置，并搭起了 GitHub Actions workflow，让 Claude 可以响应 Issue 和 Pull Request。我们还看到 Claude 是如何通过创建分支、发起 Pull Request、参与自动审查来工作的，同时也说明了：为什么你必须审查它的改动，而不能直接照单全收。
通过实操示例，我们观察到：如果仓库上下文缺失，Claude 很容易做出错误修改；而当我们引入 CLAUDE.md 之后，它的准确率会明显提升。到这一步，你应该已经清楚地理解了：如何安全地使用 Claude Code、它在哪些地方真正有价值，以及怎样在自动化过程中依然把代码库的最终控制权牢牢掌握在自己手里。
在下一章中，我们将聚焦于结构化的 agentic workflow，重点讨论 planning mode、spec-driven development，以及在实践中如何进行并行 agent 协调。
