Claude Code GitHub Actions

Saiba como integrar Claude Code no seu fluxo de trabalho de desenvolvimento com Claude Code GitHub Actions

Claude Code GitHub Actions traz automação alimentada por IA para 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 enquanto segue os padrões do seu projeto. Para análises automáticas postadas em cada PR sem um gatilho, consulte GitHub Code Review.

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.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 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 action é 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 secrets necessários.

Configuração manual

Se o comando /install-github-app falhar ou você preferir configuração manual, siga estas instruções de configuração manual:

1. 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)

   Para mais detalhes sobre segurança e permissões, consulte a documentação de segurança.

2. Adicione ANTHROPIC_API_KEY aos seus secrets do repositório (Saiba como usar secrets no GitHub Actions)

3. Copie o arquivo de fluxo de trabalho de examples/claude.yml para a pasta .github/workflows/ do seu repositório

Atualizando da versão 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:

1. Atualize a versão da action: Mude @beta para @v1
2. Remova a configuração de modo: Delete mode: "tag" ou mode: "agent" (agora detectado automaticamente)
3. Atualize as entradas de prompt: Substitua direct_prompt por prompt
4. Mova as opções de CLI: Converta max_turns, model, custom_instructions, etc. para claude_args

Referência de Mudanças Significativas

Exemplo Antes e Depois

Versão 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"

Versão 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: |
      --append-system-prompt "Follow our coding standards"
      --max-turns 10
      --model claude-sonnet-4-6

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

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

Usando skills

A entrada prompt aceita uma invocação de skill bem como texto simples:

• Para uma skill no diretório .claude/skills/ do seu repositório, execute actions/checkout antes da etapa de ação e passe /skill-name.
• Para uma skill empacotada em um plugin, instale o plugin com as entradas plugin_marketplaces e plugins e passe a /plugin-name:skill-name com namespace.

O fluxo de trabalho a seguir instala o plugin code-review e executa sua skill em cada pull request novo ou atualizado:

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 }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

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: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model opus"

Casos de uso comuns

Em comentários de issue ou 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

Claude analisará automaticamente 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 a compreensão de Claude dos 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 secret do repositório nomeado ANTHROPIC_API_KEY
• Referencie-a em fluxos de trabalho: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
• Limite as permissões da action apenas ao necessário
• Revise as sugestões de Claude antes de fazer merge

Sempre use GitHub Secrets (por exemplo, ${{ secrets.ANTHROPIC_API_KEY }}) em vez de codificar chaves de API diretamente em seus arquivos de fluxo de trabalho.

Otimizando desempenho

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 é executado em runners hospedados pelo GitHub, que consomem seus minutos do GitHub Actions
• Consulte a documentação de faturamento do GitHub para detalhes de preços e limites de minutos

Custos de API:

• 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 as taxas de token atuais

Dicas de otimização de custos:

• Use comandos específicos @claude para reduzir chamadas de API desnecessárias
• Configure --max-turns apropriado em claude_args para 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:

- 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

Recursos principais:

• Interface de prompt unificada - Use prompt para todas as instruções
• Skills - Invoque skills instaladas diretamente do prompt
• Passagem de CLI - Qualquer argumento de CLI do Claude Code via claude_args
• Gatilhos flexíveis - Funciona com qualquer evento do GitHub

Visite o diretório de exemplos para arquivos de fluxo de trabalho completos.

Usando com Amazon Bedrock & Google Vertex AI

Para ambientes empresariais, você pode usar Claude Code GitHub Actions com sua própria infraestrutura em 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:

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. Uma GitHub App (recomendado) ou use o GITHUB_TOKEN padrão

Para Amazon 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 do Bedrock
4. Uma GitHub App (recomendado) ou use o GITHUB_TOKEN padrão

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-6 --max-turns 10'

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-5@20250929 --max-turns 10'
env:
ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
CLOUD_ML_REGION: us-east5
VERTEX_REGION_CLAUDE_4_5_SONNET: us-east5

Troubleshooting

Claude não responde aos comandos @claude

Verifique se a GitHub App está instalada corretamente, confirme que os fluxos de trabalho estão habilitados, garanta que a chave de API está definida nos secrets 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

Garanta que você está usando a GitHub App ou app personalizada (não usuário Actions), verifique se os gatilhos do fluxo de trabalho incluem os eventos necessários e confirme que as permissões da 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 garanta que os secrets estejam nomeados corretamente nos fluxos de trabalho.

Configuração avançada

Parâmetros da Action

A Claude Code Action v1 usa uma configuração simplificada:

*Prompt é opcional - quando omitido para comentários de issue/PR, Claude responde à frase de gatilho
**Necessário para Claude API direto, não para Bedrock/Vertex

Passe argumentos de CLI

O parâmetro claude_args aceita qualquer argumento de CLI do Claude Code:

claude_args: "--max-turns 5 --model claude-sonnet-4-6 --mcp-config /path/to/config.json"

Argumentos comuns:

• --max-turns: Máximo de turnos de conversa (padrão: 10)
• --model: Modelo a usar (por exemplo, claude-sonnet-4-6)
• --mcp-config: Caminho para configuração MCP
• --allowedTools: Lista separada por vírgula de ferramentas permitidas. O alias --allowed-tools também funciona.
• --debug: Habilitar 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 Personalizada: Para organizações que precisam de nomes de usuário personalizados ou fluxos de autenticação personalizados. Crie sua própria GitHub App com permissões necessárias (contents, issues, pull requests) e use a action 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

Consulte a documentação do Claude Code Action para guias detalhados sobre autenticação, segurança e configuração avançada.

Personalizando o comportamento de Claude

Você pode configurar o comportamento de 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 Memory 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 de Claude para diferentes fluxos de trabalho ou tarefas.

Claude seguirá essas diretrizes ao criar PRs e responder a solicitações.