Claude Code GitHub: configure revisões e correções com Actions

A mudança prática está em quem precisa ficar disponível. Antes, alguém da equipe tinha que abrir o repositório, iniciar o Claude, levar o resultado de volta ao GitHub e manter a sessão local rodando. Com uma Action, quem mantém o projeto deixa um pedido com escopo definido e depois volta para conferir um comentário ou uma proposta de alteração. O trabalho pode começar fora do horário dessa pessoa; o tempo necessário para conferir o resultado continua existindo.

Este guia usa a documentação atual da Anthropic, consultada em 15 de outubro de 2026. O workflow abaixo é uma configuração inicial com limites deliberados, sem a pretensão de resolver qualquer issue sem supervisão.

Claude Code GitHub: um assistente de plantão no repositório

Pense no GitHub App como o crachá de acesso, no workflow como a ordem de serviço e no runner como uma estação de trabalho temporária. O workflow é o arquivo de configuração que diz ao GitHub quando começar; o runner é a máquina que executa a tarefa.

A action pode responder a menções em issues e pull requests. Quando você fornece um prompt, ela passa a executar uma tarefa automática. Para uma equipe pequena, pedidos explícitos são o jeito mais simples de descobrir tarefas úteis antes de pagar por uma revisão a cada alteração. Como usar a action.

Instale uma vez e faça o merge do workflow

Use a instalação guiada com acesso de administrador ao repositório. Com o GitHub CLI instalado, faça a autenticação usando gh auth login, abra claude dentro do repositório e execute /install-github-app. Escolha os workflows e a autenticação por chave de API ou assinatura; depois, crie o PR preparado pelo instalador e faça o merge. A instalação acontece na sua máquina; as tarefas seguintes rodam no GitHub. Configuração rápida oficial.

O caminho manual leva ao mesmo resultado:

1. Instale o Claude GitHub App no repositório escolhido.
2. No repositório, abra Settings → Secrets and variables → Actions e adicione um dos secrets de autenticação da tabela abaixo.
3. Copie o exemplo funcional da Anthropic para .github/workflows/claude.yml, selecione o parâmetro de autenticação correspondente e faça o merge do arquivo.
4. Deixe um comentário com @claude e um pedido específico.

Esses são os passos oficiais da configuração manual, com a escolha da credencial explicitada. Guia de configuração da action.

Para usar a assinatura, execute claude setup-token localmente e salve o resultado como secret. A Anthropic documenta essa opção para os planos Pro, Max, Team e Enterprise. O token gerado vale por um ano, então defina quem será responsável pela renovação. Autenticação por token.

A cobrança depende da credencial: execuções com chave de API entram na cobrança da API; execuções com token OAuth usam sua assinatura do Claude. Já o uso dos runners do GitHub Actions é contabilizado separadamente. O token de assinatura pertence à pessoa que o gerou; a Anthropic recomenda uma chave de API para secrets compartilhados entre repositórios. Autenticação e custos.

A configuração padrão com o app dispensa um token de acesso pessoal do GitHub. O acesso ao GitHub e a autenticação no Claude são coisas separadas: o app fornece o primeiro, e o secret escolhido fornece a segunda. Parâmetros de autenticação.

Comece com um workflow enxuto, acionado por menções

Use este perfil em repositórios confiáveis da equipe e para pequenas alterações em arquivos. Ele pode ler e editar arquivos e criar commits pela API do GitHub. O Claude não recebe nenhuma ferramenta de shell; por isso, não consegue executar seus comandos de teste nesse perfil. Deixe a execução dos testes com sua CI habitual, o conjunto de verificações automáticas que roda sobre as alterações propostas.

Salve o conteúdo abaixo em .github/workflows/claude.yml. As referências às actions, actions/checkout@v6 e anthropics/claude-code-action@v1, aparecem no exemplo atual da Anthropic. O limite de cinco turnos e o timeout de quinze minutos são escolhas para começar, não valores padrão da Anthropic. Workflow oficial.

name: Claude on request
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 15
    concurrency:
      group: claude-small-team
      cancel-in-progress: false
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          use_commit_signing: true
          claude_args: |
            --max-turns 5
            --tools "Read,Glob,Grep,Edit,Write"
            --disallowedTools "Bash,WebFetch,WebSearch"

Para usar a cobrança pela assinatura, substitua a linha anthropic_api_key por claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. Configure apenas uma das opções. Mantenha id-token: write, exigido pela autenticação padrão com o GitHub App. Workflow oficial e autenticação, referência dos parâmetros.

Cada controle tem uma função:

• --tools seleciona as ferramentas nativas que o Claude pode usar. Read, Glob e Grep inspecionam arquivos; Edit e Write fazem alterações. Esse parâmetro não restringe as ferramentas MCP, conectadas separadamente, que a action usa para se comunicar com o GitHub.
• --allowedTools autoriza o uso das ferramentas indicadas sem pedir confirmação. Não é uma lista completa de ferramentas permitidas. Neste exemplo, a linha explícita com --disallowedTools bloqueia as ferramentas de shell e de acesso à web.
• --max-turns limita as iterações de trabalho do agente. Não limita tokens nem dólares, e atingir o teto pode encerrar a execução com erro e trabalho incompleto. Referência da CLI.

use_commit_signing: true faz os commits passarem pela API do GitHub. É isso que permite salvar alterações neste perfil sem dar ao Claude comandos git executados pelo shell. Não é necessário nenhum secret adicional de assinatura. As ferramentas de GitHub da action continuam disponíveis, portanto esse perfil tem capacidade de escrita. Assinatura de commits, implementação da action.

O grupo fixo de concorrência permite uma tarefa deste workflow em execução por repositório. Com o comportamento padrão da fila, um novo pedido pendente pode substituir outro que já estava esperando; essa fila não garante a preservação de todas as tarefas. O timeout limita o tempo total da tarefa, incluindo a preparação do ambiente. Concorrência no GitHub, sintaxe dos workflows.

Experimente @claude review this PR for missing permission checks; report findings without changing files. Para uma issue, tente @claude fix the null handling described above, change only the parser and its regression test, and state which checks were not run.

Por padrão, quem aciona a tarefa precisa ter acesso de escrita ao repositório, e bots são bloqueados. Ao pedir a correção de uma issue, espere receber uma branch e um link para uma pessoa criar o PR. Deixe essa distinção clara nas instruções da equipe. Segurança da action.

Ative as revisões automáticas depois do teste inicial

Para revisar PRs automaticamente, selecione o workflow de revisão durante a configuração com /install-github-app. O plugin de revisão de código usa --comment e a permissão para a ferramenta de comentários mostrada abaixo para publicar os problemas encontrados. Exemplo oficial de revisão.

Nesse workflow separado de revisão, os parâmetros da action incluem:

plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
plugins: "code-review@claude-code-plugins"
prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
claude_args: >-
  --max-turns 5
  --allowedTools "mcp__github_inline_comment__create_inline_comment"

Use esses parâmetros no workflow oficial de pull_request, não no workflow por menções apresentado acima. Mantenha o checkout, a autenticação e as permissões da tarefa, acrescente um timeout e ignore PRs de forks com if: github.event.pull_request.head.repo.full_name == github.repository. Trate o limite de turnos como uma configuração de piloto: uma revisão que esgota os turnos está incompleta. A skill de revisão documentada também ignora alguns PRs, incluindo rascunhos.

Separe o alcance da instalação do acesso às ferramentas

Comece instalando o app apenas nos repositórios selecionados. O app oficial do Claude compartilha permissões entre vários recursos do Claude, e o GitHub não permite aceitar só uma parte desse conjunto. Um bloco YAML permissions enxuto não reduz o alcance da instalação do app. Modelo de permissões do app.

Se esse acesso for amplo demais, siga a configuração de um app próprio com acesso a Contents, Issues e Pull requests. Ela acrescenta os secrets APP_ID e APP_PRIVATE_KEY, além de uma etapa que cria um token do app e o passa como github_token. Para equipes prontas para abandonar chaves estáticas da API do Claude, o guia também documenta a federação de identidade de cargas de trabalho, que troca a identidade da tarefa no GitHub por acesso de curta duração à API. Configuração de app próprio e federação.

Adicione um CLAUDE.md conciso com as prioridades de revisão, as áreas em que alterações são permitidas e as evidências que uma correção deve apresentar. As instruções orientam o trabalho; as permissões do repositório e as restrições de ferramentas impõem os limites de acesso. Antes de habilitar execuções sem supervisão, revise os hooks configurados, comandos executados automaticamente em eventos do ciclo de vida, e os servidores de ferramentas adicionais. Instruções do projeto. Nossa análise do Claude Code ajuda a avaliar a ferramenta de forma mais ampla, e o guia de comandos de barra explica os comandos usados na configuração.

Seis tarefas para começar, em ordem de prioridade

Comece pelos pedidos fáceis de descrever e pelos resultados fáceis de conferir. São sugestões de workflows, sem promessa de economia medida ou resultados garantidos.

O perfil inicial não pode instalar dependências nem executar uma suíte de testes. Se a tarefa exigir isso, acrescente um perfil de execução para código confiável, revisado separadamente, com permissões para comandos específicos e limites próprios. Um comando de teste permitido ainda executa código do repositório; um nome inofensivo não torna esse código seguro.

Resolva estas falhas antes de adicionar mais gatilhos

PRs de forks podem ficar sem acesso aos secrets. O GitHub normalmente não disponibiliza secrets para execuções de pull_request e pull_request_review_comment acionadas por forks. Uma credencial do Claude vazia nessas tarefas é consequência dessa separação de confiança. Não mude para pull_request_target e execute o código do fork só para obter os secrets. Uma tarefa de issue_comment acionada por quem mantém o projeto também pode ter secrets; confiar em quem comentou não torna os arquivos do PR confiáveis. Orientações do GitHub sobre segurança de forks.

Limites de ferramentas não neutralizam o código de inicialização do projeto. A action restaura determinadas configurações do Claude a partir da branch base, mas scripts e outros arquivos do projeto ainda podem vir do PR. Audite os hooks e a configuração dos servidores de ferramentas, além das ferramentas permitidas ao Claude. Limites de confiança da action.

O tempo de runner continua sendo um limite separado. Runners padrão hospedados pelo GitHub são gratuitos para repositórios públicos. Repositórios privados têm franquias conforme o plano e cobrança pelo excedente; esgotar a franquia sem uma forma de pagamento pode interromper as tarefas. Consulte a página de uso do Actions junto com o consumo do Claude. Cobrança do GitHub Actions.

Limites de uso podem interromper um workflow válido. Os limites da API abrangem requisições e tokens de entrada e saída, os trechos de texto processados pelo modelo, por minuto. Ao receber um 429 com retry-after, espere antes de tentar novamente e reduza as tarefas simultâneas. Um 429 causado pelo teto de gastos da faixa de uso, sem esse cabeçalho, exige resolver a cobrança ou o limite; repetir a execução não resolve. A autenticação por assinatura continua sujeita aos limites de uso do plano. Limites da API, limites de uso do Claude.

Um bot que não responde e uma CI que não roda são falhas diferentes. Se não houver resposta, confira se o workflow existe na branch padrão, se o Actions está habilitado, se o secret corresponde ao parâmetro configurado e se quem comentou tem acesso de escrita. Use a menção completa @claude. Se a CI não for acionada depois, verifique se alguém substituiu a autenticação do app por github_token: ${{ secrets.GITHUB_TOKEN }}: o GitHub suprime muitos eventos criados com esse token, e alguns workflows de PR exigem aprovação. Comportamento do token do GitHub.

Duas oportunidades de negócio a partir desse workflow

A oportunidade mais forte é um serviço gerenciado de revisão para equipes pequenas. Quem compra é uma liderança de engenharia que quer apontamentos úteis, responsabilidades claras e limites operacionais previsíveis. As estimativas da DataForSEO para buscas em inglês nos Estados Unidos, consultadas em 15 de outubro de 2026, indicam 1,300 buscas mensais por “ai code review”. Isso sinaliza interesse; não é uma contagem de clientes. Uma primeira versão comercial poderia configurar um repositório, registrar suas prioridades de revisão, avaliar os apontamentos em PRs históricos e entregar um relatório contínuo de uso e falhas. A dificuldade está no desgaste causado por falsos positivos: o trabalho que sustenta o serviço é manter a qualidade das revisões conforme a base de código muda. Uma camada genérica em torno de um prompt oferece pouco motivo para continuar usando o produto.

Uma agência poderia comprar um pacote reutilizável de políticas de revisão para os repositórios dos clientes. A DataForSEO estima 590 buscas mensais por “ai code review tools” e 140 por “github ai code review” no mesmo mercado. A versão mínima do produto poderia reunir um workflow reutilizável, modelos de instrução específicos por cliente, registros de responsabilidade pelas credenciais e verificações de limites ausentes. Isso poderia ajudar a agência a manter configurações consistentes nas passagens de responsabilidade. A dificuldade é que as permissões e o ambiente de testes variam de cliente para cliente; um template precisa de manutenção e avaliação para continuar útil. Os públicos dessas buscas se sobrepõem, portanto não some os volumes como se representassem o tamanho do mercado.

Escolha onde executar de acordo com a tarefa

Escolha GitHub Actions quando o trabalho estiver ligado a um evento do repositório e a equipe quiser gerenciar configuração, permissões e logs junto com a CI. Escolha uma sessão na nuvem para uma tarefa pontual que você queira iniciar e orientar pelo navegador, mesmo com o notebook fechado. Escolha uma rotina agendada para uma tarefa recorrente salva, como uma checagem noturna do backlog, se preferir o agendamento e a configuração hospedados pelo Claude à manutenção de um workflow em YAML. As rotinas também aceitam gatilhos do GitHub e da API; a necessidade de agendar, por si só, não obriga a usar Actions. As rotinas continuam em prévia de pesquisa. Sessões na nuvem, rotinas.

Na segunda-feira, peça a quem administra o repositório que instale o app e faça o merge do workflow com esses limites. Passe um bug conhecido e um pedido de revisão com foco definido; depois, compare o resultado com a avaliação da própria equipe. Amplie os gatilhos só quando os resultados justificarem a atenção e o consumo.

Se quiser esse workflow implementado e mantido para sua equipe, conte com ajuda em automação com IA.