异步视界博客
iaieye.com

最近更新

    ↑↓ 选择↵ 打开esc 关闭

    GitHub Actions 集成:让 Claude 在 CI 里跑

    anthropics/claude-code-action@v1 GA。一行 `@claude implement this feature` 就够 —— Claude 进入团队 CI 流水线的官方门票。

    • Claude Code 功… · 10/16
    • 精读
    • 2026.05.13
    • 17 分钟
    • 8,591 字

    思思扬撰写 · AI 协作整理

    类型
    精读
    系列
    Claude Code 功能 + 集成生态调研(2026-05)
    位置
    第 10 篇 / 共 16 篇
    发布
    2026.05.13
    篇幅
    8,591 字 · 17 分钟
    章节
    8 节
    标签
    • claude-code
    • ai
    • github-actions
    • ci

    原文:https://code.claude.com/docs/en/github-actions 官方 Action:https://github.com/anthropics/claude-code-action(@v1 GA) GitHub App:https://github.com/apps/claude 官方定位:Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow.

    🔥 影响力卡片

    维度数据
    主要 repoanthropics/claude-code-action — 撰文时 @v1 GA(从 @beta 演进)
    一键安装/install-github-app(在 CLI 里跑)— 自动装 App、加 secret、写 workflow
    触发方式@claude mention(在 issue / PR / 评论里)+ 任意 GitHub event(schedule / push / pull_request 等)
    Provider 支持直连 Claude API、Amazon Bedrock(走 IAM OIDC)、Google Vertex AI(走 Workload Identity Federation)
    跟 Routines 区别GHA 在 GitHub runner 上跑(你写 yaml,有完整 CI 环境);Routines 在 Anthropic 云 上跑(Claude 自主操作)
    安全模型API key 走 GitHub Secrets;Claude GitHub App 用 OAuth-like 权限模型

    🎯 为什么必读

    1. 这是 Claude 进入团队 CI 流水线的官方门票。

    之前要让 AI 评 PR,要么自己写 webhook + 调 Anthropic API,要么用第三方工具(Greptile / CodeRabbit)。现在 Anthropic 自己出了 GitHub Action,一行 @claude implement this feature 就够。

    2. 跟 Routines 的关系:互补不冲突。

    场景用哪个
    想用 GitHub 完整 CI 环境(matrix / cache / artifacts / 已有 step)GHA
    想让 Claude 自主决定怎么做(open-ended task)Routines
    想 @claude 在 PR 评论里互动GHA
    想 GitHub event 触发(PR open / release publish)两个都能,但 Routines 更简单
    想自己控制 prompt / Skills / 模型GHA
    想让 Claude 在云上自己跑没有本地 runnerRoutines

    3. 给独立开发者的特别价值

    如果你的 demo 项目都有 CI,加一个 claude.yml 几乎 0 成本:

    • @claude review → 自动 PR 评论
    • schedule: cron: '0 9 * * *' → 每天早上自动检查所有 PR
    • @claude implement #42 → Claude 自己读 issue + 写代码 + 开 PR
    • 测试挂时自动 @claude fix the failing test

    一句话总结

    GitHub Actions 集成 = 在 GitHub Actions runner 上跑 anthropics/claude-code-action@v1,通过 @claude mention 或任意事件触发,跑完它有 GitHub PR / issue 写入权限,可以开 PR / 留评论 / 改文件。

    💎 金句墙

    ★ “Just open claude and run /install-github-app.” “打开 Claude,跑 /install-github-app 就完了。” —— 🟢 这是整个 ecosystem 里最甜的入门体验之一 — 不用读 docs,不用配 yaml,自己引导你完成

    ★ “The action now automatically detects whether to run in interactive mode (responds to @claude mentions) or automation mode (runs immediately with a prompt).” (v1 GA) “v1 自动判断是 interactive 模式(响应 @claude mention)还是 automation 模式(直接跑 prompt)。” —— 🟢 v1 比 beta 简单很多 — 不用再显式设 mode: "tag"

    ★ “Your code stays on Github’s runners.” “你的代码留在 GitHub runners 上。” —— 🟢 跟 Routines 的差别 — Routines 在 Anthropic 云跑,GHA 在 GitHub runners 跑 — 数据驻留 / 成本 / 工具可用性都不一样

    📋 核心精读

    1. 5 分钟接入(/install-github-app)

    > claude
    > /install-github-app

    它会引导你:

    1. 装 Claude GitHub App 到你的 repo
    2. 添加 ANTHROPIC_API_KEY 到 repo secrets
    3. 写一个 .github/workflows/claude.yml(从 examples 复制)
    4. 测试 @claude mention

    前提:你必须是 repo admin(才能装 App 和加 secret)。

    2. 最小 workflow 范例

    # .github/workflows/claude.yml
    name: Claude Code
    on:
      issue_comment:
        types: [created]
      pull_request_review_comment:
        types: [created]
    
    jobs:
      claude:
        runs-on: ubuntu-latest
        steps:
          - uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              # 默认响应 @claude mentions

    装好后,在任何 PR / issue 评论里 @claude implement this,Claude 就开始工作。

    3. 5 个真实场景

    A. @claude mention 互动

    最直接的用法。任何 issue / PR 评论里:

    @claude implement this feature based on the issue description
    @claude how should I implement user auth for this endpoint?
    @claude fix the TypeError in the user dashboard component
    @claude review this PR for security issues

    Claude 自动分析 context 并响应。

    B. PR 打开时自动 review

    on:
      pull_request:
        types: [opened, synchronize]
    jobs:
      review:
        runs-on: ubuntu-latest
        steps:
          - uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              prompt: "Review this PR for code quality, correctness, and security. Post findings as review comments."
              claude_args: "--max-turns 5"

    C. 定时跑(替代 cron 脚本)

    on:
      schedule:
        - cron: "0 9 * * *"
    jobs:
      daily-report:
        runs-on: ubuntu-latest
        steps:
          - uses: anthropics/claude-code-action@v1
            with:
              anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
              prompt: "Generate a summary of yesterday's commits and open issues. Post as a discussion comment."
              claude_args: "--model opus"

    D. issue 转代码

    # 在 issue 里:
    @claude implement #42
    # Claude 读 #42 → 写代码 → 开 PR

    E. 自定义 trigger phrase

    with:
      trigger_phrase: "/ai"
      # 现在 @claude 改成 /ai 触发

    4. claude_args — CLI 参数透传

    Action v1 把 Claude Code CLI 的所有参数都开放给你:

    claude_args: |
      --max-turns 5
      --model claude-opus-4-7
      --mcp-config /path/to/config.json
      --allowedTools "Read,Edit,Bash(git *)"
      --append-system-prompt "Follow our coding standards"

    常用参数:

    • --max-turns 5 — 防失控,默认 10
    • --model claude-opus-4-7 — 这里就配模型(GHA 默认 Sonnet)
    • --mcp-config path/to/.mcp.json — 装 MCP server(比如 Linear / Notion 连接)
    • --allowedTools "..." — 工具白名单
    • --debug — 排错时开

    5. v1 GA vs beta 的破坏性改动(必看,如果你之前装过 beta)

    旧(beta)新(v1)
    @beta@v1
    mode: "tag" 或 "agent"删了 — 自动检测
    direct_prompt: "..."prompt: "..."
    override_prompt: "..."prompt: + GitHub 变量
    custom_instructions: "..."claude_args: --append-system-prompt "..."
    max_turns: "10"claude_args: --max-turns 10
    model: "claude-sonnet-4-6"claude_args: --model claude-sonnet-4-6
    allowed_tools: "..."claude_args: --allowedTools "..."
    claude_env:settings: JSON

    升级路径:把 mode 字段删掉,把 direct_prompt → prompt,其他 flag 都进 claude_args,完成。

    6. 3 种 provider 配置

    直连 Claude API(最简单):

    with:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

    Amazon Bedrock(企业首选,数据驻留 AWS):

    permissions:
      id-token: write  # OIDC 必须
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-west-2
      - uses: anthropics/claude-code-action@v1
        with:
          use_bedrock: "true"
          claude_args: '--model us.anthropic.claude-sonnet-4-6'

    Google Vertex AI(企业首选,数据驻留 GCP):

    permissions:
      id-token: write
    steps:
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
      - uses: anthropics/claude-code-action@v1
        with:
          use_vertex: "true"
          claude_args: '--model claude-sonnet-4-5@20250929'

    Bedrock / Vertex 路径比直连 API 多一层 OIDC 凭证管理,但凭证短命且不需要 hardcode。

    7. 自定义 GitHub App(企业品牌化)

    默认用 Anthropic 官方 GitHub App,所有 commit 显示成 “claude[bot]”。

    如果想换成 “YourOrg Claude Assistant”:

    1. github.com/settings/apps/new 建新 app
    2. 权限:Contents R/W、Issues R/W、Pull requests R/W
    3. 生成 private key → 存到 repo secrets 为 APP_PRIVATE_KEY
    4. App ID → APP_ID
    5. workflow 用 actions/create-github-app-token@v2 拿 token

    适合企业;独立开发者用官方 App 就好。

    8. CI 关键配置(CLAUDE.md)

    repo 根目录的 CLAUDE.md 在 GitHub Actions 跑时自动加载(跟本地一样),指导 Claude 该项目的约定。

    # Project conventions
    
    ## Style
    - Tabs (not spaces)
    - semicolons required
    - functional components, no classes
    
    ## Testing
    - Run `bun test` before pushing
    - New features need tests
    - Don't mock the database

    写 CLAUDE.md = 配置 Claude 在 CI 里的行为。这是 GHA 集成跟其他 AI 代码工具最不同的地方:不是改 prompt,是改 repo 配置。

    9. 成本警告(必看)

    GHA 双重计费:

    GitHub Actions minutes(GitHub 那边):

    • 每次跑都消耗 runner minutes
    • 公开 repo 免费 unlimited;私有 repo 看你 plan
    • 长跑的 Claude 任务可能跑 5-10 分钟一个

    Claude API tokens(Anthropic 那边):

    • prompt + response 都计 token
    • 复杂任务可能几十万 token
    • Pro/Max 用户走订阅,不走 token billing

    控制成本的策略:

    claude_args: "--max-turns 5"   # 严格限步数
    timeout-minutes: 10            # workflow 超时
    
    concurrency:                    # 同时只跑一个
      group: claude-${{ github.ref }}
      cancel-in-progress: true

    10. CI 不跑 Claude 的 commit? — 常见坑

    GitHub 默认行为:用同一个 token 跑的 push 不会触发新 workflow。

    要让 Claude 的 commit 触发 CI:

    • 用 GitHub App(官方或自定义)token,不要用 ${{ secrets.GITHUB_TOKEN }}
    • 确保你的 workflow on: 包含 push / pull_request 事件
    • 检查 App 权限里有 CI 触发权

    11. 跟 Claude Code on the Web 的 PR review 区别

    Claude 还有一个自动 PR review 功能(/en/code-review):

    GitHub ActionsWeb Code Review
    触发你定义 yamlClaude 自动评论每个 PR
    运行GitHub runnerAnthropic 云
    配置claude_args + workflowclaude.ai 设置
    适合高度定制零配置

    简单说:普通 PR review → Code Review;复杂工作流 → GHA。

    🟢 译者总评

    1. GHA 是 Anthropic 把 “AI coder” 推进团队的关键产品

    独立开发者还能用 claude CLI 解决问题。团队里要让 AI 工作必须:

    • 不让某个人代表团队跟 AI 对话(那 Slack 上聊一聊就够了)
    • 让 AI 参与代码评审、issue 处理、release 流程 — 必须走 CI
    • 凭证管理、审计、回滚 — 都需要 git history

    GHA 是这套需求的标准答案。Anthropic 不出 GHA 集成,就没法把 Claude Code 卖给 Fortune 500 的工程团队。

    2. 给独立开发者的”够用”配方

    如果你有 3-5 个 demo 项目,每个都装一份 claude.yml,作用:

    场景yml 内容
    我开 PR 时自动 reviewon: pull_request + prompt: "Review for quality / security / TS errors"
    我 @claude fix 时去修on: issue_comment
    每周一早上写一份所有项目的 PR 摘要on: schedule cron: 0 9 * * 1 + prompt: "summarize all open PRs"

    总共 3 个 workflow,没什么维护成本,但工作流体验大幅提升。

    3. v1 GA 是稳定信号 — 可以放心写到生产

    @beta 期间 Anthropic 改动了 mode / direct_prompt / custom_instructions 等几个核心 API。v1 已经 GA,这些 API 不会再变。可以放心写到团队 workflow 里,不用担心半年后失效。

    4. 警惕的反模式

    • ❌ @claude 触发条件太宽(任意评论包含 “@claude” 字符串就触发)→ 容易误触
    • ❌ 不设 --max-turns → Claude 可能跑 10+ turns,烧 quota
    • ❌ 给 Claude bypassPermissions 类配置 → 在 CI 里没人监督,危险
    • ❌ 不配 concurrency: cancel-in-progress → 一个 PR 改 10 次会跑 10 次 Claude
    • ❌ 把 prompt 写得太抽象 → “review this PR” 不够,要说清审什么、不审什么

    🔗 延伸阅读

    4 条

    🔗 调研来源(可校验)

    • 主原文:https://code.claude.com/docs/en/github-actions
    • 官方 Action repo:github.com/anthropics/claude-code-action
    • 官方 GitHub App:github.com/apps/claude
    • v1 break changes 完整列表:本文档 “Breaking Changes Reference” 章节
    • changelog 验证:/install-github-app 命令本机可用(本机 v2.1.139)
    系列全部 16 篇
    1. 01Agent View:一个窗口管所有 Claude Code sessions13 分钟
    2. 02Remote Control:用浏览器和手机驱动本机的 Claude Code16 分钟
    3. 03Claude in Chrome:让 Claude Code 直接驾驶你的浏览器14 分钟
    4. 04Plugins + Marketplace:Claude Code 一切扩展的载体20 分钟
    5. 05Skills 系统:把再次输入的指令变成可加载的能力19 分钟
    6. 06Hooks:在 Claude Code 生命周期上挂触发器18 分钟
    7. 07MCP 客户端 + 第三方服务器生态18 分钟
    8. 08Subagents:Agent tool 调度专家小队20 分钟
    9. 09Routines / Scheduled Tasks / /loop:三层调度栈16 分钟
    10. 10GitHub Actions 集成:让 Claude 在 CI 里跑17 分钟
    11. 11Memory 系统:CLAUDE.md + auto memory19 分钟
    12. 12Channels:把外部事件推进活跃 session15 分钟
    13. 13IDE 集成:VSCode + JetBrains 扩展16 分钟
    14. 14Computer Use:让 Claude 真的操作你的电脑18 分钟
    15. 15Claude Code 概念全集 / 关键词速查表36 分钟
    16. 99附录:Claude 全产品矩阵中 Claude Code 的位置12 分钟