Claude Code GitHub Actions 让你在 PR 或 Issue 评论中通过 @claude 触发 AI 自动操作——代码审查、功能实现、Bug 修复，全部遵循项目的 CLAUDE.md 规范。安装可通过终端 /install-github-app 快速完成，也可手动配置；支持直接使用 Anthropic API 或通过 OIDC 集成 AWS Bedrock / Google Vertex AI。v1.0 GA 版简化了参数（统一 prompt 输入，claude_args 透传 CLI 选项），自动检测交互模式，Beta 用户需按迁移表更新工作流文件。

Claude Code GitHub Actions：用 @claude 触发 AI 自动化

Claude Code GitHub Actions 是 Anthropic 官方提供的 GitHub Action，让你在任何 Pull Request 或 Issue 中通过 @claude 提及即可让 Claude 分析代码、创建 PR、实现功能、修复 Bug。它基于 Claude Agent SDK 构建，并默认使用 Sonnet 模型（可配置为 Opus 4.7，详见下方参数）。

自动在每个 PR 上发布评审（无需触发词）的功能，见 GitHub Code Review。

为什么用 Claude Code GitHub Actions？

即时 PR 创建：描述需求，Claude 创建包含所有变更的完整 PR
自动代码实现：将 Issue 转为可直接运行的代码
遵循你的标准：读取项目的 CLAUDE.md 和现有代码模式
简单安装：/install-github-app 几分钟完成
默认安全：代码在 GitHub 的 runner 上运行，不离开你的基础设施

安装

快速安装（推荐）

在 Claude Code 终端中运行：

/install-github-app

此命令会引导你完成 GitHub App 安装和所需 Secrets 配置。

注意：

必须是仓库管理员才能安装 GitHub App 和添加 Secrets

GitHub App 将请求 Contents、Issues、Pull requests 的读写权限

此方式仅适用于直接使用 Anthropic API 的用户；若使用 Amazon Bedrock 或 Google Vertex AI，请参见下方使用 AWS Bedrock 或 Google Vertex AI

手动安装

如果 /install-github-app 命令失败或你偏好手动配置：

安装 Claude GitHub App 到你的仓库：https://github.com/apps/claude

所需仓库权限：
- Contents：Read & write（修改仓库文件）
- Issues：Read & write（响应 Issues）
- Pull requests：Read & write（创建 PR 和推送变更）
将 ANTHROPIC_API_KEY 添加到仓库 Secrets（GitHub Secrets 文档）
复制工作流文件：将 examples/claude.yml 放入你的 .github/workflows/

安装后，在 Issue 或 PR 评论中触发 @claude 以测试。

从 Beta 升级到 v1.0

v1.0 GA 版引入了破坏性变更，Beta 用户需更新工作流文件。

必须更改的内容

更新 Action 版本：将 @beta 改为 @v1
删除 mode 配置：删除 mode: "tag" 或 mode: "agent"（现在自动检测）
更新 prompt 输入：将 direct_prompt 改为 prompt
移动 CLI 选项：将 max_turns、model、custom_instructions 等移入 claude_args

变更对照表

旧 Beta 输入	新 v1.0 输入
`mode`	已删除，自动检测
`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 格式

前后对比

Beta 版：

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Follow our coding standards"
    max_turns: "10"
    model: "claude-sonnet-4-6"

GA v1.0：

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "Follow our coding standards"
      --max-turns 10
      --model claude-sonnet-4-6

Action 现在会基于你的配置自动检测运行模式：交互模式（响应 @claude 提及）或自动化模式（直接执行 prompt）。

使用示例

基础工作流：监听 Issue/PR 评论

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

使用技能（Skills）

prompt 输入支持引用仓库 .claude/skills/ 中的技能或插件中的技能。

使用本地技能：先执行 actions/checkout，然后传入 /skill-name
使用插件技能：通过 plugin_marketplaces 和 plugins 安装插件后，传入 /plugin-name:skill-name

以下工作流在每次新的 PR 或更新时，安装 code-review 插件并运行其技能：

name: Code 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 }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

定时自动化任务

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  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"
          claude_args: "--model opus"

常用 @claude 命令

在 Issue 或 PR 评论中直接写入：

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

Claude 会自动分析上下文并响应。

使用 AWS Bedrock 或 Google Vertex AI

企业环境下可以通过自己的云基础设施运行 Claude Code，掌控数据驻留和计费。

前置条件：创建自定义 GitHub App（推荐）

使用第三方云时，建议创建自己的 GitHub App 以获得最佳控制和安全性：

前往 https://github.com/settings/apps/new
填写基本信息：App 名称（例如“YourOrg Claude Assistant”）、Homepage URL
配置：取消勾选 Webhooks（“Active”）
设置权限：Contents（Read & write）、Issues（Read & write）、Pull requests（Read & write）
创建 App，然后点击“Generate a private key”下载 .pem 文件
记下 App ID
安装 App 到指定仓库（“Only select repositories”）
将私钥内容作为仓库 Secret APP_PRIVATE_KEY
将 App ID 作为仓库 Secret APP_ID

该 App 将配合 actions/create-github-app-token Action 生成认证令牌。

配置云认证

AWS Bedrock

前置条件：

Amazon Bedrock 已启用所需 Claude 模型访问
GitHub 在 AWS 中配置为 OIDC 身份提供商
IAM 角色具有 Bedrock 权限并信任 GitHub Actions

设置步骤：

启用 Bedrock 并请求 Claude 模型访问
创建 GitHub OIDC 身份提供商（Provider URL: https://token.actions.githubusercontent.com，Audience: sts.amazonaws.com）
创建 IAM 角色（Web identity，附加 AmazonBedrockFullAccess 策略，信任策略限定为你的仓库）
记录 IAM 角色 ARN（AWS_ROLE_TO_ASSUME）

所需 Secrets：AWS_ROLE_TO_ASSUME, APP_ID, APP_PRIVATE_KEY

工作流示例：

name: Claude PR Action

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude-pr:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - uses: actions/checkout@v4
      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
      - name: Configure AWS Credentials (OIDC)
        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:
          github_token: ${{ steps.app-token.outputs.token }}
          use_bedrock: "true"
          claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'

Bedrock 的模型 ID 需包含区域前缀，例如 us.anthropic.claude-sonnet-4-6。

Google Vertex AI

前置条件：

GCP 项目启用 Vertex AI API
为 GitHub 配置 Workload Identity Federation
服务账号具有 Vertex AI User 角色

设置步骤：

启用以下 API：IAM Credentials API、Security Token Service (STS) API、Vertex AI API
创建 Workload Identity Pool，添加 GitHub OIDC Provider（Issuer: https://token.actions.githubusercontent.com），设置属性映射并推荐按仓库限定条件
创建服务账号（仅授 Vertex AI User 角色）
配置 IAM 绑定，允许 Workload Identity Pool 模拟服务账号
记录 Workload Identity Provider 资源名称和 Service Account 邮箱

所需 Secrets：GCP_WORKLOAD_IDENTITY_PROVIDER, GCP_SERVICE_ACCOUNT, APP_ID, APP_PRIVATE_KEY

工作流示例：

name: Claude PR Action

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]

jobs:
  claude-pr:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
      - name: Authenticate to Google Cloud
        id: auth
        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:
          github_token: ${{ steps.app-token.outputs.token }}
          trigger_phrase: "@claude"
          use_vertex: "true"
          claude_args: '--model claude-sonnet-4-5@20250929 --max-turns 10'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5
          VERTEX_REGION_CLAUDE_4_5_SONNET: us-east5

Project ID 会自动从 Google Cloud 认证步骤获取，无需硬编码。

最佳实践

CLAUDE.md 配置

在仓库根目录创建 CLAUDE.md，定义代码风格、审查规则、项目特定要求和首选模式。Claude 会遵循这些规则。更多见 Memory 文档。

安全注意事项

API Key 必须使用 GitHub Secrets，不要硬编码在工作流中。
使用 ${{ secrets.ANTHROPIC_API_KEY }} 引用。
限制 Action 权限为最低所需。
合并前审查 Claude 的建议。

完整安全指南见 Claude Code Action 安全文档。

费用控制

GitHub Actions 费用：Claude Code 在 GitHub-hosted runner 上运行，消耗你的 Actions 分钟数。详情见 GitHub 计费文档。
API 费用：每次交互消耗 tokens，用量取决于任务复杂度和代码库大小。见 Claude 定价页。
优化建议：
- 使用具体的 @claude 命令减少不必要调用
- 在 claude_args 中设置 --max-turns 防止过多迭代
- 设置工作流级别超时
- 使用 GitHub 并发控制限制并行运行

Action 参数参考

v1.0 统一参数结构：

参数	说明	是否必填
`prompt`	对 Claude 的指令（纯文本或技能名称）	否*
`claude_args`	传递给 Claude Code 的 CLI 参数	否
`plugin_marketplaces`	插件市场 Git URL 列表（换行分隔）	否
`plugins`	要安装的插件名称列表（换行分隔）	否
`anthropic_api_key`	Claude API Key	是**
`github_token`	GitHub API 访问令牌	否
`trigger_phrase`	自定义触发词（默认 `@claude`）	否
`use_bedrock`	使用 Amazon Bedrock 而非 Claude API	否
`use_vertex`	使用 Google Vertex AI 而非 Claude API	否

* 在 Issue/PR 评论模式下可选，Claude 响应触发词；直接使用 prompt 时必填
** 直接使用 Anthropic API 时必填；Bedrock/Vertex 模式下不需要

常用 `claude_args`

claude_args: "--max-turns 5 --model claude-sonnet-4-6 --mcp-config /path/to/config.json"

常用选项：

--max-turns：最大对话轮数（默认 10）
--model：模型（例如 claude-sonnet-4-6、claude-opus-4-7）
--mcp-config：MCP 配置路径
--allowedTools：允许的工具列表（逗号分隔）
--debug：开启调试输出

故障排查

问题	检查点
Claude 不响应 `@claude`	GitHub App 是否已安装？工作流是否启用？API Key 是否已设置？评论中是否包含 `@claude`（而非 `/claude`）？
CI 不在 Claude 的提交上运行	确保使用 GitHub App 或自定义 App（而非 Actions user），检查工作流触发器，确认 App 权限包含 CI 触发器
认证错误	确认 API Key 有效且具有足够权限；对于 Bedrock/Vertex，检查凭据配置和 Secrets 名称是否正确

常见问题

@claude 在评论中不响应怎么办？

确认 GitHub App 已正确安装到仓库，工作流文件未被禁用，ANTHROPIC_API_KEY 已添加到仓库 Secrets，并且评论内容确实包含 @claude（注意斜杠的方向）。如果使用了自定义 trigger_phrase，确保匹配。

从 Beta 升级到 v1.0 后工作流报错怎么办？

参考上方“从 Beta 升级到 v1.0”章节，对照变更表修改工作流文件：更新版本为 @v1，删除 mode，将 direct_prompt 改为 prompt，将 max_turns、model、custom_instructions 等参数移入 claude_args。如果仍然失败，请查看运行日志中的具体错误信息。

如何限制 Claude 只能使用部分工具？

在 claude_args 中使用 --allowedTools 参数，逗号分隔工具名（例如 --allowedTools Read,Edit,Search）。相应的不允许工具可使用 --disallowedTools。

Claude Code GitHub Actions：用 @claude 触发 AI 自动化 #

为什么用 Claude Code GitHub Actions？ #

安装 #

快速安装（推荐） #

手动安装 #

从 Beta 升级到 v1.0 #

必须更改的内容 #

变更对照表 #

前后对比 #

使用示例 #

基础工作流：监听 Issue/PR 评论 #

使用技能（Skills） #

定时自动化任务 #

常用 @claude 命令 #

使用 AWS Bedrock 或 Google Vertex AI #

前置条件：创建自定义 GitHub App（推荐） #

配置云认证 #

AWS Bedrock #

Google Vertex AI #

最佳实践 #

CLAUDE.md 配置 #

安全注意事项 #

费用控制 #

Action 参数参考 #

常用 claude_args #

故障排查 #

常见问题 #

@claude 在评论中不响应怎么办？ #

从 Beta 升级到 v1.0 后工作流报错怎么办？ #

如何限制 Claude 只能使用部分工具？ #