Claude Code no GitHub Actions: revisão de PR com segurança

Claude Code no GitHub Actions: revisão de PR com segurança

Para usar o Claude Code no GitHub Actions, instale a action oficial da Anthropic no repositório, guarde a chave de API em um secret, dê ao workflow apenas leitura de código e escrita de comentários em pull requests e dispare a revisão a cada PR. O que separa um piloto seguro de um risco é limitar permissões, ferramentas e gatilhos antes de ligar. Este guia segue a documentação oficial e deixa claro o que é documentação, o que é prática de implementação e o que é hipótese a validar no seu repositório.

Principais pontos

• A integração oficial roda o Claude Code como uma etapa do workflow e comenta no pull request, sem substituir a aprovação de uma pessoa.
• A chave de API deve ficar em GitHub Secrets, nunca no arquivo do workflow nem em variáveis impressas no log.
• O bloco de permissões do workflow e a lista de ferramentas liberadas para o agente são as duas travas principais. Comece só com leitura.
• Código de PR é entrada não confiável: trate texto de PR, issues e arquivos como possível tentativa de prompt injection.
• Comece com um repositório e um fluxo, defina uma métrica de sucesso antes e decida depois do piloto se expande, ajusta ou para.

O que o Claude Code faz dentro de um pipeline?

No uso interativo, o Claude Code roda no terminal de uma pessoa, que enxerga cada passo e aprova ações. No CI, ele roda sem ninguém olhando em tempo real. Essa diferença muda tudo: o que era uma pergunta de permissão na tela vira uma configuração que você precisa decidir antes.

A documentação oficial descreve a integração com o GitHub Actions por meio da action claude-code-action. Ela permite dois usos principais: responder a menções, quando alguém escreve @claude em um comentário de PR ou issue, e rodar automaticamente com um prompt fixo quando um evento acontece, como a abertura ou atualização de um pull request. Para revisão, o segundo modo costuma ser o mais previsível, porque o prompt é seu e versionado, e não depende de quem escreveu o comentário.

O agente lê o código do repositório, considera o diff e as instruções do arquivo CLAUDE.md, e devolve comentários. Se você liberar mais permissões, ele também pode editar arquivos e abrir commits. Para uma primeira fase de revisão, não libere isso. Se quiser entender como escrever esse arquivo de contexto, veja Como escrever um bom CLAUDE.md para o repositório da empresa.

O que preparar antes de ligar?

Antes de abrir o editor de workflow, resolva as decisões que não são técnicas. Elas evitam retrabalho e deixam o piloto defensável perante quem cuida de segurança e de LGPD na empresa.

• Escolha um repositório de risco baixo ou médio, com testes razoáveis e donos de código claros. Evite começar pelo repositório que toca pagamentos ou dados pessoais sensíveis.
• Defina quem é responsável pela chave de API e pelo custo do uso. Crie uma chave exclusiva para o CI, separada das chaves de desenvolvimento.
• Decida o que a revisão automática deve olhar: bugs prováveis, falta de testes, padrões da equipe, riscos de segurança. Uma lista curta funciona melhor que um pedido genérico de revisar tudo.
• Combine a regra de ouro: o comentário do agente é uma sugestão, e a aprovação do merge continua com uma pessoa.
• Escreva a métrica de sucesso antes de começar. Exemplo: o time considera úteis a maioria dos comentários numa amostra revisada por humanos. Sem isso, o piloto vira opinião.

Se o código do repositório contém dados pessoais de clientes (fixtures, dumps, logs commitados), isso precisa ser limpo ou fora do alcance do agente, porque o conteúdo lido pode ser enviado ao provedor do modelo. Para o contexto regulatório, veja LGPD e inteligência artificial: o que a empresa deve fazer.

Passo a passo para a primeira revisão automática

O roteiro abaixo segue o fluxo descrito na documentação oficial da Anthropic. Os nomes exatos de inputs e a versão atual da action mudam com o tempo, então confira a página oficial antes de copiar qualquer coisa.

• Passo 1, instalação do app: a documentação indica o comando de instalação do GitHub App a partir do próprio Claude Code, ou a instalação manual do app no repositório. Instale só nos repositórios do piloto, não na organização inteira.
• Passo 2, secret: em Settings, Secrets and variables, Actions, crie o secret ANTHROPIC_API_KEY com a chave exclusiva do CI. O workflow referencia o secret pelo nome, e o valor nunca aparece no arquivo.
• Passo 3, arquivo de workflow: crie um arquivo dentro de .github/workflows. O gatilho é o evento de pull request (aberto e atualizado). A etapa usa a action oficial da Anthropic, recebe a chave pelo secret e um prompt de revisão escrito por você.
• Passo 4, permissões explícitas: declare o bloco permissions no workflow. Para comentar em PR, em geral basta leitura de conteúdo e escrita em pull requests. Confira na documentação se o modo escolhido exige alguma permissão adicional, como a de identidade usada em autenticações com a nuvem.
• Passo 5, prompt de revisão: peça uma saída objetiva. Por exemplo: apontar até alguns problemas por PR, cada um com arquivo, motivo e sugestão, ignorar estilo que o linter já cobre e dizer quando não houver nada relevante.
• Passo 6, limites de execução: use as opções de argumentos da action para limitar o número de turnos do agente e restringir as ferramentas permitidas. Isso controla custo e superfície de ação.
• Passo 7, teste em um PR descartável: abra um PR de teste com um erro plantado de propósito e verifique se o comentário aparece, se aponta o erro e se o log não expõe nada sensível.
• Passo 8, fixe a versão: referencie a action por uma versão estável ou, melhor, pelo hash do commit, como recomenda o guia de endurecimento de segurança do GitHub Actions. Atualize de forma deliberada.

O resultado esperado é simples: a cada PR, um comentário curto e útil, sem alterar código e sem acesso a nada além do necessário.

Como restringir permissões do workflow e do agente?

Há duas camadas de permissão, e as duas importam.

A primeira é do GitHub. O token que o workflow recebe pode ter escopo amplo por padrão, dependendo da configuração do repositório ou da organização. A prática recomendada na documentação do GitHub é declarar o bloco permissions e conceder o mínimo. Para revisão, isso significa leitura do conteúdo do repositório e escrita apenas onde o comentário é publicado. Não conceda escrita de conteúdo se o agente não deve commitar.

A segunda camada é do Claude Code. A action permite definir quais ferramentas o agente pode usar. Uma revisão só precisa ler arquivos, buscar no código e ver o diff. Ela não precisa executar comandos arbitrários de shell, acessar a rede ou instalar pacotes. Se algum dia precisar rodar os testes, libere um comando específico, e não o shell inteiro. A lógica é a mesma explicada em Segurança no Claude Code para empresas: permissões, sandbox e segredos: negar por padrão e liberar por exceção documentada.

Um checklist rápido para revisar o workflow antes de aceitar o merge dele:

• O bloco permissions existe e está no nível mínimo?
• O agente tem acesso apenas às ferramentas de leitura?
• Há limite de turnos para evitar laços longos e custo imprevisto?
• A action está fixada em versão ou hash?
• O workflow roda só nos eventos e branches pretendidos?
• Quem pode alterar o arquivo de workflow é um grupo pequeno, com revisão obrigatória?

Essa última pergunta é fácil de esquecer. Se qualquer pessoa pode editar o workflow em um PR e esse PR roda com segredos, o controle é só aparente.

Como proteger segredos e evitar prompt injection?

Segredos em CI têm três riscos típicos: vazar em log, ser lido por código que não é seu e ficar vivo por tempo demais.

Sobre o primeiro, use sempre GitHub Secrets, nunca escreva a chave no YAML e não imprima variáveis de ambiente em etapas de depuração. O GitHub mascara valores de secrets nos logs, mas a mascaração não cobre transformações do valor, então não conte com ela como defesa única.

Sobre o segundo, preste atenção em PRs vindos de forks. Por padrão, o GitHub não entrega secrets a workflows disparados por pull requests de forks, e isso é uma proteção útil. Existem gatilhos que contornam essa restrição, como o pull_request_target, e o guia de segurança do GitHub avisa que eles exigem cuidado porque executam no contexto do repositório base. Se o seu repositório recebe contribuições externas, mantenha a revisão automática restrita a branches internas no piloto.

Sobre o terceiro, trate a chave como descartável: tenha dono, limite de uso no provedor quando possível e rotina de rotação. O texto Chaves de API em agentes de IA: onde guardar e como rotacionar detalha esse ciclo.

Há ainda a questão do prompt injection. Quem escreve o título do PR, a descrição, um comentário ou até um arquivo de código pode incluir instruções dirigidas ao modelo, como ignorar as regras anteriores e revelar informações. Em uma revisão que só lê e comenta, o dano é menor, mas continua real: o comentário pode ser manipulado, e, se houver ferramentas de escrita ou rede, o impacto cresce. As referências da OWASP sobre prevenção de prompt injection e o Top 10 para aplicações com LLM são o ponto de partida. Na prática, o que mais protege é a combinação de permissões mínimas, ausência de segredos úteis ao alcance do agente e revisão humana antes de qualquer ação.

Cenário ilustrativo: um time pequeno e um repositório de API

Cenário ilustrativo: uma empresa de logística tem um time pequeno que mantém uma API interna de rastreamento. Os PRs ficam parados esperando revisão porque duas pessoas sêniores concentram a aprovação. O time decide testar o Claude Code no CI.

Eles mapeiam o fluxo atual: quem abre o PR, quem revisa, onde costumam aparecer os problemas repetidos (validação de entrada, falta de teste para casos de borda, queries sem paginação). Em seguida limitam: o workflow só roda em PRs de branches internas, com permissão de leitura de conteúdo e escrita em pull requests, e o agente só pode ler arquivos. O prompt pede no máximo alguns apontamentos por PR, focados nos três problemas recorrentes.

No piloto, a revisão automática comenta antes de os revisores humanos olharem. As pessoas continuam aprovando. Ao fim do período combinado, o time amostra os comentários, marca cada um como útil, ruidoso ou errado e decide: expandir para outro repositório, ajustar o prompt ou parar. Nada aqui depende de um número prometido, só da amostra que o próprio time coletou.

Como medir se a revisão automática vale a pena?

A aplicação do método de trabalho aqui é direta: mapear, limitar, pilotar e transferir. Mapear é entender o processo atual de revisão e onde o tempo se perde. Limitar é decidir permissões, ferramentas e repositórios. Pilotar é rodar um fluxo real com logs e uma métrica combinada. Transferir é entregar para o time com documentação do workflow, dono da chave e critério de decisão para continuar.

Para medir, use sinais simples que você consegue coletar sem ferramenta nova:

• Proporção de comentários que o time considerou úteis numa amostra revisada por pessoas.
• Comentários errados ou fora de contexto, que indicam prompt ou CLAUDE.md a ajustar.
• Tempo entre abrir o PR e o primeiro feedback, comparado ao período anterior ao piloto.
• Custo de uso por PR, acompanhado no painel do provedor, para saber se o modelo de uso cabe no orçamento.
• Incidentes: qualquer log com dado sensível, comentário manipulado ou permissão usada além do previsto.

Para estruturar critérios de decisão ao final, o guia Como medir um piloto de automação com IA: métricas e gates de decisão ajuda a definir o que significa expandir, ajustar ou parar. Se a ideia é levar o uso para o time inteiro, o guia de adoção do Claude Code para equipes cobre papéis e governança.

Uma hipótese a validar no seu contexto: revisão automática tende a ser mais útil para padrões repetitivos e menos para decisões de arquitetura. Isso não vem da documentação, vem da lógica do que um agente enxerga num diff. Teste no seu repositório antes de generalizar.

Perguntas frequentes

O Claude Code no GitHub Actions substitui a revisão de código humana? Não. Ele funciona como uma primeira leitura que aponta problemas prováveis e padrões da equipe. A decisão de aprovar o merge deve continuar com uma pessoa responsável, principalmente em código que toca dados pessoais ou regras de negócio críticas.

Preciso dar permissão de escrita para o agente revisar PRs? Para comentar, o workflow precisa de escrita apenas em pull requests, e a leitura do conteúdo do repositório. Não é necessário liberar escrita de conteúdo nem execução livre de comandos. Se mais adiante você quiser que o agente sugira correções por commit, trate isso como uma segunda fase, com novo piloto e nova revisão de riscos.

É seguro rodar a revisão em PRs de forks ou de contribuidores externos? É a situação de maior risco, porque o conteúdo do PR é totalmente controlado por terceiros e pode conter prompt injection. Por padrão o GitHub não entrega secrets a workflows de PRs de forks, e vale manter esse comportamento. No piloto, restrinja a revisão automática a branches internas e só avalie o caso externo depois, com revisão específica de segurança.

Onde ficam os dados do meu código quando o agente roda? O conteúdo que o agente lê no job é enviado ao provedor do modelo para gerar a resposta, e o job executa nos runners do GitHub, hospedados ou próprios. Confira os termos de uso e de retenção de dados do provedor e alinhe com quem responde por LGPD na sua empresa. Se houver dados pessoais no repositório, limpe ou exclua esses arquivos do alcance do agente antes de começar.

Fontes

• Anthropic: Claude Code com GitHub Actions
• GitHub: Security hardening for GitHub Actions
• OWASP: prevenção de prompt injection
• OWASP Top 10 para aplicações com LLM