GitHub Actions: Automação Concorrente com @claude no Pull Request

📚 Navegação da Série: O capítulo anterior 43 Git Trabalho de Versionamento ensinou a usar o Claude Code localmente para gerenciar branches, commits e interagir com Pull Requests de forma segura. Este capítulo aborda a automação na nuvem: como configurar o Claude Code no GitHub Actions para que ele responda a comandos como @claude em Pull Requests ou issues, inspecionando código, sugerindo melhorias ou abrindo PRs de forma automatizada.

Imagine o seguinte cenário por volta das onze da noite: você já está deitado e pronto para dormir quando surge um alerta no grupo de trabalho.

Um colega de equipe: "Você conseguiu revisar o Pull Request do João? O deploy precisa ser feito amanhã cedo." Você: "Já estou deitado, reviso amanhã pela manhã." Colega: "Amanhã de manhã será tarde demais..."

Se o repositório estivesse configurado com o Claude Code no GitHub Actions, a revisão já estaria pronta: ao abrir o PR, a IA executaria a validação de forma automática no GitHub runner, apontando riscos de estouro de pilha e falhas de limites de índices diretamente na aba de comentários. A equipe poderia aplicar os ajustes e concluir o merge de forma imediata.

Nos capítulos anteriores, o uso do Claude Code baseou-se na interação direta via terminal da sua máquina local. O GitHub Actions permite configurar o Claude Code em servidores remotos do GitHub, acionando a execução a partir de gatilhos como a menção @claude. O agente pode responder a issues, revisar Pull Requests ou tratar falhas mesmo quando seu computador local está desligado.

Ao ler este capítulo, você obterá:

• O conceito da execução do Claude Code integrado ao GitHub Actions e sua relação com a CLI local.
• O funcionamento do gatilho de menção @claude (onde inserir e como a IA diferencia comandos válidos).
• O arquivo YAML mínimo para configurar o workflow e o papel de suas diretrizes.
• Três cenários comuns de automação: revisão de código em PRs, correções automáticas baseadas em issues e execuções agendadas.
• As diretrizes de segurança para configurar a chave de API nos Secrets do GitHub, evitando vazamento de dados.
• O passo a passo prático para configurar e testar a automação no seu repositório de testes em menos de 5 minutos.

---

01 O Claude Code Executado no GitHub Actions

A integração consiste em executar a mesma estrutura de CLI do Claude Code nos servidores do GitHub, acionada por eventos do repositório (abertura de PRs, novos comentários ou cronogramas agendados) em vez de comandos manuais no terminal local.

Até agora, o fluxo de uso exigia que você abrisse o console da máquina, digitasse claude e validasse os diffs manualmente. A execução dependia da sua presença física.

O GitHub Actions remove essa necessidade, conforme a definição oficial do recurso:

O Claude Code GitHub Actions adiciona suporte a automações de inteligência artificial nos workflows do GitHub. Utilizando a menção @claude em comentários de PRs ou issues, a IA analisa o código, implementa correções e publica Pull Requests de forma alinhada às regras do repositório.

Analogia: Um desenvolvedor plantonista. Pense na IA como um membro da equipe contratado para atuar no período da noite. Ele não exige espaço físico na empresa nem salários fixos (cobrado apenas por volume de requisições de tokens). Ao ser mencionado em um tópico de discussão com comandos como "revise este código", ele executa a tarefa e anexa a resposta no próprio canal. O trabalho é executado de forma paralela e em segundo plano.

O Claude Code no GitHub Actions utiliza a mesma engine de execução do terminal local: ele é estruturado sobre o Claude Agent SDK (Capítulo 45) e lê o arquivo CLAUDE.md do repositório para obter as diretrizes do projeto (Capítulo 18). As regras de desenvolvimento e lint declaradas localmente são respeitadas pela IA ao rodar na nuvem.

Cenários comuns de automação:

• Revisão de código (code review) automatizada: analisar o código de cada novo Pull Request aberto apontando inconsistências lógicas de forma imediata.
• Correção automática baseadas em Issues: delegar para o agente a escrita de códigos e abertura de Pull Requests correlacionados a partir de issues de melhoria.
• Correção de falhas no CI: instruir a IA a depurar erros de compilação ou testes que falharam na esteira de integração contínua.

💡 Resumo em uma frase: O Claude no GitHub Actions executa a mesma lógica da CLI em servidores da nuvem acionada por eventos do Git, respeitando as definições de desenvolvimento descritas no CLAUDE.md.

---

02 Interagindo via Menção @claude

O principal canal de interação com a IA ocorre por meio de comentários contendo o gatilho @claude nos painéis do GitHub.

Analogia: Mensagens direcionadas em grupos. Em canais de comunicação da equipe, mensagens genéricas são lidas por todos, mas não exigem ações específicas. Ao direcionar a frase com a marcação @usuario, o destinatário recebe um alerta indicando que aquela mensagem requer sua atenção direta. O gatilho do GitHub funciona de forma similar: a IA ignora discussões gerais e inicia a esteira de execução apenas quando o comentário contém o texto @claude.

Canais suportados para interagir com o agente:

• Comentários na aba de discussões do Pull Request (issue comment).
• Anotações e revisões de código na aba Files Changed do PR (pull request review comment).
• Descrições ou comentários em Issues do repositório.

Exemplos de instruções em linguagem natural para o agente:

@claude Crie a implementacao descrita nesta issue abrindo uma nova branch.
@claude Explique a logica desta funcao e verifique se existem falhas de tipagem.
@claude Corrija o erro de ArrayIndexOutOfBounds no helper de formatacao.

O agente analisará o contexto do repositório — incluindo o código-fonte, o arquivo CLAUDE.md e a issue relacionada — para propor a solução adequada no painel do GitHub.

Assim como nas diretrizes de prompts locais (Capítulo 15), quanto mais específica for a instrução, mais direcionada será a resposta da IA. Dizer @claude revise gerará observações genéricas, enquanto @claude analise riscos de SQL injection nos inputs deste controller direcionará o agente a depurar falhas específicas de segurança.

Atenção a um detalhe de caractere apontado na documentação de diagnóstico:

Certifique-se de iniciar a interação usando a marcação @claude (usando o caractere arroba), e não /claude (barra).

Configurar a automação e digitar /claude no comentário do GitHub não acionará o Actions. O caractere / é reservado para comandos do console interativo local (Capítulo 36). Na nuvem, utilize a menção @claude.

Característica	Console Local (CLI)	GitHub Actions (Nuvem)
Acionamento	Comando manual claude.	Evento do repositório (comentário, push, etc).
Gatilho de Comandos	Linha de comando do terminal ou comandos de barra /.	Menção contendo @claude em discussões.
Intervenção Humana	Requer validação e aprovação manual de diffs.	Execução automática com base em permissões do workflow.
Ambiente de Execução	Hardware local da sua máquina.	Runner virtualizado do GitHub.

💡 Resumo em uma frase: A menção @claude aciona o agente nos comentários de issues e PRs para executar tarefas de código na nuvem; utilize o caractere @ e evite o uso de barras / reservadas à CLI local.

---

03 Instalação: Automatizando a Integração no Repositório

Para ativar o suporte a menções, configure as três dependências no repositório: o GitHub App de integração, a chave de acesso da API nos Secrets e o arquivo YAML do workflow.

A forma recomendada para configurar a infraestrutura de forma automática é executar o instalador na CLI local do Claude Code:

/install-github-app

Nota: O comando /install-github-app é um comando de barra digitado na sessão local do chat do Claude (Capítulo 36), que inicializa o instalador automático.

O assistente guiará você nas seguintes etapas: instalação do app na conta do GitHub, vinculação da chave ANTHROPIC_API_KEY nas configurações de segurança do repositório e gravação do arquivo de workflow no caminho .github/workflows/.

Atente-se aos limites de infraestrutura definidos na documentação oficial:

• O instalador requer permissões de administrador (admin) no repositório do GitHub.
• O setup automatizado atende apenas usuários da API direta da Anthropic. Conexões usando Bedrock ou Vertex AI exigem setup de variáveis manual.

Se você não tiver privilégios de administrador no repositório, a gravação de Secrets e a ativação de apps de terceiros no GitHub serão bloqueadas.

O aplicativo solicita apenas três permissões de escrita e leitura no repositório, necessárias para o trabalho de desenvolvimento:

• Contents (Conteúdo): acesso ao código-fonte para aplicar refatorações.
• Issues: leitura e gravação de comentários e diagnósticos nas discussões de tarefas.
• Pull requests: permissão para criar branches adicionais e propor revisões de código.

Se preferir fazer a instalação manual, acesse o portal de aplicativos github.com/apps/claude, configure a chave do token nas opções do repositório e baixe o template YAML do repositório oficial claude-code-action/examples.

💡 Resumo em uma frase: O comando /install-github-app na CLI local configura o aplicativo, adiciona o token de segurança e cria a estrutura de arquivos no repositório, exigindo privilégios de administrador.

---

04 Anatomia do Workflow YAML

O arquivo YAML, armazenado na pasta .github/workflows/, define quais eventos ativam a IA no servidor e quais ações devem ser executadas.

Analogia: Escala de plantão. O arquivo de workflow funciona como a planilha de regras do plantonista, especificando o horário de início do expediente (gatilho de ativação) e o roteiro de tarefas a serem cumpridas.

Exemplo de workflow mínimo para responder a menções @claude em discussões:

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 }}

Análise das seções do arquivo:

• name: Identificação do fluxo exibida na aba Actions do painel do GitHub.
• on (Gatilhos de Execução): Especifica os eventos que ativam a esteira. Neste exemplo, novas postagens de comentários em issues (issue_comment) ou em revisões de código de Pull Requests (pull_request_review_comment).
• jobs (Definição do Ambiente): Inicializa uma máquina virtual Ubuntu (ubuntu-latest) para processar o repositório, garantindo o isolamento de dados.
• steps (Etapas de Execução): Invoca o action oficial do desenvolvedor (claude-code-action@v1) injetando a chave da API salva nos Secrets (ANTHROPIC_API_KEY).

O action v1 identifica de forma automática a natureza do disparo:

O action analisa as configurações de entrada para identificar se a execução segue o modo de resposta interativo (respondendo apenas a menções de tags @claude) ou o modo automatizado baseado em prompts diretos.

Se você não declarar o campo prompt nas configurações do arquivo, a IA permanecerá em modo passivo, agindo apenas quando mencionada com a tag @claude.

Evite misturar declarações antigas baseadas em versões de testes (beta) na sua folha YAML (como parâmetros mode: "tag" ou direct_prompt). Configure o arquivo utilizando a especificação do action v1.

Para passar parâmetros adicionais à CLI (como limites de iteração), utilize o campo claude_args:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Instruções específicas para a execução"
    claude_args: "--max-turns 5 --model claude-sonnet-4-6"

Parâmetros suportados no claude_args:

Parâmetro	Finalidade	Valor Padrão
--max-turns	Limita o número de loops da conversa para controlar o consumo de tokens.	10
--model	Define o modelo de inteligência artificial a ser inicializado.	Sonnet
--allowedTools	Lista de ferramentas liberadas para a sessão de processamento.	—
--mcp-config	Caminho de leitura do JSON de servidores MCP do repositório.	—

A automação utiliza por padrão a versão do modelo Sonnet. Se o fluxo exigir análises de alta complexidade ou refatorações estruturais em larga escala, configure o modelo Opus adicionando --model claude-opus-4-8 nas opções do claude_args.

💡 Resumo em uma frase: O arquivo de workflow especifica os gatilhos no bloco on e aponta para o action oficial no steps, permitindo customizar parâmetros da CLI através do campo claude_args.

---

05 Três Exemplos Práticos de Workflows

Abaixo constam as principais configurações estruturadas para atender às necessidades reais do dia a dia de desenvolvimento:

1. Revisão de Código (Code Review) Automatizada em PRs

Dispara o validador para revisar o código de cada novo Pull Request criado ou atualizado no repositório:

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: "Execute a revisão técnica deste Pull Request analisando a qualidade do código, corretude da lógica e segurança física de dados."
          claude_args: "--max-turns 5"

Este workflow dispensa a menção manual no chat. Por conter a declaração prompt e monitorar o evento pull_request, a IA analisa as alterações e anexa os apontamentos na aba de revisão do GitHub a cada atualização da branch.

2. Implementação e Correção de Bugs via Discussões

Configure o workflow para responder a chamadas específicas em Issues, permitindo que a IA desenvolva as correções baseadas nos detalhes informados pelo time:

@claude Adicione a validação de token conforme as diretrizes e abra um Pull Request.

O agente cria a branch de desenvolvimento, escreve o código com base na issue e publica o Pull Request correspondente no GitHub.

3. Análise Periódica do Status do Repositório (Cron)

Permite agendar varreduras diárias no repositório para listar avisos de segurança ou compilar atividades pendentes:

name: Relatório de Issues Pendentes
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: "Compile as principais issues abertas no repositório e crie um resumo de pendências organizadas por criticidade."

O cronograma "0 9 * * *" dispara a automação diariamente às 9 horas UTC.

Comparativo das abordagens de workflows:

Perfil	Disparador (Gatilho)	Presença do Prompt	Tipo de Resposta	Cenário Típico
Revisão de PR	pull_request	Sim	Automática (imediata)	Revisão técnica de qualidade em novas alterações.
Resolução de Tarefas	issue_comment	Não	Interativa (sob comando)	Criação de código e melhorias via issues.
Relatórios	schedule (cron)	Sim	Automática (periódica)	Análise de segurança ou compilação de status diários.

💡 Resumo em uma frase: Os fluxos atendem à revisão de PRs (execução contínua por push), desenvolvimento pontual (resposta sob menção de tag @claude) ou relatórios agendados (execução periódica via cron).

---

06 Segurança: Proteção de Chaves e Acesso no GitHub Actions

A exposição de tokens de API em arquivos YAML ou logs públicos compromete a segurança financeira e de dados da empresa.

A documentação oficial destaca a regra fundamental de segurança de tokens:

Jamais commite chaves de API em formato de texto puro no repositório Git.

Use o recurso de Secrets do GitHub para criptografar as credenciais da máquina.

Analogia: Armários de chaves blindados. Em vez de deixar a chave física da empresa pendurada na fechadura ou em gavetas acessíveis, você a armazena em um cofre digital. O workflow do Actions não lê a chave diretamente do código, mas acessa o valor criptografado usando o token correspondente.

Passos para armazenar a credencial com segurança:

1. Acesse o painel de administração do repositório no GitHub: Settings → Secrets and variables → Actions.
2. Clique no botão New repository secret.
3. Adicione o nome ANTHROPIC_API_KEY e cole a chave de API correspondente no valor. Salve.

No arquivo YAML do workflow, referencie o valor criptografado usando o formato anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}. Isso garante a proteção da credencial em repositórios públicos.

Para evitar vazamento de dados por injeções de prompt em repositórios abertos, limite a concessão de acessos à IA e realize a revisão das propostas geradas:

Ação Incorreta	Prática Recomendada de Segurança
Commitar a chave em formato legível no arquivo YAML.	Usar o segredo criptografado nos Secrets do GitHub.
Liberar acesso de gravação irrestrito para todas as seções.	Configurar as três permissões básicas de desenvolvimento (Contents, Issues, PRs).
Aceitar e mesclar PRs criados pela IA sem revisão humana.	Inspecionar a lógica de código proposta antes do merge final.
Executar comandos externos sugeridos em issues sem validação.	Validar códigos sugeridos por terceiros para evitar execuções de prompts maliciosos.

Trate os Pull Requests gerados pelas automações do Claude no GitHub Actions com o mesmo nível de rigor aplicado ao código de desenvolvedores recém-chegados.

💡 Resumo em uma frase: Salve a chave ANTHROPIC_API_KEY nos Secrets do GitHub para evitar a exposição do token no código, limitando as permissões do app e revisando as propostas de mesclagem.

---

07 Prática: Configurando o Claude Code no GitHub Actions em 5 Minutos

Configuraremos e testaremos a automação em um repositório pessoal de testes.

Requisitos: Conta no GitHub com privilégios de administração em um repositório pessoal de testes, Claude Code configurado localmente.

Passo 1: Instalar o app de integração (no terminal do projeto)

Abra a pasta do projeto de testes no terminal e inicie a CLI local:

claude

Solicite a inicialização da automação:

/install-github-app

Resultado esperado: O instalador guiará você na configuração do app no repositório. O processo grava o segredo ANTHROPIC_API_KEY no GitHub de forma segura e insere o arquivo de workflow padrão na pasta do projeto. Encerre o chat local.

Passo 2: Validar o arquivo de workflow YAML

Na raiz do seu projeto local, acesse a pasta e abra o arquivo gerado:

.github/workflows/claude.yml

Resultado esperado: O arquivo deve conter as definições de gatilho para issue_comment e pull_request_review_comment, apontando para a execução de anthropics/claude-code-action@v1.

Passo 3: Confirmar a gravação nos Secrets do GitHub

Acesse a página do seu repositório no navegador GitHub e mude para a aba Settings → Secrets and variables → Actions.

Resultado esperado: A lista deve conter o segredo ANTHROPIC_API_KEY configurado pelo instalador.

Passo 4: Criar uma Issue e testar a automação

Mude para a aba Issues do repositório no navegador, clique em New Issue e escreva o prompt a seguir no corpo do texto:

@claude Adicione a linha "Hello cloud" no final do arquivo README.md e abra um Pull Request.

Submeta a issue.

Passo 5: Acompanhar o processamento remoto

Mude para a aba Actions do painel do GitHub no seu navegador.

Resultado esperado: Uma execução do workflow de nome Claude Code deve constar na lista. Acompanhe a execução do runner. Em instantes, o Claude adicionará um comentário de confirmação no corpo da issue e criará o Pull Request com as alterações solicitadas.

Passo 6: Revisar e mesclar as alterações

Mude para a aba Pull Requests, inspecione o diff criado pelo agente e conclua o merge para fechar o ciclo de teste.

💡 Resumo em uma frase: O teste prático valida o fluxo de instalação via comando /install-github-app, checagem do YAML, confirmação do segredo no painel do GitHub, teste via menção @claude na issue e mesclagem do PR gerado.

---

08 Resumo

A integração do Claude Code com o GitHub Actions permite estender a automação de código para o ambiente na nuvem, automatizando tarefas sob demanda através de menções simples e eventos do repositório.

Pontos chaves abordados neste capítulo:

Diretriz	Detalhe
Funcionamento	Executa a CLI do Claude Code em runners do GitHub, acionada por comentários ou eventos de desenvolvimento.
Gatilhos	Responde a comandos contendo @claude (arroba) nas discussões, ignorando anotações com barras /.
Instalação	O comando /install-github-app simplifica a criação do app de integração e escrita do workflow.
Padrões	A execução na nuvem respeita as regras de linters e desenvolvimento configuradas no CLAUDE.md.
Segurança	Requer uso de Secrets do GitHub para proteger o token da API e revisão manual de segurança antes de mesclar novos PRs.

Com essa estrutura operacional, você cria ambientes de validação ágeis na nuvem para manter a integridade do código do projeto de forma contínua.

---

O próximo capítulo, 45 "Agent SDK", ensinará a programar integrações customizadas. Veremos como usar a biblioteca de desenvolvimento para embutir o motor do Claude Code em softwares próprios, construindo seus próprios assistentes de código. Nos vemos no próximo capítulo!

---

Leituras Recomendadas

• Gerenciando Permissões de Escrita
• Navegando via CLI Desktop
• Padrões de Fluxo e Desenvolvimento

---