CI 集成（GitHub Actions）

把 Claude Code 接入 GitHub Actions，在 PR/issue 里 @claude 即可让 AI 自动分析代码、实现功能、修 bug、开 PR。

是什么

Claude Code GitHub Actions 是把 AI 自动化带进 GitHub 工作流的官方集成。在任意 PR 或 issue 里写一句 @claude 提及，Claude 就能分析代码、创建 PR、实现功能、修复 bug，全程遵循你项目的 CLAUDE.md 规范。它由官方 GitHub Action anthropics/claude-code-action 提供，构建在 Claude Agent SDK 之上，代码始终留在 GitHub 的 runner 上（secure by default）。注意：若要每个 PR 无需触发就自动 review，应看 GitHub Code Review（/en/code-review）而非本功能。

怎么工作

核心是 GitHub Action anthropics/claude-code-action@v1，跑在 GitHub-hosted runner（ubuntu-latest）上，代码不出 GitHub runner；它构建在 Claude Agent SDK 之上
v1 自动检测运行模式：issue/PR 评论场景进入 interactive 模式（响应 @claude 提及），提供了 prompt 则进入 automation 模式（立即按 prompt 执行）。beta 的 mode: tag/agent 已删除改为自动检测
触发靠 GitHub 事件 + 工作流 if 条件判断评论体是否 contains '@claude'；支持任意 GitHub 事件：issue_comment、pull_request_review_comment、issues、pull_request、schedule(cron) 等
认证默认走 Claude API（读 secret ANTHROPIC_API_KEY）；企业可切 use_bedrock: true 或 use_vertex: true，用 OIDC / Workload Identity Federation 免存静态凭证
配置统一化：prompt 给指令，claude_args 透传任意 Claude Code CLI 参数（--max-turns、--model、--mcp-config、--allowedTools 等）
Claude 读取仓库根目录 CLAUDE.md 作为项目规范，在创建 PR、响应请求时遵循
Claude 提交的 commit 想触发后续 CI 必须用 GitHub App（官方或自建），不能用默认 Actions user

怎么配置 / 用法

触发方式：在 PR/issue 评论里 @claude（默认触发短语，可用 trigger_phrase 改）。

安装（推荐）：终端打开 claude 运行 /install-github-app，按引导装 GitHub app + 写 secrets（需仓库 admin）。

手动安装三步：

装官方 app https://github.com/apps/claude（权限 Contents/Issues/Pull requests 均 Read & write）
仓库 secret 加 ANTHROPIC_API_KEY
把 examples/claude.yml 拷到 .github/workflows/

最小工作流：

yaml

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

自定义 prompt + CLI 透传：

yaml

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Your instructions here"
    claude_args: "--max-turns 5 --model claude-sonnet-4-6 --mcp-config /path/to/config.json"

用 Skill：在 action 步骤前先 actions/checkout，prompt 传 /skill-name（仓库 .claude/skills/）；插件 skill 用 plugin_marketplaces + plugins 安装后传 /plugin-name:skill-name。

切到 Opus 4.8：claude_args 配 --model claude-opus-4-8（默认是 Sonnet）。

什么时候用

想用一句 @claude 把 issue 描述直接变成可工作的代码 / 完整 PR 时
想在评论里让 Claude 解释如何实现某功能、或定点修 bug（如 @claude fix the TypeError）时
想做自定义自动化：定时任务（schedule cron 生成日报）、对每个 opened/synchronize 的 PR 跑 skill 做 code review 时
企业需要数据驻留 / 自有计费时——切 Amazon Bedrock 或 Google Vertex AI
别用此功能做无触发的全量自动 PR review：那是 GitHub Code Review（/en/code-review）的活
若想在 GitHub Actions 之外做编程式集成，应直接用 Claude Agent SDK 而非本 Action

限制 / 坑

v1.0 相对 beta 有破坏性变更（breaking changes），从 beta 升级必须改工作流文件，否则不兼容
/install-github-app 快速安装仅对 Claude API 直连用户可用；Bedrock/Vertex 必须走企业手动配置
安装 GitHub app 与加 secret 都要求仓库 admin 权限
触发短语必须精确是 @claude，写成 /claude 不触发
Claude 用默认 Actions user 提交时其 commit 不会触发后续 CI——必须用 GitHub App 或自建 app，且 app 权限要含 CI 触发
--max-turns 默认 10，过大会导致过度迭代和 token 浪费；建议配合 workflow timeout 与 concurrency 控制避免 runaway job
绝不能把 API key 硬编码进工作流/提交进仓库，必须用 GitHub Secrets
anthropic_api_key 对 Claude API 直连必填，对 Bedrock/Vertex 不需要（改用云认证）
Claude 的建议在合并前需人工 review（官方明确提示 Review Claude's suggestions before merging）
Bedrock 模型 ID 必须带区域前缀（us.anthropic.claude-sonnet-4-6），写错会失败；跨区域模型需在所有相关区域申请访问

硬事实速查（20 条）

Action 名：anthropics/claude-code-action@v1（beta 升 v1：@beta 改 @v1）
快速安装命令：终端 claude 里运行 /install-github-app（仅 Claude API 直连用户可用；Bedrock/Vertex 需走手动/企业流程）
安装需仓库 admin 权限
官方 GitHub App 地址：https://github.com/apps/claude，要求权限 Contents、Issues、Pull requests 全部 Read & write
工作流文件目录：.github/workflows/；官方示例文件 examples/claude.yml
API key secret 名固定为 ANTHROPIC_API_KEY，引用方式 ${{ secrets.ANTHROPIC_API_KEY }}
默认触发短语 @claude（不是 /claude）；可用 trigger_phrase 改
默认模型是 Sonnet；切 Opus 4.8 用 claude_args 配 --model claude-opus-4-8
Action 输入参数：prompt（指令或 skill 名，非必填）、claude_args（CLI 参数，非必填）、plugin_marketplaces（换行分隔的插件市场 Git URL）、plugins（换行分隔的待装插件名）、anthropic_api_key（必填*，Bedrock/Vertex 除外）、github_token（GitHub token，非必填）、trigger_phrase（默认 @claude）、use_bedrock、use_vertex
claude_args 常用参数：--max-turns（默认 10）、--model（如 claude-sonnet-4-6）、--mcp-config（MCP 配置路径）、--allowedTools（逗号分隔，别名 --allowed-tools）、--disallowedTools、--debug、--append-system-prompt
beta→v1 输入映射：direct_prompt→prompt；override_prompt→prompt+GitHub 变量；custom_instructions→claude_args: --append-system-prompt；max_turns→claude_args: --max-turns；model→claude_args: --model；allowed_tools→claude_args: --allowedTools；disallowed_tools→claude_args: --disallowedTools；claude_env→settings JSON 格式；mode 删除
Skill 用法：仓库 .claude/skills/ 下的 skill 先跑 actions/checkout 再传 /skill-name；插件 skill 用 plugin_marketplaces + plugins 装好后传命名空间形式 /plugin-name:skill-name
插件 skill 示例：plugin_marketplaces: "https://github.com/anthropics/claude-code.git"，plugins: "code-review@claude-code-plugins"
自建 GitHub App（企业/第三方 provider 推荐）：地址 https://github.com/settings/apps/new，关闭 Webhooks Active，配 Contents/Issues/Pull requests 读写，生成 .pem 私钥，记下 App ID；secret 存 APP_ID 与 APP_PRIVATE_KEY，配合 actions/create-github-app-token@v2 生成 token
Bedrock：use_bedrock: "true"，OIDC provider URL https://token.actions.githubusercontent.com，Audience sts.amazonaws.com，IAM 策略 AmazonBedrockFullAccess，secret AWS_ROLE_TO_ASSUME；模型 ID 带区域前缀如 us.anthropic.claude-sonnet-4-6；示例 AWS_REGION/aws-region us-west-2
Vertex AI：use_vertex: "true"，需 IAM Credentials API、STS API、Vertex AI API；secret GCP_WORKLOAD_IDENTITY_PROVIDER 与 GCP_SERVICE_ACCOUNT（仅授 Vertex AI User 角色）；env ANTHROPIC_VERTEX_PROJECT_ID、CLOUD_ML_REGION: us-east5、VERTEX_REGION_CLAUDE_4_5_SONNET: us-east5；模型如 claude-sonnet-4-5@20250929
企业工作流 permissions 需含：contents: write、pull-requests: write、issues: write、id-token: write
企业工作流用 github_token: ${{ steps.app-token.outputs.token }} 而非 anthropic_api_key（Bedrock/Vertex 自带云认证）
成本两部分：GitHub Actions runner 消耗 Actions 分钟数；Claude API 按 prompt/响应 token 计费
自动回复 PR 评论时无需 prompt，Claude 自动响应 @claude 提及；其他事件需用 prompt 提供指令

官方出处：https://code.claude.com/docs/en/github-actions

CI 集成（GitHub Actions） ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​

硬事实速查（20 条） ​