@claude,Claude 就可以分析您的代码、创建拉取请求、实现功能和修复错误 - 所有这些都遵循您项目的标准。如需在每个 PR 上自动发布评论而无需触发器,请参阅 GitHub Code Review。
Claude Code GitHub Actions 建立在 Claude Agent SDK 之上,该 SDK 支持将 Claude Code 以编程方式集成到您的应用程序中。您可以使用该 SDK 构建超越 GitHub Actions 的自定义自动化工作流。
为什么使用 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 返回工作流和密钥步骤。早期版本直接进行工作流选择。
- 您必须是仓库管理员才能安装 GitHub 应用并添加密钥
- GitHub 应用将请求对内容、Issue 和拉取请求的读写权限
- 此快速启动方法仅适用于直接 Claude API 用户。如果您使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform,请参阅 使用 Amazon Bedrock 和 Google Cloud 部分。
手动设置
如果/install-github-app 命令失败或您更喜欢手动设置,请按照以下手动设置说明进行操作:
-
安装 Claude GitHub 应用到您的仓库:https://github.com/apps/claude
Claude GitHub 应用需要以下仓库权限:
- Contents:读写(用于修改仓库文件)
- Issues:读写(用于响应 issue)
- Pull requests:读写(用于创建 PR 和推送更改)
- 添加 ANTHROPIC_API_KEY 到您的仓库密钥(了解如何在 GitHub Actions 中使用密钥)
-
复制工作流文件从 examples/claude.yml 到您的仓库的
.github/workflows/
从 Beta 升级
如果您当前使用 Claude Code GitHub Actions 的 beta 版本,我们建议您更新工作流以使用 GA 版本。新版本简化了配置,同时添加了强大的新功能,如自动模式检测。基本更改
所有 beta 用户必须对其工作流文件进行这些更改才能升级:- 更新 action 版本:将
@beta更改为@v1 - 删除模式配置:删除
mode: "tag"或mode: "agent"(现在自动检测) - 更新提示输入:将
direct_prompt替换为prompt - 移动 CLI 选项:将
max_turns、model、custom_instructions等转换为claude_args
重大更改参考
前后示例
Beta 版本:示例用例
Claude Code GitHub Actions 可以帮助您完成各种任务。examples 目录包含针对不同场景的现成工作流。基本工作流
使用 skills
prompt 输入接受 skill 调用以及纯文本:
- 对于存储库的
.claude/skills/目录中的 skill,在操作步骤之前运行actions/checkout,然后传递/skill-name。 - 对于打包在插件中的 skill,使用
plugin_marketplaces和plugins输入安装插件,然后传递命名空间的/plugin-name:skill-name。
code-review 插件并在每个新的或更新的拉取请求上运行其 skill:
使用提示的自定义自动化
常见用例
在 issue 或 PR 评论中:最佳实践
CLAUDE.md 配置
在您的仓库根目录创建一个CLAUDE.md 文件来定义代码风格指南、审查标准、项目特定规则和首选模式。此文件指导 Claude 对您的项目标准的理解。
安全考虑
有关全面的安全指导,包括权限、身份验证和最佳实践,请参阅 Claude Code Action 安全文档。 始终为 API 密钥使用 GitHub Secrets:- 将您的 API 密钥添加为名为
ANTHROPIC_API_KEY的仓库密钥 - 在工作流中引用它:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - 将 action 权限限制为仅必要的权限
- 在合并前审查 Claude 的建议
${{ secrets.ANTHROPIC_API_KEY }})而不是直接在工作流文件中硬编码 API 密钥。
优化性能
使用 issue 模板提供上下文,保持您的CLAUDE.md 简洁和专注,并为您的工作流配置适当的超时。
CI 成本
使用 Claude Code GitHub Actions 时,请注意相关成本: GitHub Actions 成本:- Claude Code 在 GitHub 托管的运行器上运行,这会消耗您的 GitHub Actions 分钟数
- 有关详细的定价和分钟限制,请参阅 GitHub 的计费文档
- 每次 Claude 交互都会根据提示和响应的长度消耗 API 令牌
- 令牌使用量因任务复杂性和代码库大小而异
- 有关当前令牌费率,请参阅 Claude 的定价页面
- 使用特定的
@claude命令来减少不必要的 API 调用 - 在
claude_args中配置适当的--max-turns以防止过度迭代 - 设置工作流级别的超时以避免失控的作业
- 考虑使用 GitHub 的并发控制来限制并行运行
配置示例
Claude Code Action v1 使用统一参数简化了配置:- 统一提示界面 - 对所有说明使用
prompt - Skills - 直接从提示调用已安装的 skills
- CLI 传递 - 通过
claude_args的任何 Claude Code CLI 参数 - 灵活的触发器 - 适用于任何 GitHub 事件
使用 Amazon Bedrock 和 Google Cloud
对于企业环境,您可以将 Claude Code GitHub Actions 与您自己的云基础设施一起使用。这种方法让您可以控制数据驻留和计费,同时保持相同的功能。前置条件
在使用云提供商设置 Claude Code GitHub Actions 之前,您需要:对于 Google Cloud 的 Agent Platform:
- 启用了 Google Cloud 的 Agent Platform 的 Google Cloud 项目
- 为 GitHub Actions 配置的工作负载身份联合
- 具有所需权限的服务账户
- GitHub 应用(推荐)或使用默认 GITHUB_TOKEN
对于 Amazon Bedrock:
- 启用了 Amazon Bedrock 的 AWS 账户
- 在 AWS 中配置的 GitHub OIDC 身份提供商
- 具有 Amazon Bedrock 权限的 IAM 角色
- GitHub 应用(推荐)或使用默认 GITHUB_TOKEN
1
创建自定义 GitHub 应用(推荐用于第三方提供商)
为了在使用 Google Cloud 的 Agent Platform 或 Amazon Bedrock 等第三方提供商时获得最佳控制和安全性,我们建议创建您自己的 GitHub 应用:Claude API 的替代方案或如果您不想设置自己的 Github 应用:使用官方 Anthropic 应用:
- 转到 https://github.com/settings/apps/new
- 填写基本信息:
- GitHub App 名称:选择唯一的名称(例如,“YourOrg Claude Assistant”)
- 主页 URL:您的组织网站或仓库 URL
- 配置应用设置:
- Webhooks:取消选中”Active”(此集成不需要)
- 设置所需的权限:
- 仓库权限:
- Contents:读写
- Issues:读写
- Pull requests:读写
- 仓库权限:
- 点击”Create GitHub App”
- 创建后,点击”Generate a private key”并保存下载的
.pem文件 - 从应用设置页面记下您的应用 ID
- 将应用安装到您的仓库:
- 从您的应用设置页面,点击左侧边栏中的”Install App”
- 选择您的账户或组织
- 选择”Only select repositories”并选择特定仓库
- 点击”Install”
- 将私钥添加为仓库密钥:
- 转到您的仓库的 Settings → Secrets and variables → Actions
- 创建一个名为
APP_PRIVATE_KEY的新密钥,内容为.pem文件的内容
- 将应用 ID 添加为密钥:
- 创建一个名为
APP_ID的新密钥,值为您的 GitHub 应用的 ID
此应用将与 actions/create-github-app-token action 一起使用,以在您的工作流中生成身份验证令牌。
- 从以下位置安装:https://github.com/apps/claude
- 无需额外的身份验证配置
2
配置云提供商身份验证
选择您的云提供商并设置安全身份验证:
Amazon Bedrock
Amazon Bedrock
配置 AWS 以允许 GitHub Actions 安全地进行身份验证,而无需存储凭证。
安全说明:使用特定于仓库的配置并仅授予最少所需的权限。所需设置:
-
启用 Amazon Bedrock:
- 请求在 Amazon Bedrock 中访问 Claude 模型
- 对于跨区域模型,请在所有必需的区域中请求访问
-
设置 GitHub OIDC 身份提供商:
- 提供商 URL:
https://token.actions.githubusercontent.com - 受众:
sts.amazonaws.com
- 提供商 URL:
-
为 GitHub Actions 创建 IAM 角色:
- 受信任的实体类型:Web 身份
- 身份提供商:
token.actions.githubusercontent.com - 权限:
AmazonBedrockFullAccess策略 - 为您的特定仓库配置信任策略
- AWS_ROLE_TO_ASSUME:您创建的 IAM 角色的 ARN
Google Cloud 的 Agent Platform
Google Cloud 的 Agent Platform
配置 Google Cloud 以允许 GitHub Actions 安全地进行身份验证,而无需存储凭证。
安全说明:使用特定于仓库的配置并仅授予最少所需的权限。所需设置:
-
在您的 Google Cloud 项目中启用 API:
- IAM Credentials API
- Security Token Service (STS) API
- Google Cloud 的 Agent Platform API
-
创建工作负载身份联合资源:
- 创建工作负载身份池
- 添加 GitHub OIDC 提供商,具有:
- 发行者:
https://token.actions.githubusercontent.com - 仓库和所有者的属性映射
- 安全建议:使用特定于仓库的属性条件
- 发行者:
-
创建服务账户:
- 仅授予
Vertex AI User角色 - 安全建议:为每个仓库创建专用服务账户
- 仅授予
-
配置 IAM 绑定:
- 允许工作负载身份池模拟服务账户
- 安全建议:使用特定于仓库的主体集
- GCP_WORKLOAD_IDENTITY_PROVIDER:完整的提供商资源名称
- GCP_SERVICE_ACCOUNT:服务账户电子邮件地址
3
添加所需的密钥
将以下密钥添加到您的仓库(Settings → Secrets and variables → Actions):
对于 Claude API(直接):
-
对于 API 身份验证:
ANTHROPIC_API_KEY:您的 Claude API 密钥,来自 console.anthropic.com
-
对于 GitHub 应用(如果使用您自己的应用):
APP_ID:您的 GitHub 应用的 IDAPP_PRIVATE_KEY:私钥 (.pem) 内容
对于 Google Cloud 的 Agent Platform
-
对于 GCP 身份验证:
GCP_WORKLOAD_IDENTITY_PROVIDERGCP_SERVICE_ACCOUNT
-
对于 GitHub 应用(如果使用您自己的应用):
APP_ID:您的 GitHub 应用的 IDAPP_PRIVATE_KEY:私钥 (.pem) 内容
对于 Amazon Bedrock
-
对于 AWS 身份验证:
AWS_ROLE_TO_ASSUME
-
对于 GitHub 应用(如果使用您自己的应用):
APP_ID:您的 GitHub 应用的 IDAPP_PRIVATE_KEY:私钥 (.pem) 内容
4
创建工作流文件
创建与您的云提供商集成的 GitHub Actions 工作流文件。下面的示例显示了 Amazon Bedrock 和 Google Cloud 的 Agent Platform 的完整配置:
Amazon Bedrock 工作流
Amazon Bedrock 工作流
前置条件:
- 启用了 Amazon Bedrock 访问权限,具有 Claude 模型权限
- GitHub 在 AWS 中配置为 OIDC 身份提供商
- 具有 Amazon Bedrock 权限的 IAM 角色,信任 GitHub Actions
Google Cloud 的 Agent Platform 工作流
Google Cloud 的 Agent Platform 工作流
前置条件:
- 在您的 GCP 项目中启用了 Google Cloud 的 Agent Platform API
- 为 GitHub 配置了工作负载身份联合
- 具有 Google Cloud 的 Agent Platform 权限的服务账户
故障排除
Claude 不响应 @claude 命令
验证 GitHub 应用是否正确安装,检查工作流是否已启用,确保 API 密钥在仓库密钥中设置,并确认评论包含@claude(不是 /claude)。
CI 不在 Claude 的提交上运行
确保您使用的是 GitHub 应用或自定义应用(不是 Actions 用户),检查工作流触发器是否包含必要的事件,并验证应用权限是否包括 CI 触发器。身份验证错误
确认 API 密钥有效且具有足够的权限。对于 Amazon Bedrock 或 Google Cloud 的 Agent Platform,检查凭证配置并确保密钥在工作流中正确命名。高级配置
Action 参数
Claude Code Action v1 使用简化的配置:
*提示是可选的 - 当对 issue/PR 评论省略时,Claude 响应触发短语
**对于直接 Claude API 是必需的,对于 Amazon Bedrock 或 Google Cloud 的 Agent Platform 不是必需的
传递 CLI 参数
claude_args 参数接受任何 Claude Code CLI 参数:
--max-turns:最大对话轮数(默认:10)--model:要使用的模型(例如,claude-sonnet-5)--mcp-config:MCP 配置的路径--allowedTools:允许的工具的逗号分隔列表。--allowed-tools别名也可以使用。--debug:启用调试输出
替代集成方法
虽然/install-github-app 命令是推荐的方法,但您也可以:
- 自定义 GitHub 应用:对于需要品牌用户名或自定义身份验证流的组织。创建您自己的 GitHub 应用,具有所需的权限(contents、issues、pull requests),并使用 actions/create-github-app-token action 在您的工作流中生成令牌。
- 手动 GitHub Actions:直接工作流配置以获得最大灵活性
- MCP 配置:Model Context Protocol 服务器的动态加载
自定义 Claude 的行为
您可以通过两种方式配置 Claude 的行为:- CLAUDE.md:在您的仓库根目录的
CLAUDE.md文件中定义编码标准、审查标准和项目特定规则。Claude 在创建 PR 和响应请求时将遵循这些指南。查看我们的 Memory 文档了解更多详情。 - 自定义提示:在工作流文件中使用
prompt参数提供工作流特定的说明。这允许您为不同的工作流或任务自定义 Claude 的行为。