Claude Code GitHub Actions

了解如何通过 Claude Code GitHub Actions 将 Claude Code 集成到您的开发工作流中

Claude Code GitHub Actions 为您的 GitHub 工作流带来 AI 驱动的自动化。只需在 PR 或 issue 中简单 @claude 提及，Claude 即可分析您的代码、创建拉取请求、实现功能并修复错误——同时遵循您项目的标准。如需在每次 PR 上自动发布无需触发器的审查，请参阅 GitHub 代码审查。

为何使用 Claude Code GitHub Actions？

• 即时创建 PR：描述您的需求，Claude 即可创建包含所有必要更改的完整 PR
• 自动化代码实现：通过单一命令将 issue 转化为可运行的代码
• 遵循您的标准：Claude 尊重您的 CLAUDE.md 指南和现有代码模式
• 简单设置：通过我们的安装程序和 API 密钥，几分钟内即可开始使用
• 默认安全：您的代码保留在 GitHub 的运行器上

Claude 能做什么？

Claude Code 提供强大的 GitHub Action，彻底改变您处理代码的方式：

Claude Code Action

此 GitHub Action 允许您在 GitHub Actions 工作流中运行 Claude Code。您可以基于 Claude Code 构建任何自定义工作流。

查看仓库 →

设置

快速设置

在 Claude Code 终端中运行 /install-github-app 以交互方式设置集成。该命令会在您的仓库上安装 Claude GitHub App，然后引导您添加 GitHub Actions 工作流和 API 密钥密钥。

GitHub App 安装后，命令会询问是否继续 GitHub Actions 设置。在 Claude Code v2.1.187 及更高版本中，您可以选择暂时跳过，仅完成 App 安装，之后再次运行 /install-github-app 返回工作流和密钥步骤。早期版本会直接继续工作流选择。

手动设置

如果 /install-github-app 命令失败或您偏好手动设置，请按照以下手动设置说明操作：

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

   Claude GitHub App 需要以下仓库权限：

   • Contents：读写（用于修改仓库文件）
   • Issues：读写（用于响应 issue）
   • Pull requests：读写（用于创建 PR 和推送更改）

   有关安全和权限的更多详情，请参阅 安全文档。

2. 将 ANTHROPIC_API_KEY 添加到您的仓库密钥（了解如何在 GitHub Actions 中使用密钥）

3. 将工作流文件从 examples/claude.yml 复制到您仓库的 .github/workflows/ 目录

从 Beta 版升级

如果您当前正在使用 Claude Code GitHub Actions 的 Beta 版本，我们建议您更新工作流以使用 GA 版本。新版本简化了配置，同时添加了强大的新功能，如自动模式检测。

必要变更

所有 Beta 用户必须对其工作流文件进行以下更改才能升级：

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

破坏性变更参考

前后对比示例

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-5"

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

使用示例

Claude Code GitHub Actions 可以帮助您完成各种任务。examples 目录包含适用于不同场景的现成工作流。

基础工作流

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 提及

使用技能

prompt 输入接受 skill 调用以及纯文本：

• 对于仓库 .claude/skills/ 目录中的技能，在 Action 步骤前运行 actions/checkout 并传递 /skill-name。
• 对于打包在插件中的技能，使用 plugin_marketplaces 和 plugins 输入安装插件，并传递命名空间的 /plugin-name:skill-name。

以下工作流安装 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 }}"

使用 Prompt 的自定义自动化

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"

常见使用场景

在 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 将自动分析上下文并做出适当响应。

最佳实践

CLAUDE.md 配置

在仓库根目录创建 CLAUDE.md 文件，以定义代码风格指南、审查标准、项目特定规则和首选模式。此文件指导 Claude 理解您的项目标准。

安全注意事项

有关权限、身份验证和最佳实践的全面安全指南，请参阅 Claude Code Action 安全文档。

始终使用 GitHub Secrets 存储 API 密钥：

• 将您的 API 密钥添加为名为 ANTHROPIC_API_KEY 的仓库密钥
• 在工作流中引用：anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
• 将 Action 权限限制为仅必要的范围
• 合并前审查 Claude 的建议

始终使用 GitHub Secrets（例如 ${{ secrets.ANTHROPIC_API_KEY }}），而非直接在工作流文件中硬编码 API 密钥。

优化性能

使用 issue 模板提供上下文，保持 CLAUDE.md 简洁聚焦，并为您的工作流配置适当的超时时间。

CI 成本

使用 Claude Code GitHub Actions 时，请注意相关成本：

GitHub Actions 成本：

• Claude Code 在 GitHub 托管的运行器上运行，会消耗您的 GitHub Actions 分钟数
• 有关详细定价和分钟数限制，请参阅 GitHub 计费文档

API 成本：

• 每次 Claude 交互根据 prompt 和响应的长度消耗 API token
• Token 使用量因任务复杂度和代码库大小而异
• 有关当前 token 费率，请参阅 Claude 定价页面

成本优化建议：

• 使用特定的 @claude 命令减少不必要的 API 调用
• 在 claude_args 中配置适当的 --max-turns 以防止过度迭代
• 设置工作流级别的超时以避免失控作业
• 考虑使用 GitHub 的并发控制来限制并行运行

配置示例

Claude Code Action v1 通过统一参数简化了配置：

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Your instructions here" # 可选
    claude_args: "--max-turns 5" # 可选 CLI 参数

主要特性：

• 统一的 prompt 接口 - 对所有指令使用 prompt
• 技能 - 直接从 prompt 调用已安装的 skills
• CLI 透传 - 通过 claude_args 传递任何 Claude Code CLI 参数
• 灵活的触发器 - 适用于任何 GitHub 事件

访问 examples 目录 获取完整的工作流文件。

与 Amazon Bedrock 和 Google Cloud 配合使用

对于企业环境，您可以将 Claude Code GitHub Actions 与自有云基础设施配合使用。这种方式让您在保持相同功能的同时，控制数据驻留和计费。

前提条件

在设置 Claude Code GitHub Actions 与云提供商之前，您需要：

对于 Google Cloud 的 Agent Platform：

1. 启用了 Google Cloud 的 Agent Platform 的 Google Cloud 项目
2. 为 GitHub Actions 配置了 Workload Identity Federation
3. 具有所需权限的服务账号
4. GitHub App（推荐）或使用默认的 GITHUB_TOKEN

对于 Amazon Bedrock：

1. 启用了 Amazon Bedrock 的 AWS 账户
2. 在 AWS 中配置了 GitHub OIDC Identity Provider
3. 具有 Amazon Bedrock 权限的 IAM 角色
4. GitHub App（推荐）或使用默认的 GITHUB_TOKEN

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:
      - name: Checkout repository
        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'

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:
      - name: Checkout repository
        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

故障排查

Claude 不响应 @claude 命令

验证 GitHub App 是否正确安装，检查工作流是否已启用，确保 API 密钥已设置在仓库密钥中，并确认评论包含 @claude（而非 /claude）。

CI 不在 Claude 的提交上运行

确保您使用的是 GitHub App 或自定义应用（而非 Actions 用户），检查工作流触发器是否包含必要的事件，并验证应用权限是否包含 CI 触发器。

身份验证错误

确认 API 密钥有效且具有足够的权限。对于 Amazon Bedrock 或 Google Cloud 的 Agent Platform，检查凭证配置并确保工作流中的密钥名称正确。

高级配置

Action 参数

Claude Code Action v1 使用简化的配置：

*Prompt 是可选的 - 对于 issue/PR 评论，省略时 Claude 会响应触发短语
**直接 Claude API 需要，Amazon Bedrock 或 Google Cloud 的 Agent Platform 不需要

传递 CLI 参数

claude_args 参数接受任何 Claude Code CLI 参数：

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

常用参数：

• --max-turns：最大对话轮数（默认：10）
• --model：使用的模型（例如 claude-sonnet-5）
• --mcp-config：MCP 配置路径
• --allowedTools：允许的工具列表，逗号分隔。--allowed-tools 别名同样有效。
• --debug：启用调试输出

替代集成方法

虽然 /install-github-app 命令是推荐的方法，但您也可以：

• 自定义 GitHub App：对于需要品牌用户名或自定义身份验证流的组织。创建具有所需权限（contents、issues、pull requests）的自己的 GitHub App，并在工作流中使用 actions/create-github-app-token Action 生成令牌。
• 手动 GitHub Actions：直接配置工作流以获得最大灵活性
• MCP 配置：动态加载 Model Context Protocol 服务器

有关身份验证、安全和高级配置的详细指南，请参阅 Claude Code Action 文档。

自定义 Claude 的行为

您可以通过两种方式配置 Claude 的行为：

1. CLAUDE.md：在仓库根目录定义编码标准、审查标准和项目特定规则。Claude 在创建 PR 和响应请求时将遵循这些指南。有关更多详情，请参阅我们的 Memory 文档。
2. 自定义 prompts：使用工作流文件中的 prompt 参数提供工作流特定的指令。这允许您为不同的工作流或任务自定义 Claude 的行为。

Claude 在创建 PR 和响应请求时将遵循这些指南。