GitHub Actions 集成 Claude Code 完整指南

本文是对官方文档 Claude Code GitHub Actions 的中文要点摘要，完整内容以原文为准。

是什么？能做什么？

Claude Code GitHub Actions 将 AI 自动化能力直接嵌入 GitHub 工作流。只需在 PR 或 Issue 评论中 @claude，Claude 即可：

• 分析代码并创建包含完整改动的 PR
• 将 Issue 描述直接转化为可运行代码
• 自动修复 Bug，并遵守 CLAUDE.md 中定义的项目规范
• 响应定时任务（如每日提交摘要）

代码全程运行在 GitHub 的 runner 上，默认不离开 GitHub 环境。

安装方式

快速安装（推荐）

在本地终端打开 Claude Code，执行：

/install-github-app

该命令会引导完成 GitHub App 安装和 Secrets 配置。

注意事项：

• 需要仓库管理员权限
• GitHub App 会申请 Contents、Issues、Pull requests 的读写权限
• 仅适用于直接调用 Anthropic API 的用户；使用 Amazon Bedrock 或 Google Vertex AI 的用户需手动配置

手动安装（三步）

1. 安装官方 GitHub App：https://github.com/apps/claude
2. 在仓库 Secrets 中添加 ANTHROPIC_API_KEY
3. 将示例工作流文件复制到 .github/workflows/

安装完成后，在任意 Issue 或 PR 评论中 @claude 即可验证是否生效。

从 Beta 升级到 v1.0

v1.0 引入破坏性变更，Beta 用户必须修改工作流文件方可升级。

迁移示例：

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

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

典型工作流示例

基础触发工作流（响应 @claude 评论）：

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

定时自动化任务：

on:
  schedule:
    - cron: 0 9 * * *
steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
      prompt: Generate a summary of yesterday commits and open issues
      claude_args: --model opus

评论中的常见触发语句：

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

核心配置参数

常用 claude_args：

• --max-turns 5：限制最大对话轮次
• --model claude-sonnet-4-6：指定模型
• --allowedTools：限制可用工具范围
• --mcp-config：加载 MCP 配置文件
• --debug：开启调试输出

企业环境：Bedrock 与 Vertex AI 集成

对于需要控制数据驻留或自定义计费的企业，可将 Claude Code Actions 对接到自有云基础设施。

Amazon Bedrock

1. 在 AWS 中配置 GitHub OIDC Identity Provider，创建具有 Bedrock 权限的 IAM Role
2. 在仓库 Secrets 中添加 AWS_ROLE_TO_ASSUME
3. 工作流中设置 use_bedrock: true，模型名需加区域前缀，例如 us.anthropic.claude-sonnet-4-6

Google Vertex AI

1. 在 GCP 项目中启用所需 API：IAM Credentials API、Security Token Service (STS) API、Vertex AI API
2. 配置 Workload Identity Federation
3. 创建仅具有 Vertex AI User 角色的服务账号
4. 在 Secrets 中添加 GCP_WORKLOAD_IDENTITY_PROVIDER 和 GCP_SERVICE_ACCOUNT
5. 工作流中设置 use_vertex: true

两种方案均推荐使用 OIDC/Workload Identity Federation，避免存储静态凭证。企业场景下官方建议创建自定义 GitHub App，而非使用 Anthropic 官方 App，以获得更强的权限控制与品牌化能力。

最佳实践与费用控制

安全：

• API Key 必须放在 GitHub Secrets，用 ${{ secrets.ANTHROPIC_API_KEY }} 引用，绝不硬编码
• 仅授予 Action 所需的最小权限，--allowedTools 可进一步收窄工具范围

项目规范：

• 在仓库根目录创建 CLAUDE.md，定义代码风格、审查标准与项目规则，内容保持简洁聚焦

费用控制：

• 设置 --max-turns 防止无限循环
• 配置工作流级别的 timeout-minutes 避免任务失控
• 使用 GitHub concurrency 控制并行 run 数量
• 注意：每次交互同时消耗 GitHub Actions 分钟数和 Anthropic API Token

故障排查

• @claude 无响应：检查 GitHub App 是否已安装、工作流是否启用、Secrets 名称是否正确（注意是 @claude 不是 /claude）
• Claude 的提交未触发 CI：确认使用了 GitHub App Token，而非 Actions 默认用户
• 认证错误：检查 API Key 有效性；Bedrock/Vertex 场景下核对 Secrets 名称与 IAM 权限配置