@claude em qualquer PR ou issue, Claude pode analisar seu código, criar pull requests, implementar recursos e corrigir bugs - tudo enquanto segue os padrões do seu projeto.
Claude Code GitHub Actions é construído sobre o Claude Code
SDK, que permite integração programática do
Claude Code em suas aplicações. Você pode usar o SDK para construir fluxos de trabalho de automação personalizados além do GitHub Actions.
Claude Opus 4.5 agora está disponível. Claude Code GitHub Actions usa Sonnet por padrão. Para usar Opus 4.5, configure o parâmetro model para usar
claude-opus-4-5-20251101.Por que usar Claude Code GitHub Actions?
- Criação instantânea de PR: Descreva o que você precisa, e Claude cria um PR completo com todas as alterações necessárias
- Implementação de código automatizada: Transforme issues em código funcional com um único comando
- Segue seus padrões: Claude respeita suas diretrizes
CLAUDE.mde padrões de código existentes - Configuração simples: Comece em minutos com nosso instalador e chave de API
- Seguro por padrão: Seu código permanece nos runners do Github
O que Claude pode fazer?
Claude Code fornece uma poderosa GitHub Action que transforma como você trabalha com código:Claude Code Action
Esta GitHub Action permite que você execute Claude Code dentro de seus fluxos de trabalho do GitHub Actions. Você pode usar isso para construir qualquer fluxo de trabalho personalizado sobre Claude Code. Ver repositório →Configuração
Configuração rápida
A maneira mais fácil de configurar esta ação é através do Claude Code no terminal. Basta abrir claude e executar/install-github-app.
Este comando o guiará através da configuração do aplicativo GitHub e dos segredos necessários.
- Você deve ser um administrador do repositório para instalar o aplicativo GitHub e adicionar segredos
- O aplicativo GitHub solicitará permissões de leitura e escrita para Contents, Issues e Pull requests
- Este método de início rápido está disponível apenas para usuários diretos da Claude API. Se você está usando AWS Bedrock ou Google Vertex AI, consulte a seção Usando com AWS Bedrock & Google Vertex AI.
Configuração manual
Se o comando/install-github-app falhar ou você preferir configuração manual, siga estas instruções de configuração manual:
-
Instale o aplicativo Claude GitHub em seu repositório: https://github.com/apps/claude
O aplicativo Claude GitHub requer as seguintes permissões de repositório:
- Contents: Leitura e escrita (para modificar arquivos do repositório)
- Issues: Leitura e escrita (para responder a issues)
- Pull requests: Leitura e escrita (para criar PRs e fazer push de alterações)
- Adicione ANTHROPIC_API_KEY aos seus segredos do repositório (Aprenda como usar segredos no GitHub Actions)
-
Copie o arquivo de fluxo de trabalho de examples/claude.yml para a pasta
.github/workflows/do seu repositório
Atualizando da Beta
Se você está usando a versão beta do Claude Code GitHub Actions, recomendamos que você atualize seus fluxos de trabalho para usar a versão GA. A nova versão simplifica a configuração enquanto adiciona recursos poderosos como detecção automática de modo.Mudanças essenciais
Todos os usuários beta devem fazer essas alterações em seus arquivos de fluxo de trabalho para fazer upgrade:- Atualize a versão da ação: Mude
@betapara@v1 - Remova configuração de modo: Delete
mode: "tag"oumode: "agent"(agora detectado automaticamente) - Atualize entradas de prompt: Substitua
direct_promptporprompt - Mova opções de CLI: Converta
max_turns,model,custom_instructions, etc. paraclaude_args
Referência de Mudanças Significativas
| Entrada Beta Antiga | Nova Entrada v1.0 |
|---|---|
mode | (Removido - detectado automaticamente) |
direct_prompt | prompt |
override_prompt | prompt com variáveis do GitHub |
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 formato JSON |
Exemplo Antes e Depois
Versão beta:Exemplos de casos de uso
Claude Code GitHub Actions pode ajudá-lo com uma variedade de tarefas. O diretório de exemplos contém fluxos de trabalho prontos para uso em diferentes cenários.Fluxo de trabalho básico
Usando comandos de barra
Automação personalizada com prompts
Casos de uso comuns
Em comentários de issue ou PR:Melhores práticas
Configuração CLAUDE.md
Crie um arquivoCLAUDE.md na raiz do seu repositório para definir diretrizes de estilo de código, critérios de revisão, regras específicas do projeto e padrões preferidos. Este arquivo guia a compreensão de Claude sobre os padrões do seu projeto.
Considerações de segurança
Para orientação abrangente de segurança incluindo permissões, autenticação e melhores práticas, consulte a documentação de segurança do Claude Code Action. Sempre use GitHub Secrets para chaves de API:- Adicione sua chave de API como um segredo do repositório nomeado
ANTHROPIC_API_KEY - Referencie-a em fluxos de trabalho:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - Limite as permissões de ação apenas ao necessário
- Revise as sugestões de Claude antes de fazer merge
${{ secrets.ANTHROPIC_API_KEY }}) em vez de codificar chaves de API diretamente em seus arquivos de fluxo de trabalho.
Otimizando desempenho
Use modelos de issue para fornecer contexto, mantenha seuCLAUDE.md conciso e focado, e configure timeouts apropriados para seus fluxos de trabalho.
Custos de CI
Ao usar Claude Code GitHub Actions, esteja ciente dos custos associados: Custos do GitHub Actions:- Claude Code é executado em runners hospedados pelo GitHub, que consomem seus minutos do GitHub Actions
- Consulte a documentação de faturamento do GitHub para preços detalhados e limites de minutos
- Cada interação com Claude consome tokens de API com base no comprimento de prompts e respostas
- O uso de tokens varia pela complexidade da tarefa e tamanho da base de código
- Consulte a página de preços do Claude para taxas de token atuais
- Use comandos específicos
@claudepara reduzir chamadas de API desnecessárias - Configure
--max-turnsapropriado emclaude_argspara evitar iterações excessivas - Defina timeouts no nível do fluxo de trabalho para evitar jobs descontrolados
- Considere usar controles de concorrência do GitHub para limitar execuções paralelas
Exemplos de configuração
A Claude Code Action v1 simplifica a configuração com parâmetros unificados:- Interface de prompt unificada - Use
promptpara todas as instruções - Comandos de barra - Prompts pré-construídos como
/reviewou/fix - Passagem de CLI - Qualquer argumento de CLI do Claude Code via
claude_args - Gatilhos flexíveis - Funciona com qualquer evento do GitHub
Usando com AWS Bedrock & Google Vertex AI
Para ambientes empresariais, você pode usar Claude Code GitHub Actions com sua própria infraestrutura de nuvem. Esta abordagem oferece controle sobre residência de dados e faturamento enquanto mantém a mesma funcionalidade.Pré-requisitos
Antes de configurar Claude Code GitHub Actions com provedores de nuvem, você precisa:Para Google Cloud Vertex AI:
- Um Projeto Google Cloud com Vertex AI ativado
- Workload Identity Federation configurado para GitHub Actions
- Uma conta de serviço com as permissões necessárias
- Um GitHub App (recomendado) ou use o GITHUB_TOKEN padrão
Para AWS Bedrock:
- Uma conta AWS com Amazon Bedrock ativado
- GitHub OIDC Identity Provider configurado na AWS
- Uma função IAM com permissões do Bedrock
- Um GitHub App (recomendado) ou use o GITHUB_TOKEN padrão
1
Crie um GitHub App personalizado (Recomendado para Provedores 3P)
Para melhor controle e segurança ao usar provedores 3P como Vertex AI ou Bedrock, recomendamos criar seu próprio GitHub App:Alternativa para Claude API ou se você não quiser configurar seu próprio Github app: Use o app oficial da Anthropic:
- Vá para https://github.com/settings/apps/new
- Preencha as informações básicas:
- Nome do GitHub App: Escolha um nome único (por exemplo, “YourOrg Claude Assistant”)
- URL da Homepage: Site da sua organização ou URL do repositório
- Configure as configurações do app:
- Webhooks: Desmarque “Active” (não necessário para esta integração)
- Defina as permissões necessárias:
- Permissões do Repositório:
- Contents: Leitura e Escrita
- Issues: Leitura e Escrita
- Pull requests: Leitura e Escrita
- Permissões do Repositório:
- Clique em “Create GitHub App”
- Após a criação, clique em “Generate a private key” e salve o arquivo
.pembaixado - Anote seu App ID na página de configurações do app
- Instale o app em seu repositório:
- Na página de configurações do seu app, clique em “Install App” na barra lateral esquerda
- Selecione sua conta ou organização
- Escolha “Only select repositories” e selecione o repositório específico
- Clique em “Install”
- Adicione a chave privada como um segredo ao seu repositório:
- Vá para Settings → Secrets and variables → Actions do seu repositório
- Crie um novo segredo nomeado
APP_PRIVATE_KEYcom o conteúdo do arquivo.pem
- Adicione o App ID como um segredo:
- Crie um novo segredo nomeado
APP_IDcom o ID do seu GitHub App
Este app será usado com a ação actions/create-github-app-token para gerar tokens de autenticação em seus fluxos de trabalho.
- Instale de: https://github.com/apps/claude
- Nenhuma configuração adicional necessária para autenticação
2
Configure autenticação do provedor de nuvem
Escolha seu provedor de nuvem e configure autenticação segura:
AWS Bedrock
AWS Bedrock
Configure AWS para permitir que GitHub Actions se autentique com segurança sem armazenar credenciais.
Nota de Segurança: Use configurações específicas do repositório e conceda apenas as permissões mínimas necessárias.Configuração Necessária:
-
Ative Amazon Bedrock:
- Solicite acesso aos modelos Claude no Amazon Bedrock
- Para modelos entre regiões, solicite acesso em todas as regiões necessárias
-
Configure GitHub OIDC Identity Provider:
- URL do Provedor:
https://token.actions.githubusercontent.com - Audience:
sts.amazonaws.com
- URL do Provedor:
-
Crie Função IAM para GitHub Actions:
- Tipo de entidade confiável: Web identity
- Provedor de identidade:
token.actions.githubusercontent.com - Permissões: política
AmazonBedrockFullAccess - Configure política de confiança para seu repositório específico
- AWS_ROLE_TO_ASSUME: O ARN da função IAM que você criou
Google Vertex AI
Google Vertex AI
Configure Google Cloud para permitir que GitHub Actions se autentique com segurança sem armazenar credenciais.
Nota de Segurança: Use configurações específicas do repositório e conceda apenas as permissões mínimas necessárias.Configuração Necessária:
-
Ative APIs em seu projeto Google Cloud:
- IAM Credentials API
- Security Token Service (STS) API
- Vertex AI API
-
Crie recursos de Workload Identity Federation:
- Crie um Workload Identity Pool
- Adicione um provedor OIDC do GitHub com:
- Issuer:
https://token.actions.githubusercontent.com - Mapeamentos de atributos para repositório e proprietário
- Recomendação de segurança: Use condições de atributo específicas do repositório
- Issuer:
-
Crie uma Conta de Serviço:
- Conceda apenas a função
Vertex AI User - Recomendação de segurança: Crie uma conta de serviço dedicada por repositório
- Conceda apenas a função
-
Configure vinculações IAM:
- Permita que o Workload Identity Pool represente a conta de serviço
- Recomendação de segurança: Use conjuntos de principais específicos do repositório
- GCP_WORKLOAD_IDENTITY_PROVIDER: O nome completo do recurso do provedor
- GCP_SERVICE_ACCOUNT: O endereço de email da conta de serviço
3
Adicione Segredos Necessários
Adicione os seguintes segredos ao seu repositório (Settings → Secrets and variables → Actions):
Para Claude API (Direto):
-
Para Autenticação de API:
ANTHROPIC_API_KEY: Sua chave de API Claude de console.anthropic.com
-
Para GitHub App (se usar seu próprio app):
APP_ID: O ID do seu GitHub AppAPP_PRIVATE_KEY: O conteúdo da chave privada (.pem)
Para Google Cloud Vertex AI
-
Para Autenticação GCP:
GCP_WORKLOAD_IDENTITY_PROVIDERGCP_SERVICE_ACCOUNT
-
Para GitHub App (se usar seu próprio app):
APP_ID: O ID do seu GitHub AppAPP_PRIVATE_KEY: O conteúdo da chave privada (.pem)
Para AWS Bedrock
-
Para Autenticação AWS:
AWS_ROLE_TO_ASSUME
-
Para GitHub App (se usar seu próprio app):
APP_ID: O ID do seu GitHub AppAPP_PRIVATE_KEY: O conteúdo da chave privada (.pem)
4
Crie arquivos de fluxo de trabalho
Crie arquivos de fluxo de trabalho do GitHub Actions que se integrem com seu provedor de nuvem. Os exemplos abaixo mostram configurações completas para AWS Bedrock e Google Vertex AI:
Fluxo de trabalho AWS Bedrock
Fluxo de trabalho AWS Bedrock
Pré-requisitos:
- Acesso AWS Bedrock ativado com permissões de modelo Claude
- GitHub configurado como provedor de identidade OIDC na AWS
- Função IAM com permissões do Bedrock que confia no GitHub Actions
| Nome do Segredo | Descrição |
|---|---|
AWS_ROLE_TO_ASSUME | ARN da função IAM para acesso ao Bedrock |
APP_ID | Seu ID de GitHub App (das configurações do app) |
APP_PRIVATE_KEY | A chave privada que você gerou para seu GitHub App |
Fluxo de trabalho Google Vertex AI
Fluxo de trabalho Google Vertex AI
Pré-requisitos:
- Vertex AI API ativada em seu projeto GCP
- Workload Identity Federation configurada para GitHub
- Conta de serviço com permissões do Vertex AI
| Nome do Segredo | Descrição |
|---|---|
GCP_WORKLOAD_IDENTITY_PROVIDER | Nome do recurso do provedor de identidade de workload |
GCP_SERVICE_ACCOUNT | Email da conta de serviço com acesso ao Vertex AI |
APP_ID | Seu ID de GitHub App (das configurações do app) |
APP_PRIVATE_KEY | A chave privada que você gerou para seu GitHub App |
Solução de problemas
Claude não responde a comandos @claude
Verifique se o GitHub App está instalado corretamente, verifique se os fluxos de trabalho estão ativados, certifique-se de que a chave de API está definida nos segredos do repositório e confirme que o comentário contém@claude (não /claude).
CI não está sendo executado nos commits de Claude
Certifique-se de que você está usando o GitHub App ou app personalizado (não usuário Actions), verifique se os gatilhos de fluxo de trabalho incluem os eventos necessários e verifique se as permissões do app incluem gatilhos de CI.Erros de autenticação
Confirme que a chave de API é válida e tem permissões suficientes. Para Bedrock/Vertex, verifique a configuração de credenciais e certifique-se de que os segredos estão nomeados corretamente nos fluxos de trabalho.Configuração avançada
Parâmetros de ação
A Claude Code Action v1 usa uma configuração simplificada:| Parâmetro | Descrição | Necessário |
|---|---|---|
prompt | Instruções para Claude (texto ou comando de barra) | Não* |
claude_args | Argumentos de CLI passados para Claude Code | Não |
anthropic_api_key | Chave de API Claude | Sim** |
github_token | Token do GitHub para acesso à API | Não |
trigger_phrase | Frase de gatilho personalizada (padrão: “@claude”) | Não |
use_bedrock | Use AWS Bedrock em vez da Claude API | Não |
use_vertex | Use Google Vertex AI em vez da Claude API | Não |
**Necessário para Claude API direto, não para Bedrock/Vertex
Passe argumentos de CLI
O parâmetroclaude_args aceita qualquer argumento de CLI do Claude Code:
--max-turns: Máximo de turnos de conversa (padrão: 10)--model: Modelo a usar (por exemplo,claude-sonnet-4-5-20250929)--mcp-config: Caminho para configuração MCP--allowed-tools: Lista separada por vírgula de ferramentas permitidas--debug: Ativar saída de debug
Métodos de integração alternativos
Enquanto o comando/install-github-app é a abordagem recomendada, você também pode:
- GitHub App Personalizado: Para organizações que precisam de nomes de usuário personalizados ou fluxos de autenticação personalizados. Crie seu próprio GitHub App com permissões necessárias (contents, issues, pull requests) e use a ação actions/create-github-app-token para gerar tokens em seus fluxos de trabalho.
- GitHub Actions Manual: Configuração direta de fluxo de trabalho para máxima flexibilidade
- Configuração MCP: Carregamento dinâmico de servidores Model Context Protocol
Personalizando o comportamento de Claude
Você pode configurar o comportamento de Claude de duas maneiras:- CLAUDE.md: Defina padrões de codificação, critérios de revisão e regras específicas do projeto em um arquivo
CLAUDE.mdna raiz do seu repositório. Claude seguirá essas diretrizes ao criar PRs e responder a solicitações. Confira nossa documentação de Memória para mais detalhes. - Prompts personalizados: Use o parâmetro
promptno arquivo de fluxo de trabalho para fornecer instruções específicas do fluxo de trabalho. Isso permite que você personalize o comportamento de Claude para diferentes fluxos de trabalho ou tarefas.