前阵子在折腾CI/CD流水线的时候我一直在琢磨一个问题claude-code-action这个项目能不能真的让Claude Code在GitHub Actions的容器环境里跑起来并且输出可用的PR评论。当时刚好在做一个需要频繁代码审查的仓库人工reviewer盯不过来就想试试能不能把Claude Code拉到自动化流程里当第二双眼睛。说实话第一次看到这个项目时我先是兴奋接着就是怀疑——容器环境里能不能正常鉴权Claude Code会不会在非交互模式下卡住输出格式能不能被GitHub识别带着这些疑问我实际拉下来跑了几轮从最基础的CLI验证到Job Summaries输出再到Pull Request评论最后还把weight 0和自动提交代码这个高危选项一块测了。整个过程比预想的曲折但也确实收获了不少实打实的经验。这篇就按我自己的实操顺序把这套东西怎么接线、哪些地方容易翻车、每条路径适合什么场景完整记录下来。1. 一眼看懂GitHub Actions和Claude Code的协作方式先说清楚这个动作到底干了件什么事。GitHub Actions的机制其实很简单仓库里放一个.github/workflows/*.yml文件GitHub检测到push或PR等事件后会按里面写的步骤拉起一个临时环境跑你指定的命令再把结果写回仓库或通过API上报。而Claude Code是Anthropic官方出的终端编程工具你可以在命令行里给它一个任务它会自己读代码、改代码、跑测试、提交变更。这两者能结合的关键点在于Claude Code本质上是一个CLI程序而GitHub Actions允许你在runner上执行任意命令所以只要解决三件事就能让Claude Code在流水线里干活在runner上安装并认证Claude Code。给Claude Code一个足够具体、可自动执行的任务指令。把Claude Code的产出注释、改动、结果说明传回仓库变成PR评论或Job Summaries。claude-code-action这个项目就是把这些环节包成了一个现成的Action你不需要自己在yml里折腾node脚本、Anthropic API调用、鉴权令牌这些细枝末节。它在GitHub Marketplace上的定义大致是输入参数包括anthropic-api-key、github-token、prompt、system-prompt、model、max-failures、run-command等。支持两种运行方式一种是一次性执行命令或提示词另一种是进入交互式会话配合weight 0做自动提交代码这种高级玩法。输出会写到GitHub Actions的Job Summaries也就是工作流运行页面的 Markdown 区域或者直接以PR评论的形式呈现。我在第一次看它的README时最不理解的就是weight这个参数字面意思是权重和代码审查有什么关系后来实际跑了一次才明白它在Claude Code的会话上下文里起到了哪些文件变更算高优先级的作用。这个后面会专门展开这里先有个概念就行。2. 环境准备API密钥、仓库配置与权限设置动手之前先确认几样东西一个GitHub仓库必须是私有或公开都行但建议先拿私有仓库练手、一个Anthropic API密钥从console.anthropic.com创建注意这个密钥要按API调用量计费Claude Code跑起来的消耗比单纯调聊天接口要大得多、以及本地的Git和终端环境。如果你想把效果落地到PR评论还需要配置仓库的Actions权限和Workflow permissions让工作流有权提交评论。2.1 Anthropic API密钥的两种安全姿势第一种也是最推荐的正规做法把密钥存到GitHub仓库的Secrets里路径是Settings - Secrets and variables - Actions新建一个名为ANTHROPIC_API_KEY的密钥粘贴你的API Key。然后在yml里用${{ secrets.ANTHROPIC_API_KEY }}引用。第二种是拿Claude Code自己的OAuth认证来跑。claude-code-action支持读取CLAUDE_CODE_OAUTH_TOKEN环境变量这个Token可以通过在本地装好Claude Code后执行/login生成然后在~/.claude/目录下找到对应的凭据文件提取出来放进Secrets。这种方式的优势是不走API计费走的是Claude订阅额度但缺点是Token有过期时间而且一旦在CI里失效排查起来比较麻烦。我在实际使用中两种都试过建议如果是个人项目、订阅了Claude Pro或Max套餐用OAuth Token更经济如果是团队项目、要严格控费直接走API Key。这里有个容易忽略的点API Key的权限范围。如果你只给Claude Code分配了读取代码的权限那它即便被要求做修改也会因为没有写权限而报错。所以第22条里我会强调需要让Claude Code修改代码时API Key本身不区分读写真正限制行为的是仓库的Actions权限和你在提示词里的要求。别把API Key想着只读的就不干活GitHub这边会先卡住它。2.2 仓库Actions权限的三层开关如果发现Action执行了但Claude Code的评论没有出现在PR里八成是这一层的权限没开对。需要检查的地方有三处第一处是Settings - Actions - General - Workflow permissions这里要选Read and write permissions否则工作流只能读仓库内容没法发评论、改文件、提交代码。第二处是.github/workflows/下的yml文件关于permissions配置块。建议全局放开权限但限定scope我推荐这样写permissions: contents: write pull-requests: write issues: write如果担心风险也可以写成contents: read这就意味着Claude Code只能读代码不能改代码只适合做代码评审建议这种场景。第三处是如果你的仓库启用了Require approval for all outside collaborators或分支保护规则那么工作流提交的commit或者PR评论可能被标记为来自bot需要单独给github-actions这个bot开权限。我在测试时因为开了必须由具有写权限的用户批准才允许合并导致Claude Code提交的代码一直卡在等待审批最初还以为是Action写代码失败了排查了半天才发现是这个原因。3. 第一个Demo让Claude Code在容器里跑通并输出Job Summary环境准备好了先不急着让它改代码而是让Claude Code在容器环境里跑起来输出一句话就够了。这一步能快速验证Action集成是否正确、Claude Code能否正常启动、鉴权是否通过。新建.github/workflows/claude-code-test.yml内容如下name: Claude Code Test on: push: branches: [ main ] workflow_dispatch: permissions: contents: read pull-requests: write issues: write jobs: claude-code: runs-on: ubuntu-latest name: Run claude-code-action steps: - name: Checkout uses: actions/checkoutv4 - name: Run Claude Code Action uses: davila7/claude-code-actionv1 with: anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} prompt: | Review the repository and provide three actionable recommendations for improving code quality and test coverage. This is a fresh checkout, so start by exploring the directory structure. system-prompt: | You are a senior software engineer performing a code review. Be concise, direct, and focus on actionable feedback.这里用actions/checkoutv4把代码拉下来然后触发Action。davila7/claude-code-actionv1是社区里维护得比较活跃的版本如果你想要更多调试输出可以指定到具体commit hash而不是紧跟v1。第一次跑的时候我遇到的第一个坑Claude Code在容器里其实是以非交互模式运行的如果它在等待输入整个Job就会卡住直到超时。所以提示词里一定要明确请直接输出结果不要询问任何问题也不要请求确认。我还遇到过因为缺少git用户配置导致提交失败的情况后面在yml里补上这段即可- name: Set Git user run: | git config --global user.name claude-code[bot] git config --global user.email claude-code[bot]users.noreply.github.com跑完这步后打开工作流运行页面往下翻到Run claude-code-action这个step就能看到## Claude Code Results这样的Markdown标题下面跟着Claude Code生成的内容。这就是Job Summaries机制Actions运行结束后会把step的输出自动汇总到运行页面里不需要额外调API。我在第一次成功看到输出时还是挺兴奋的——因为这意味着整条链路已经通了Claude Code的模型能力被搬进了CI环境剩下的问题都是怎么用好它而不是能不能用。4. 把结果推到PR评论区从环境变量到运行日志的完整链路分析Job Summaries适合自己看但如果你希望reviewer或者协作者直接在PR页面看到Claude Code的评审意见就得让它以PR评论的形式出现。这一步的关键在于prompt里要包含PR的上下文信息Action内部会把这些信息传给Claude Code再由Claude Code生成的回复以评论形式写入PR。我用的yml长这样name: Claude Code PR Review on: pull_request: types: [ opened, synchronize ] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run Claude Code review uses: davila7/claude-code-actionv1 with: anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} prompt: | You are reviewing PR #${{ github.event.pull_request.number }}. Analyze the diff for potential bugs, security issues, and style problems. Structure your response as a Markdown document with clear sections for each category.这里有个细节值得注意fetch-depth: 0。默认的checkout是浅克隆只包含最新一次commitClaude Code想看diff时信息不够。设成0会拉取全部历史虽然慢一点但对PR评审场景来说是必要的。我在一开始没加这个参数Claude Code在分析diff时经常说无法确定变更范围后来加上才恢复正常。再加一层保险可以手动把一个包含变更详情的环境变量池喂给Claude Code。项目里的env参数就是干这个用的你可以定义任意数量的环境变量Claude Code在生成回应时会看到它们with: env: | REPO: ${{ github.repository }} PR_NUMBER: ${{ github.event.pull_request.number }} PR_TITLE: ${{ github.event.pull_request.title }} PR_BODY: ${{ github.event.pull_request.body }}这样在prompt里就可以直接引用这些变量名比如请特别关注PR_BODY里提到的性能问题。实际操作中PR标题和正文往往包含reviewer的意图喂给模型能显著提高评审的针对性。跑通后打开PR页面能看到一条来自github-actions[bot]的评论标题通常是### Claude Code Review里面按你指定的结构列出了发现的问题。把这条链路和Job Summary结合着用效果最好Job Summary给你自己看全量分析PR评论只放给协作者看的精炼结论。5. Prompt设计策略代码审计场景下的case实践prompt写得好不好直接决定Claude Code在CI里是真干活还是瞎指挥。在容器环境里Claude Code没有人在旁边纠偏一旦提示词含糊它会自己脑补任务输出一堆泛泛而谈的建议。我把这段时间总结出的prompt设计策略按场景列一下供直接套用。5.1 代码质量审计场景这种场景下Claude Code需要同时做静态分析和Best Practice检查。我用的提示词模板是这样的You are reviewing this repository as a senior engineer. 1. List the three most critical code quality problems you found. 2. For each problem, show the exact file path and line number. 3. Include a short snippet of the problematic code and a suggestion for improvement. 4. Keep the entire response under 300 words.关键在于三个和精确到文件路径和行号这两点前者限制输出规模后者逼着模型真正去读代码而不是空谈。我试过不加限制让它自由发挥出来的东西看似全面但落实到修改时根本无从下手。给模型明确的数量和质量约束反而能挖掘出更深层的问题。5.2 安全审计场景做安全审计时prompt里要明确告诉它只关注漏洞类别避免被业务逻辑带偏Perform a security-focused audit. Examine these categories: - SQL injection - XXE (XML External Entity) - Insecure deserialization - Hardcoded credentials - Insecure random number generation For each vulnerability found, provide file path, line number, and a patched code snippet. If no vulnerabilities are found, clearly state No critical vulnerabilities detected in scope.最后那句if no vulnerabilities are found加得很值——Claude Code默认倾向于总有东西要说如果不给它一个明确的无可报告出口它会从无关紧要的地方硬找几个小问题反而稀释了安全审计的价值。5.3 多步骤重构场景如果你想让它完成改了A然后跑测试再改B这种多步骤循环prompt里必须写清楚步骤顺序和终止条件Execute the following sequence: 1. Identify all occurrences of hardcoded timeouts in the test suite. 2. Replace them with references to a shared constant defined in a conftest configuration. 3. Run the relevant tests using pytest and check they pass. 4. Do not commit the changes. Report the diff as Markdown with file names and a summary of what was changed.这里do not commit the changes是安全开关。默认情况下Claude Code拿到权限后可能会自己提交代码而你在CI里其实只想让它当个分析员。把改和提交拆成两个Action先让它分析人工确认后再跑一个专门负责提交的Action比让Claude Code一步到位安全得多。5.4 处理语义不清时的兜底话术Claude Code在找不到有效任务时会发挥想象力。应对办法是在prompt末尾加一条硬性兜底规则If you cannot find actionable requests in the repository, respond with exactly No actionable feedback to report. and do not elaborate.这条规则能避免模型过度联想特别是在仓库刚初始化或者PR内容很空的时候。我遇到过几次它把README当代码审的场景加了兜底话术后这类无效输出基本消失了。6. 自动提交代码当成高危选项来理解如果只看不跑不过瘾想让Claude Code直接改代码并提交那你就进入了我说的高危选项区。claude-code-action支持通过设置run-command: claude -p …代码修改提示词…让Claude Code自己进行修改、跑测试、提交commit。听着很酷但里面的坑也不少强烈建议先在非生产分支上试水。6.1 每个变更是重量为0的棋子每个失败是重试计数器这个项目里有个weight参数仔细读它的源码就能发现它控制的是Claude Code的决策倾向——权重为0的变更意味着这次修改本身是可选的、低优先级的。举个例子系统给你展示了一堆文件列表如果某个文件是weight 0Claude Code就知道这个改动不是必须的不强行搞。对应到实际场景就是代码改动优先级 vs 任务完成度的权衡。更关键的是还有个max-failures参数。它的作用是限制Claude Code的试错次数如果一次修改后测试没过它会再试一次但超过max-failures次就终止并报错。我第一次跑的时候没设这个参数结果Claude Code陷入了一个死循环改代码、跑测试失败、继续改、又失败直到Job超时。后来学乖了每次都显式加max-failures: 3同时配合run-command里的--max-failures 3层层保险。6.2 自动提交时的三个真实教训第一个教训是关于分支保护。如果分支上有必须由指定用户审批的规则那么Claude Code提交的commit会被拒但错误信息是remote rejected这种看起来像权限问题的报错不熟悉的人会一头雾水。解决办法是调整分支规则把github-actions[bot]加进白名单或者干脆只在临时分支上跑自动提交。第二个教训是提交信息里必须说清楚来龙去脉但别指望AI自动生成有意义的commit message。我在没指定commit-message参数时Claude Code生成的commit信息有时是Update files有时是Fix issues极难追溯。实际上claude-code-action有专门的输入项来控制是否提交以及提交信息格式建议写成with: commit-message: chore: automated code fixes from Claude Code review push-changes: true第三个教训是自动提交会污染你的Git History。当Claude Code频繁提交时PR的commit列表会变得非常长reviewer根本分不清人改的和AI改的。我后来改成Claude Code改完后不直接提交而是把patch文件作为artifact输出后面再加一个人类审核的步骤这样历史就整洁多了。- name: Apply patch run: | # Generate diff to a file first git diff /tmp/claude-code-changes.patch cat /tmp/claude-code-changes.patch6.3 跑测试失败时的自动修复闭环如果说weight、max-failures是往终点跑的油门那么测试修复闭环就是方向盘。我试过让Claude Code自己发现测试挂了然后修好——这个场景的prompt要写得非常精细You are in a repository with a failing test suite. 1. Run the test suite and identify the failing tests. 2. Read the implementation files that these tests touch. 3. Change the implementation to make the tests pass. 4. Re-run the failing tests to confirm they now pass. 5. Do not modify the test files themselves unless the test assertion is itself wrong. 6. Output a summary of the changes and the test results.这个闭环要是能跑通就等于CI里养了一个能干活的实习生它会自己调试、自己改代码、自己验证最后还给你一份工作报告。但必须小心的是如果测试本身写得有问题Claude Code可能会好心地修改测试去迎合代码——所以上面的第5点特别重要必须限制它改测试文件的权限。我在实际测试中还发现当测试失败信息不够明确时比如只显示exit code 1而没有stack traceClaude Code会陷入盲目修改—测试依旧失败的循环。解决办法是在提前查好测试输出格式或者在启动命令里加上--verbose参数让模型拿到尽量多的诊断信息。7. 骨架之外Job Summaries的Markdown风格和输出转义也许你注意到了上面几次运行输出最终都汇到了Job Summary。这里有个小细节GitHub对Job Summary的内容有严格的Markdown渲染规则包括换行和表格式样。如果你发现Claude Code输出的Markdown表格总是乱掉或没有渲染出来多半是转义和格式问题。我用下来的建议是在system-prompt里就让Claude Code以简洁的Markdown形式输出使用标题和小节列表避免复杂嵌套表格。如果非要有表格让它用最简单的对齐方式别搞合并单元格或多行表格。GitHub的Markdown渲染对表格限制比较多复杂表格很容易被打回原形。还有一点claude-code-action在把Claude Code的stdout写入Job Summary时可能会把长输出的换行符融合掉。如果你发现评论里所有段落连成一片可以在Action配置里找类似output-style或markdown的选项把它设成github-flavored-markdown能明显改善可读性。8. 安全边界什么不该交给Claude Code做说了这么多能做的也该聊聊绝对不能让它碰的。Claude Code在CI里跑着的身份其实是你的GitHub Token的化身。它有权限在仓库里提交、创建PR、发评论如果提示词里给了它不该给的命令后果就是AI给你仓库塞了一堆莫名其妙的commit。我总结的安全边界有三条绝不往prompt里放生产环境凭据即使你在环境变量里临时加了DATABASE_URL或AWS_ACCESS_KEY_IDClaude Code一旦读到就可能泄露进日志或评论里。正确做法是把敏感信息放在${{ secrets.XXX }}中并且在prompt里明确禁止模型引用这些变量。不要让Claude Code删除文件。除非你的业务场景真的是自动清理废弃文件否则它在做重构时可能顺手删掉看似未使用但实际上是配置文件的文件。我吃过一次亏它把pytest.ini当作冗余配置删了导致后续所有测试都因找不到配置而报错。使用仓库Secrets时要特别注意masking效果。GitHub Actions运行时日志会自动隐藏真正的secret值但如果Claude Code把secret值写进了PR评论或文件里那就在日志之外裸奔了。所以日常最好不要在prompt或system prompt里主动引用secret名也不要在输出中提示它读取环境变量里的Token。9. 结合GitHub原生能力给Claude Code加一道路由层现在的claude-code-action已经很能打了但如果想让流水线更精细可以进一步组合原生GitHub Actions能力。比如只有特定路径的变更才触发Claude Code通过on.pull_request.paths配置避免它每次都在文档或样式文件上浪费API额度。利用concurrency组控制并发防止多个PR同时触发多个Claude Code实例导致API调用计数爆炸。claude-code-action本身就支持并发控制我在多个PR密集提交时叠加了团队级别的concurrency限流计费压力小了不少。把Claude Code的评审结果作为后续Job的门禁。比如在第一个job里让Claude Code分析代码质量然后解析输出若发现严重问题就fail掉后续的构建/部署job。这其实是把代码评审结果变成CI门禁比单纯跑linter要深入得多。我在一个中等规模仓库里跑了两个月整体感受是claude-code-action的集成价值不在替代人工reviewer而在让AI自动处理机械性的代码风格、规范类问题把人工reviewer省出来的时间集中到真正需要思考的架构和业务逻辑上。它能做得比人稳定不会被PR数量吓到但也比人死板没有全局视野容易在局部问题上钻牛角尖。10. 完整yml配置示例与参数速查最后把我在生产环境里验证过的一个完整示例贴出来方便你直接抄作业。这个配置同时打开了PR评论和Job Summary并且限制了Claude Code的试错次数name: Claude Code Audit on: pull_request: types: [opened, synchronize] workflow_dispatch: permissions: contents: read pull-requests: write jobs: claude-audit: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Claude Code audit uses: davila7/claude-code-actionv1 with: anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} prompt: | Audit this PR for: - style regressions - potential runtime errors - missing test coverage Output a concise Markdown report with a severity level for each issue. system-prompt: | You are an expert code reviewer embedded in CI. Be precise and avoid generic advice. Use file paths and line numbers. env: | PR_NUMBER: ${{ github.event.pull_request.number }}一些参数速查也放这里参数作用建议值anthropic-api-keyAnthropic API密钥${{ secrets.ANTHROPIC_API_KEY }}github-tokenGitHub Token用于评论和提交${{ secrets.GITHUB_TOKEN }}prompt任务提示词尽量具体包含步骤和输出格式system-prompt系统级角色定义控制语气和行为边界model模型版本默认即可按需求换max-failures自动修代码的最大重试次数3weight变更优先级权重0表示低优先级1表示高优先级env传给Claude Code的额外环境变量按需定义commit-message自动提交时的commit信息明确描述别留空run-command完全自定义的Claude Code CLI命令适合进阶用户在实际操作中我个人最常踩的坑仍然是权限那一层其次是prompt写得不够细。每次觉得Claude Code怎么这都没做到时先回头看自己是否在prompt里限制了它的表现空间。毕竟版本更新快具体参数名可能有调整但如果思路对了换什么Action都能跑得转。