Learn about integrating Claude Code into your development workflow with Claude Code GitHub Actions
了解如何使用 Claude Code GitHub Actions 将 Claude Code 集成到您的开发工作流程中
Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow.
With a simple @claude mention in any PR or issue, Claude can analyze your code, create pull requests, implement features, and fix bugs - all while following your project's standards.
Claude Code GitHub Actions 为您的 GitHub 工作流程带来了 AI 驱动的自动化。
在任何 PR 或issue中简单提及 @claude ，Claude 就能分析您的代码、创建拉取请求、实现功能并修复错误------所有操作都遵循你的项目标准。
Claude Code GitHub Actions is built on top of the Claude Code SDK, which enables programmatic integration of Claude Code into your applications.
You can use the SDK to build custom automation workflows beyond GitHub Actions.
Claude Code GitHub Actions 基于 Claude Code SDK 构建，该 SDK 支持将 Claude Code 程序化集成到您的应用程序中。
您可以使用 SDK 构建超出 GitHub Actions 的自定义自动化工作流程。
Claude Code GitHub Actions default to Sonnet. To use Opus 4.5, configure the model parameter to use claude-opus-4-5-20251101.
Claude Code GitHub Actions 默认使用 Sonnet。要使用 Opus 4.5，请配置模型参数以使用 claude-opus-4-5-20251101 。
一，Why use Claude Code GitHub Actions?
为什么使用 Claude Code GitHub Actions？
Instant PR creation: Describe what you need, and Claude creates a complete PR with all necessary changes
即时创建 PR：描述你的需求，Claude 会创建一个包含所有必要更改的完整 PR
Automated code implementation: Turn issues into working code with a single command
自动化代码实现：通过一个命令将issues转化为可运行的代码
Follows your standards: Claude respects your CLAUDE.md guidelines and existing code patterns
遵循你的标准：Claude 尊重你的 CLAUDE.md 指南和现有代码模式
Simple setup: Get started in minutes with our installer and API key
简单设置：通过安装程序和 API 密钥，几分钟内即可开始使用
Secure by default: Your code stays on Github's runners
默认安全：您的代码保留在 Github 的运行器上
二，What can Claude do? Claude 能做什么？
Claude Code provides a powerful GitHub Action that transforms how you work with code:
Claude Code 提供了强大的 GitHub 操作，它改变了您处理代码的方式：
2.1 Claude Code Action
This GitHub Action allows you to run Claude Code within your GitHub Actions workflows. You can use this to build any custom workflow on top of Claude Code.
这个GitHub Action 允许你在 GitHub Actions 工作流中运行 Claude Code。你可以使用它来构建基于 Claude Code 的任何自定义工作流。
https://github.com/anthropics/claude-code-action
三，Setup 设置
3.1，Quick setup 快速设置
The easiest way to set up this action is through Claude Code in the terminal. Just open claude and run /install-github-app.
设置这个 Action 最简单的方法是通过终端中的 Claude Code。只需打开 claude 并运行 /install-github-app 。
This command will guide you through setting up the GitHub app and required secrets.
这个命令将指导你设置 GitHub app和所需密钥
You must be a repository admin to install the GitHub app and add secrets
你必须是代码仓库管理员才能安装 GitHub 应用并添加密钥
The GitHub app will request read & write permissions for Contents, Issues, and Pull requests
GitHub app将请求对 Contents、Issues 和 Pull requests 的读写权限
This quickstart method is only available for direct Claude API users. If you're using AWS Bedrock or Google Vertex AI, please see the Using with AWS Bedrock & Google Vertex AI section.
这种快速入门方法仅适用于直接使用 Claude API 的用户。如果你使用的是 AWS Bedrock 或 Google Vertex AI，请参阅后面的"与 AWS Bedrock & Google Vertex AI 一起使用"部分。
3.2，Manual setup 手动设置
If the /install-github-app command fails or you prefer manual setup, please follow these manual setup instructions:
如果 /install-github-app 命令失败或你更喜欢手动设置，请按照这些手动设置说明进行操作：
3.2.1 Install the Claude GitHub app to your repository: https://github.com/apps/claude
将 Claude GitHub 应用安装到您的代码仓库：https://github.com/apps/claude
The Claude GitHub app requires the following repository permissions:
Claude GitHub app需要以下代码仓库权限：
Contents: Read & write (to modify repository files)
内容：读取和写入（以修改代码仓库文件）
Issues: Read & write (to respond to issues)
问题：读取和写入（以回复问题）
Pull requests: Read & write (to create PRs and push changes)
拉取请求：读取与写入（用于创建 PR 和推送更改）
3.2.2 Add ANTHROPIC_API_KEY to your repository secrets (Learn how to use secrets in GitHub Actions)
将 ANTHROPIC_API_KEY 添加到您的仓库密钥中（学习如何在 GitHub Actions 中使用密钥）
https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
3.2.3 Copy the workflow file from examples/claude.yml into your repository's .github/workflows/
将 workflow 文件从 examples/claude.yml 复制到您的仓库的 .github/workflows/
After completing either the quickstart or manual setup, test the action by tagging @claude in an issue or PR comment.
完成快速入门或手动设置后，通过在issue或 PR 评论中使用 @claude 进行测试。
四，Upgrading from Beta 从 Beta 版本升级
Claude Code GitHub Actions v1.0 introduces breaking changes that require updating your workflow files in order to upgrade to v1.0 from the beta version.
Claude Code GitHub Actions v1.0 引入了破坏性变更，需要更新你的工作流文件才能从 Beta 版本升级到 v1.0。
If you're currently using the beta version of Claude Code GitHub Actions, we recommend that you update your workflows to use the GA version. The new version simplifies configuration while adding powerful new features like automatic mode detection.
如果你目前正在使用 Claude Code GitHub Actions 的 Beta 版本，我们建议你更新你的工作流以使用正式版本。新版本简化了配置，同时添加了自动模式检测等强大的新功能。
4.1 Essential changes 重要变更
All beta users must make these changes to their workflow files in order to upgrade:
所有beta版本用户必须对其工作流文件进行这些更改以进行升级：
4.1.1 Update the action version: Change @beta to @v1
更新操作版本：将 @beta 更改为 @v1
4.1.2 Remove mode configuration: Delete mode: "tag" or mode: "agent" (now auto-detected)
移除模式配置：删除 mode: "tag" 或 mode: "agent" （现在自动检测）
4.1.3 Update prompt inputs: Replace direct_prompt with prompt
更新提示输入：将 direct_prompt 替换为 prompt
4.1.4 Move CLI options: Convert max_turns, model, custom_instructions, etc. to claude_args
移动了 CLI 选项：将 max_turns 、 model 、 custom_instructions 等转换为 claude_args
4.2 Breaking Changes Reference 重大变更参考
原mode：(Removed - auto-detected)(已移除 - 自动检测)
原direct_prompt改为prompt
override_prompt-> prompt with GitHub variables
使用 GitHub 变量 prompt
custom_instructions->claude_args: --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 format
settings JSON 格式
4.3 Before and After Example 前后示例
Beta version: 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-5-20250929"
GA version (v1.0): 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: |
--system-prompt "Follow our coding standards"
--max-turns 10
--model claude-sonnet-4-5-20250929
The action now automatically detects whether to run in interactive mode (responds to @claude mentions) or automation mode (runs immediately with a prompt) based on your configuration.
该操作现在会根据您的配置自动检测是否以交互模式运行（响应 @claude 引用）或自动化模式运行（立即使用提示运行）。
五，Example use cases 示例
Claude Code GitHub Actions can help you with a variety of tasks. The examples directory contains ready-to-use workflows for different scenarios.
Claude Code GitHub Actions 可以帮助您处理各种任务。示例目录包含适用于不同场景的现成工作流。
5.1 Basic workflow 基本工作流
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 }}
Responds to @claude mentions in comments
5.2 Using skills 使用技能进行代码评审
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 }}
prompt: "/review"
claude_args: "--max-turns 5"
5.3 Custom automation with prompts
使用提示自定义自动化
如根据昨天的提交和打开的issue生成一份摘要
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 claude-opus-4-5-20251101"
5.4 Common use cases 常见用例
In issue or PR comments:
在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
修复用户仪表板组件中的TypeError 错误
Claude will automatically analyze the context and respond appropriately.
Claude 将自动分析上下文并作出适当回应。
六，Best practices 最佳实践
6.1 CLAUDE.md configuration CLAUDE.md 配置
Create a CLAUDE.md file in your repository root to define code style guidelines, review criteria, project-specific rules, and preferred patterns. This file guides Claude's understanding of your project standards.
在你的仓库根目录中创建一个 CLAUDE.md 文件来定义代码风格指南、审查标准、项目特定规则和首选模式。该文件指导 Claude 对你的项目标准的理解。
6.2 Security considerations 安全注意事项
Never commit API keys directly to your repository.
切勿将 API 密钥直接提交到你的仓库中。
Always use GitHub Secrets for API keys:
始终使用 GitHub Secrets 存储 API 密钥：
Add your API key as a repository secret named ANTHROPIC_API_KEY
将您的 API 密钥添加为名为 ANTHROPIC_API_KEY 的仓库密钥：
Reference it in workflows: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
在作业流程中引用它： anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
Limit action permissions to only what's necessary
限制操作权限仅限于必要范围
Review Claude's suggestions before merging
合并前审查 Claude 的建议
Always use GitHub Secrets (for example, ${{ secrets.ANTHROPIC_API_KEY }}) rather than hardcoding API keys directly in your workflow files.
始终使用 GitHub 密钥（例如， ${{ secrets.ANTHROPIC_API_KEY }} ），而不是直接在流程文件中硬编码 API 密钥。
6.3 Optimizing performance 优化性能
Use issue templates to provide context, keep your CLAUDE.md concise and focused, and configure appropriate timeouts for your workflows.
使用issue模板提供上下文，保持你的 CLAUDE.md 简洁集中，并为你的工作流配置适当的超时。
6.4 CI costs CI 成本
When using Claude Code GitHub Actions, be aware of the associated costs:
在使用 Claude Code GitHub Actions 时，请注意相关成本：
6.4.1 GitHub Actions costs: GitHub Actions 成本：
Claude Code runs on GitHub-hosted runners, which consume your GitHub Actions minutes
Claude Code 在 GitHub 托管的运行器上运行，这些运行器会消耗你的 GitHub Actions 分钟数
6.4.2 API costs: API 成本：
Each Claude interaction consumes API tokens based on the length of prompts and responses
每次 Claude 交互会根据提示词和响应的长度消耗 API 令牌
Token usage varies by task complexity and codebase size
任务复杂度和代码库大小不同，Token 使用量也不同
6.4.3 Cost optimization tips: 成本优化建议：
Use specific @claude commands to reduce unnecessary API calls
使用特定的 @claude 命令来减少不必要的 API 调用
Configure appropriate --max-turns in claude_args to prevent excessive iterations
在 claude_args 中配置适当的 --max-turns 以防止过度迭代
Set workflow-level timeouts to avoid runaway jobs
设置工作流程级别的超时以避免失控作业
Consider using GitHub's concurrency controls to limit parallel runs
考虑使用 GitHub 的并发控制来限制并行运行
七， Configuration examples 配置示例
The Claude Code Action v1 simplifies configuration with unified parameters:
Claude Code Action v1 通过统一的参数简化了配置：
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "Your instructions here" # Optional
claude_args: "--max-turns 5" # Optional CLI arguments
Key features: 主要功能：
Unified prompt interface - Use prompt for all instructions
统一提示接口 - 对所有指令使用 prompt
Commands - Prebuilt prompts like /review or /fix
命令 - 预构建的提示如 /review 或 /fix
CLI passthrough - Any Claude Code CLI argument via claude_args
CLI 透传 - 通过 claude_args 传递任何 Claude Code CLI 参数
Flexible triggers - Works with any GitHub event
灵活触发器 - 支持任何 GitHub 事件
示例:https://github.com/anthropics/claude-code-action/tree/main/examples
When responding to issue or PR comments, Claude automatically responds to @claude mentions. For other events, use the prompt parameter to provide instructions.
在回复issue或 PR 评论时，Claude 会自动回复@claude 提及的内容。对于其他事件，使用 prompt 参数提供指示
八，Troubleshooting 故障排除
8.1 Claude not responding to @claude commands
Claude 没有响应 @claude 命令
Verify the GitHub App is installed correctly, check that workflows are enabled, ensure API key is set in repository secrets, and confirm the comment contains @claude (not /claude).
验证 GitHub app是否正确安装，检查工作流是否已启用，确保 API 密钥已设置在仓库密钥中，并确认评论包含 @claude （而不是 /claude ）。
8.2 CI not running on Claude's commits
Claude 提交时没有运行 CI
Ensure you're using the GitHub App or custom app (not Actions user), check workflow triggers include the necessary events, and verify app permissions include CI triggers.
确保你正在使用 GitHub app或自定义应用（而不是 Actions 用户），检查工作流触发器是否包含必要的事件，并验证应用权限是否包括 CI 触发器。
8.3 Authentication errors 认证错误
Confirm API key is valid and has sufficient permissions. For Bedrock/Vertex, check credentials configuration and ensure secrets are named correctly in workflows.
确认 API 密钥有效且具有足够的权限。对于 Bedrock/Vertex，检查凭证配置并确保工作流中的密钥名称正确。
九，Advanced configuration 高级配置
9.1 Action parameters 操作参数
The Claude Code Action v1 uses a simplified configuration:
Claude Code Action v1 使用简化的配置：
prompt参数: Instructions for Claude (text or skill like /review)
Claude 的说明（文本或技能，如 /review ）
claude_args:CLI arguments passed to Claude Code
传递给 Claude Code 的 CLI 参数
anthropic_api_key:Claude API key Claude API 密钥
github_token: GitHub token for API access
用于 API 访问的 GitHub 令牌
trigger_phrase:Custom trigger phrase (default: "@claude")
自定义触发短语（默认："@claude"）
use_bedrock:Use AWS Bedrock instead of Claude API
使用 AWS Bedrock 而不是 Claude API
use_vertex:Use Google Vertex AI instead of Claude API
使用 Google Vertex AI 而不是 Claude API
9.1.1 Pass CLI arguments 传递 CLI 参数
The claude_args parameter accepts any Claude Code CLI arguments:
claude_args 参数接受任何 Claude Code CLI 参数：
claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929 --mcp-config /path/to/config.json"
Common arguments: 常见参数：
--max-turns: Maximum conversation turns (default: 10)
--max-turns : 最大对话轮数（默认：10）
--model: Model to use (for example, claude-sonnet-4-5-20250929)
--model : 使用的模型（例如， claude-sonnet-4-5-20250929 ）
--mcp-config: Path to MCP configuration
--mcp-config : MCP 配置文件路径
--allowed-tools: Comma-separated list of allowed tools
--allowed-tools : 允许使用的工具列表，用逗号分隔
--debug: Enable debug output
--debug : 启用调试输出
9.2 Alternative integration methods
其他集成方法
While the /install-github-app command is the recommended approach, you can also:
虽然 /install-github-app 命令是推荐的方法，你也可以用下面的方法：
9.2.1 Custom GitHub App: For organizations needing branded usernames or custom authentication flows. Create your own GitHub App with required permissions (contents, issues, pull requests) and use the actions/create-github-app-token action to generate tokens in your workflows.
自定义 GitHub 应用：针对需要品牌化用户名或自定义认证流程的组织。创建具有所需权限（内容、问题、拉取请求）的 GitHub 应用，并使用 actions/create-github-app-token 操作在你的流程中生成令牌。
9.2.2 Manual GitHub Actions: Direct workflow configuration for maximum flexibility
手动 GitHub Actions：直接工作流程配置，实现最大灵活性
9.2.3 MCP Configuration: Dynamic loading of Model Context Protocol servers
MCP 配置：动态加载模型上下文协议服务器
9.3 Customizing Claude's behavior
自定义 Claude 的行为
You can configure Claude's behavior in two ways:
您可以通过两种方式配置 Claude 的行为：
9.3.1 CLAUDE.md: Define coding standards, review criteria, and project-specific rules in a CLAUDE.md file at the root of your repository. Claude will follow these guidelines when creating PRs and responding to requests.
CLAUDE.md：在仓库根目录中的 CLAUDE.md 文件中定义编码标准、审查标准和特定项目的规则。Claude 在创建 PR 和响应请求时会遵循这些指南。
9.3.2 Custom prompts: Use the prompt parameter in the workflow file to provide workflow-specific instructions. This allows you to customize Claude's behavior for different workflows or tasks.
自定义提示：在流程文件中使用 prompt 参数提供特定于流程的说明。这允许你针对不同的流程或任务自定义 Claude 的行为。
Claude will follow these guidelines when creating PRs and responding to requests.
Claude 在创建 PR 和回复请求时会遵循这些指南。
小结：
在仓库根目录中创建一个 CLAUDE.md 文件来定义代码风格指南
--max-turns 以防止过度迭代
可以实现issue的功能