Claude Code GitHub Actions traz automação alimentada por IA para o seu fluxo de trabalho do GitHub. Com uma simples menção @claude em qualquer PR ou issue, Claude pode analisar seu código, criar pull requests, implementar recursos e corrigir bugs - tudo seguindo 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.

​
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 mudanças necessárias
  • Implementação automatizada de código: Transforme issues em código funcional com um único comando
  • Segue seus padrões: Claude respeita suas diretrizes CLAUDE.md e 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 dos 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 action é através do Claude Code no terminal. Apenas abra claude e execute /install-github-app. Este comando irá guiá-lo através da configuração do app GitHub e segredos necessários.
  • Você deve ser um administrador do repositório para instalar o app GitHub e adicionar segredos
  • O app 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 API Claude. Se você está usando AWS Bedrock ou Google Vertex AI, por favor veja 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, por favor siga estas instruções de configuração manual:
  1. Instale o app Claude GitHub no seu repositório: https://github.com/apps/claude O app 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 enviar mudanças)
    Para mais detalhes sobre segurança e permissões, veja a documentação de segurança.
  2. Adicione ANTHROPIC_API_KEY aos segredos do seu repositório (Aprenda como usar segredos no GitHub Actions)
  3. Copie o arquivo de fluxo de trabalho de examples/claude.yml para o .github/workflows/ do seu repositório
Após completar a configuração rápida ou manual, teste a action marcando @claude em um comentário de issue ou PR!

​
Atualizando da versão Beta

Claude Code GitHub Actions v1.0 introduz mudanças que quebram compatibilidade que requerem atualização dos seus arquivos de fluxo de trabalho para atualizar para v1.0 da versão beta.
Se você está atualmente 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 novos recursos poderosos como detecção automática de modo.

​
Mudanças essenciais

Todos os usuários beta devem fazer essas mudanças nos seus arquivos de fluxo de trabalho para atualizar:
  1. Atualize a versão da action: Mude @beta para @v1
  2. Remova configuração de modo: Delete mode: "tag" ou mode: "agent" (agora auto-detectado)
  3. Atualize entradas de prompt: Substitua direct_prompt por prompt
  4. Mova opções CLI: Converta max_turns, model, custom_instructions, etc. para claude_args

​
Referência de Mudanças que Quebram Compatibilidade

Entrada Beta AntigaNova Entrada v1.0
mode(Removido - auto-detectado)
direct_promptprompt
override_promptprompt com variáveis GitHub
custom_instructionsclaude_args: --system-prompt
max_turnsclaude_args: --max-turns
modelclaude_args: --model
allowed_toolsclaude_args: --allowedTools
disallowed_toolsclaude_args: --disallowedTools
claude_envsettings formato JSON

​
Exemplo Antes e Depois

Versão beta: 
- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Revise este PR para problemas de segurança"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Siga nossos padrões de codificação"
    max_turns: "10"
    model: "claude-3-5-sonnet-20241022"
Versão GA (v1.0): 
- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Revise este PR para problemas de segurança"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --system-prompt "Siga nossos padrões de codificação"
      --max-turns 10
      --model claude-sonnet-4-5-20250929
A action agora detecta automaticamente se deve executar em modo interativo (responde a menções @claude) ou modo de automação (executa imediatamente com um prompt) baseado na sua configuração.

​
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 usar para diferentes cenários.

​
Fluxo de trabalho básico

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 }}
          # Responde a menções @claude em comentários

​
Usando comandos slash

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"

​
Automação personalizada com prompts

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: "Gere um resumo dos commits de ontem e issues abertas"
          claude_args: "--model claude-opus-4-1-20250805"

​
Casos de uso comuns

Em comentários de issue ou PR: 
@claude implemente este recurso baseado na descrição da issue
@claude como devo implementar autenticação de usuário para este endpoint?
@claude corrija o TypeError no componente de dashboard do usuário
Claude irá automaticamente analisar o contexto e responder apropriadamente.

​
Melhores práticas

​
Configuração CLAUDE.md

Crie um arquivo CLAUDE.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 o entendimento do Claude sobre os padrões do seu projeto.

​
Considerações de segurança

Nunca faça commit de chaves de API diretamente no seu repositório!
Para orientação abrangente de segurança incluindo permissões, autenticação e melhores práticas, veja 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 de repositório chamado ANTHROPIC_API_KEY
  • Referencie-a em fluxos de trabalho: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
  • Limite permissões da action apenas ao necessário
  • Revise as sugestões do Claude antes de fazer merge
Sempre use GitHub Secrets (ex., ${{ secrets.ANTHROPIC_API_KEY }}) ao invés de codificar chaves de API diretamente nos seus arquivos de fluxo de trabalho.

​
Otimizando performance

Use templates de issue para fornecer contexto, mantenha seu CLAUDE.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 executa em runners hospedados pelo GitHub, que consomem seus minutos do GitHub Actions
  • Veja documentação de cobrança do GitHub para preços detalhados e limites de minutos
Custos de API:
  • Cada interação do Claude consome tokens de API baseado no comprimento de prompts e respostas
  • Uso de tokens varia pela complexidade da tarefa e tamanho da base de código
  • Veja página de preços do Claude para taxas atuais de tokens
Dicas de otimização de custos:
  • Use comandos @claude específicos para reduzir chamadas desnecessárias de API
  • Configure --max-turns apropriado em claude_args para prevenir 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

O Claude Code Action v1 simplifica a configuração com parâmetros unificados: 
- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Suas instruções aqui" # Opcional
    claude_args: "--max-turns 5" # Argumentos CLI opcionais
Recursos principais:
  • Interface de prompt unificada - Use prompt para todas as instruções
  • Comandos slash - Prompts pré-construídos como /review ou /fix
  • Passagem CLI - Qualquer argumento CLI do Claude Code via claude_args
  • Triggers flexíveis - Funciona com qualquer evento do GitHub
Visite o diretório de exemplos para arquivos completos de fluxo de trabalho.
Ao responder a comentários de issue ou PR, Claude automaticamente responde a menções @claude. Para outros eventos, use o parâmetro prompt para fornecer instruções.

​
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 lhe dá controle sobre residência de dados e cobrança mantendo a mesma funcionalidade.

​
Pré-requisitos

Antes de configurar Claude Code GitHub Actions com provedores de nuvem, você precisa:

​
Para Google Cloud Vertex AI:

  1. Um Projeto Google Cloud com Vertex AI habilitado
  2. Workload Identity Federation configurado para GitHub Actions
  3. Uma conta de serviço com as permissões necessárias
  4. Um GitHub App (recomendado) ou use o GITHUB_TOKEN padrão

​
Para AWS Bedrock:

  1. Uma conta AWS com Amazon Bedrock habilitado
  2. GitHub OIDC Identity Provider configurado na AWS
  3. Uma função IAM com permissões Bedrock
  4. Um GitHub App (recomendado) ou use o GITHUB_TOKEN padrão
1

Criar 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:
  1. Vá para https://github.com/settings/apps/new
  2. Preencha as informações básicas:
    • Nome do GitHub App: Escolha um nome único (ex., “YourOrg Claude Assistant”)
    • URL da Homepage: Site da sua organização ou URL do repositório
  3. Configure as configurações do app:
    • Webhooks: Desmarque “Active” (não necessário para esta integração)
  4. Defina as permissões necessárias:
    • Permissões do repositório:
      • Contents: Leitura e Escrita
      • Issues: Leitura e Escrita
      • Pull requests: Leitura e Escrita
  5. Clique em “Create GitHub App”
  6. Após a criação, clique em “Generate a private key” e salve o arquivo .pem baixado
  7. Anote seu App ID da página de configurações do app
  8. Instale o app no seu repositório:
    • Da 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”
  9. Adicione a chave privada como um segredo ao seu repositório:
    • Vá para Configurações do seu repositório → Secrets and variables → Actions
    • Crie um novo segredo chamado APP_PRIVATE_KEY com o conteúdo do arquivo .pem
  10. Adicione o App ID como um segredo:
  • Crie um novo segredo chamado APP_ID com o ID do seu GitHub App
Este app será usado com a action actions/create-github-app-token para gerar tokens de autenticação nos seus fluxos de trabalho.
Alternativa para API Claude ou se você não quer configurar seu próprio app Github: Use o app oficial da Anthropic:
  1. Instale de: https://github.com/apps/claude
  2. Nenhuma configuração adicional necessária para autenticação
2

Configurar autenticação do provedor de nuvem

Escolha seu provedor de nuvem e configure autenticação segura:
Configure a AWS para permitir que GitHub Actions se autentique de forma segura 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:
  1. Habilite Amazon Bedrock:
    • Solicite acesso aos modelos Claude no Amazon Bedrock
    • Para modelos cross-region, solicite acesso em todas as regiões necessárias
  2. Configure GitHub OIDC Identity Provider:
    • URL do Provider: https://token.actions.githubusercontent.com
    • Audience: sts.amazonaws.com
  3. 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
Valores Necessários:Após a configuração, você precisará:
  • AWS_ROLE_TO_ASSUME: O ARN da função IAM que você criou
OIDC é mais seguro que usar chaves de acesso AWS estáticas porque as credenciais são temporárias e automaticamente rotacionadas.
Veja documentação da AWS para instruções detalhadas de configuração OIDC.
Configure Google Cloud para permitir que GitHub Actions se autentique de forma segura 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:
  1. Habilite APIs no seu projeto Google Cloud:
    • IAM Credentials API
    • Security Token Service (STS) API
    • Vertex AI API
  2. Crie recursos Workload Identity Federation:
    • Crie um Workload Identity Pool
    • Adicione um provedor GitHub OIDC 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
  3. 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
  4. Configure vinculações IAM:
    • Permita que o Workload Identity Pool personifique a conta de serviço
    • Recomendação de segurança: Use conjuntos principais específicos do repositório
Valores Necessários:Após a configuração, você precisará:
  • GCP_WORKLOAD_IDENTITY_PROVIDER: O nome completo do recurso do provedor
  • GCP_SERVICE_ACCOUNT: O endereço de email da conta de serviço
Workload Identity Federation elimina a necessidade de chaves de conta de serviço baixáveis, melhorando a segurança.
Para instruções detalhadas de configuração, consulte a documentação do Google Cloud Workload Identity Federation.
3

Adicionar Segredos Necessários

Adicione os seguintes segredos ao seu repositório (Settings → Secrets and variables → Actions):

​
Para API Claude (Direta):

  1. Para Autenticação de API:
  2. Para GitHub App (se usando seu próprio app):
    • APP_ID: ID do seu GitHub App
    • APP_PRIVATE_KEY: O conteúdo da chave privada (.pem)

​
Para Google Cloud Vertex AI

  1. Para Autenticação GCP:
    • GCP_WORKLOAD_IDENTITY_PROVIDER
    • GCP_SERVICE_ACCOUNT
  2. Para GitHub App (se usando seu próprio app):
    • APP_ID: ID do seu GitHub App
    • APP_PRIVATE_KEY: O conteúdo da chave privada (.pem)

​
Para AWS Bedrock

  1. Para Autenticação AWS:
    • AWS_ROLE_TO_ASSUME
  2. Para GitHub App (se usando seu próprio app):
    • APP_ID: ID do seu GitHub App
    • APP_PRIVATE_KEY: O conteúdo da chave privada (.pem)
4

Criar arquivos de fluxo de trabalho

Crie arquivos de fluxo de trabalho do GitHub Actions que se integram com seu provedor de nuvem. Os exemplos abaixo mostram configurações completas para AWS Bedrock e Google Vertex AI:
Pré-requisitos:
  • Acesso AWS Bedrock habilitado com permissões de modelo Claude
  • GitHub configurado como provedor de identidade OIDC na AWS
  • Função IAM com permissões Bedrock que confia no GitHub Actions
Segredos GitHub necessários:
Nome do SegredoDescrição
AWS_ROLE_TO_ASSUMEARN da função IAM para acesso Bedrock
APP_IDID do seu GitHub App (das configurações do app)
APP_PRIVATE_KEYA chave privada que você gerou para seu GitHub App
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-5-20250929-v1:0 --max-turns 10'
O formato do ID do modelo para Bedrock inclui o prefixo da região (ex., us.anthropic.claude...) e sufixo da versão.
Pré-requisitos:
  • API Vertex AI habilitada no seu projeto GCP
  • Workload Identity Federation configurado para GitHub
  • Conta de serviço com permissões Vertex AI
Segredos GitHub necessários:
Nome do SegredoDescrição
GCP_WORKLOAD_IDENTITY_PROVIDERNome do recurso do provedor de identidade workload
GCP_SERVICE_ACCOUNTEmail da conta de serviço com acesso Vertex AI
APP_IDID do seu GitHub App (das configurações do app)
APP_PRIVATE_KEYA chave privada que você gerou para seu GitHub App
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@20250514 --max-turns 10'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5
          VERTEX_REGION_CLAUDE_3_7_SONNET: us-east5
O ID do projeto é automaticamente recuperado do passo de autenticação do Google Cloud, então você não precisa codificá-lo.

​
Solução de problemas

​
Claude não respondendo a comandos @claude

Verifique se o GitHub App está instalado corretamente, verifique se os fluxos de trabalho estão habilitados, garanta 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 executando nos commits do Claude

Garanta que você está usando o GitHub App ou app personalizado (não usuário Actions), verifique se os triggers do fluxo de trabalho incluem os eventos necessários, e verifique se as permissões do app incluem triggers de CI.

​
Erros de autenticação

Confirme se a chave de API é válida e tem permissões suficientes. Para Bedrock/Vertex, verifique a configuração de credenciais e garanta que os segredos estão nomeados corretamente nos fluxos de trabalho.

​
Configuração avançada

​
Parâmetros da action

O Claude Code Action v1 usa uma configuração simplificada:
ParâmetroDescriçãoObrigatório
promptInstruções para Claude (texto ou comando slash)Não*
claude_argsArgumentos CLI passados para Claude CodeNão
anthropic_api_keyChave de API ClaudeSim**
github_tokenToken GitHub para acesso à APINão
trigger_phraseFrase de trigger personalizada (padrão: “@claude”)Não
use_bedrockUsar AWS Bedrock ao invés da API ClaudeNão
use_vertexUsar Google Vertex AI ao invés da API ClaudeNão
*Prompt é opcional - quando omitido para comentários de issue/PR, Claude responde à frase de trigger
**Obrigatório para API Claude direta, não para Bedrock/Vertex

​
Usando claude_args

O parâmetro claude_args aceita qualquer argumento CLI do Claude Code: 
claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929 --mcp-config /path/to/config.json"
Argumentos comuns:
  • --max-turns: Máximo de turnos de conversa (padrão: 10)
  • --model: Modelo a usar (ex., claude-sonnet-4-5-20250929)
  • --mcp-config: Caminho para configuração MCP
  • --allowed-tools: Lista separada por vírgulas de ferramentas permitidas
  • --debug: Habilitar saída de debug

​
Métodos alternativos de integração

Embora o comando /install-github-app seja a abordagem recomendada, você também pode:
  • GitHub App Personalizado: Para organizações que precisam de nomes de usuário com marca ou fluxos de autenticação personalizados. Crie seu próprio GitHub App com permissões necessárias (contents, issues, pull requests) e use a action actions/create-github-app-token para gerar tokens nos 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
Veja a documentação do Claude Code Action para guias detalhados sobre autenticação, segurança e configuração avançada.

​
Personalizando o comportamento do Claude

Você pode configurar o comportamento do Claude de duas maneiras:
  1. CLAUDE.md: Defina padrões de codificação, critérios de revisão e regras específicas do projeto em um arquivo CLAUDE.md na 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.
  2. Prompts personalizados: Use o parâmetro prompt no arquivo de fluxo de trabalho para fornecer instruções específicas do fluxo de trabalho. Isso permite que você personalize o comportamento do Claude para diferentes fluxos de trabalho ou tarefas.
Claude seguirá essas diretrizes ao criar PRs e responder a solicitações.