Claude Code no GitHub Actions: configuração e workflows

O Claude Code no GitHub Actions permite rodar o Claude Code dentro de um workflow do GitHub. Você menciona @claude em uma issue ou pull request, e o Claude lê o código, responde, escreve uma correção em uma branch nova ou revisa o diff, tudo em um runner do GitHub. O jeito mais rápido de configurar é abrir o Claude Code no seu repositório e rodar /install-github-app. Ele instala o Claude GitHub App, salva sua chave como secret do repositório e abre um pull request com os arquivos de workflow.

Este guia cobre os dois caminhos de configuração, os inputs da action oficial anthropics/claude-code-action, os dois modos (menções e automação), um workflow pronto de revisão de PR, secrets, controles de custo e permissão, e os casos em que rodar o Claude localmente é a melhor escolha. Tudo aqui segue a documentação da Anthropic e o README da action em outubro de 2026. Se o que você quer é um agente que conserta builds de CI vermelhos sozinho, isso tem um post próprio: corrigir falhas de CI automaticamente com IA.

O que a action faz

anthropics/claude-code-action@v1 é uma GitHub Action que roda o agente Claude Code no seu próprio runner do GitHub. Ela funciona em dois modos:

• Interativo (menções). Se você não passa um prompt, ela espera uma frase de disparo, @claude por padrão. A frase pode estar em um comentário de issue ou PR, em uma revisão de PR, ou no título ou corpo de uma issue nova. O Claude responde em um comentário e pode fazer push de uma branch com mudanças.
• Automação. Se você define prompt, o Claude executa essa tarefa assim que o workflow dispara, sem precisar de menção. Os resultados vão para o log da execução, a menos que o prompt ou um plugin diga ao Claude para publicar em algum lugar. É assim que se montam revisões de PR, relatórios agendados e triagem de issues.

O agente segue as mesmas regras do seu terminal. Ele lê o CLAUDE.md, usa as ferramentas que você permite e para no limite de turnos que você define.

Passo 1: configuração rápida com /install-github-app

Abra o Claude Code no repositório e rode:

/install-github-app

Antes de começar, confira três coisas:

• Você é admin do repositório. Instalar o app e adicionar secrets exigem direitos de admin.
• O repositório está no github.com. Se o remote está no gitlab.com ou no bitbucket.org, o comando mostra um aviso e sai.
• O GitHub CLI está logado. Rode gh auth login antes, se ainda não fez.

O comando guia você pelo processo. Ele instala o Claude GitHub App no repo e pergunta como o Claude deve se autenticar. Depois salva ANTHROPIC_API_KEY (uma chave de API) ou CLAUDE_CODE_OAUTH_TOKEN (um token ligado à sua assinatura do Claude) como secret do repositório. Se já existe uma chave, ele pode reaproveitá-la. Por fim, faz push de uma branch com os arquivos de workflow e abre um pull request para você fazer o merge.

Você recebe dois workflows: claude.yml responde às menções @claude, e claude-code-review.yml revisa pull requests. Aperte Esc para parar no meio, ou escolha “Skip for now” (pular por enquanto) depois que o app estiver instalado, se quiser escrever os workflows você mesmo. Se rodar o comando de novo mais tarde, ele oferece atualizar o arquivo de workflow para a versão mais recente.

A configuração rápida funciona com a API do Claude e com assinaturas do Claude. Se você usa Amazon Bedrock, Google Cloud ou Microsoft Foundry, siga o caminho manual e a seção de provedores de nuvem da documentação.

Passo 2: configuração manual

Se o comando não se encaixa na sua situação, os mesmos três passos à mão são:

1. Instale o Claude GitHub App em github.com/apps/claude no repositório. A action usa as permissões Contents, Issues e Pull requests dele, cada uma com leitura e escrita.
2. Adicione um secret em Settings → Secrets and variables → Actions:
   • ANTHROPIC_API_KEY: uma chave de API do Claude Console, cobrada por token, ou
   • CLAUDE_CODE_OAUTH_TOKEN: rode claude setup-token localmente para criar um; funciona com os planos Pro, Max, Team e Enterprise.
3. Copie o workflow de exemplo claude.yml da pasta examples/ da action para .github/workflows/.

Aqui está um workflow de menções que funciona:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Duas permissões são fáceis de esquecer. id-token: write é necessária para a autenticação padrão pelo GitHub App. actions: read deixa o Claude ler os resultados do CI, então você pode perguntar por que um check falhou. Se você usa um token de assinatura, troque a última linha por claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Para uma organização, a documentação sugere instalar o app no nível da organização, colocar a chave em um secret de Actions da organização e chamar um workflow reutilizável a partir de cada repo. Ela também recomenda uma chave de API em vez de um token OAuth para secrets compartilhados, porque um token pertence à assinatura de uma pessoa. Se você prefere não guardar nenhuma chave de longa duração, a action suporta workload identity federation (OIDC) pelos inputs anthropic_federation_rule_id e anthropic_organization_id.

Passo 3: use @claude em issues e pull requests

Com o workflow na branch padrão, escreva um comentário:

@claude why does the checkout test fail on Node 22? Fix it if the cause is in our code.

@claude implement this issue. Keep the public API unchanged and add tests.

@claude review the error handling in src/payments/ and suggest changes inline.

O Claude responde em um comentário. Quando altera código, faz push para uma branch que começa com claude/ (o input branch_prefix muda isso) e dá um link para abrir o pull request. Algumas regras decidem quem pode iniciar uma execução:

• Quem comenta precisa de acesso de escrita. Usuários sem acesso são ignorados, a menos que você os liste em allowed_non_write_users, o que também exige um github_token seu.
• Bots são ignorados, a menos que você os nomeie em allowed_bots. Definir como "*" aceita qualquer bot, o que o README desaconselha em repositórios públicos.
• O gatilho é uma palavra inteira. @claude funciona, /claude e @claude-bot não. Mude com trigger_phrase se precisar.

Também existem assignee_trigger (inicia quando uma issue é atribuída a um usuário específico) e label_trigger (inicia quando um label é adicionado, claude por padrão). Combine-os com os tipos de evento issues certos em on:.

Passo 4: um workflow de revisão automática de PR

O workflow de revisão abaixo é o que vem na documentação. Ele roda em todo pull request aberto, atualizado, reaberto ou marcado como pronto para revisão, sem ninguém digitar @claude:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      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 }}
          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: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

O que cada parte faz:

• plugin_marketplaces e plugins carregam o plugin oficial code-review.
• prompt roda o comando dele no PR atual. --comment publica os achados como comentários inline, ou como um único comentário de resumo.
• A linha claude_args é obrigatória. Sem --allowedTools para a ferramenta de comentário inline, o servidor MCP que publica comentários não inicia.

O plugin pula PRs em rascunho, fechados e triviais, e PRs em que ele já comentou. Pull requests vindos de forks de um repositório público não recebem os secrets do repositório, então a revisão não roda neles. A Anthropic também oferece um produto gerenciado separado chamado Code Review, que revisa PRs sem nenhum arquivo de workflow. A action é a opção que você controla e roda no seu próprio runner.

Para uma visão mais ampla do que a revisão por IA pega e do que ela deixa passar, veja revisão de código com IA.

Passo 5: automações agendadas e personalizadas

Com prompt você roda qualquer tarefa em qualquer evento do GitHub. Um resumo diário fica assim:

name: Daily report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Summarize yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Lembre que, com um prompt simples, o Claude não tem shell nem acesso à API do GitHub até você liberar ferramentas com --allowedTools ou uma regra permissions.allow no input settings. Workflows agendados só rodam a partir da branch padrão, e o GitHub os desativa em repositórios públicos depois de 60 dias sem atividade.

Os inputs que você vai usar de verdade

A action tem muitos inputs. Estes são os mais comuns:

Outros úteis do README: base_branch e branch_prefix para onde o Claude faz push, use_sticky_comment para manter um único comentário que se atualiza, track_progress para publicar comentários de acompanhamento em eventos de PR e issue, use_commit_signing para assinar commits e additional_permissions (por exemplo actions: read). A action também retorna outputs como branch_name, session_id e structured_output para os passos seguintes.

Se você usava a versão beta, a atualização é mecânica. Troque @beta por @v1, remova mode, renomeie direct_prompt para prompt, mova max_turns e model para dentro de claude_args e transforme custom_instructions em --append-system-prompt.

Secrets: o que vai onde

• Nunca coloque uma chave em um arquivo de workflow. Use ${{ secrets.ANTHROPIC_API_KEY }} ou ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.
• Mantenha os secrets no nível mais restrito que funcione: um secret de repositório para um repo, um secret de organização limitado a repositórios selecionados para vários.
• Deixe show_full_output desligado em repos públicos. O README avisa que a saída completa nos logs pode expor secrets.
• Trate o texto das issues como entrada não confiável. Qualquer pessoa que pode escrever uma issue pode tentar guiar o Claude com instruções escondidas nela. A regra de acesso de escrita é a sua principal defesa, então não afrouxe allowed_non_write_users ou allowed_bots à toa. Prompt injection e segurança de agentes de código com IA aprofundam os riscos.

Controlando custo e permissões

Cada execução custa duas vezes: minutos do GitHub Actions no runner e tokens do Claude (ou uso da assinatura, se você usa um token OAuth). As alavancas que a documentação recomenda:

• Limite os turnos: claude_args: "--max-turns 5" impede que uma execução entre em loop.
• Defina um timeout de job com timeout-minutes no job.
• Use concurrency para uma rajada de pushes não iniciar cinco revisões do mesmo PR:

concurrency:
  group: claude-${{ github.event.pull_request.number || github.event.issue.number }}
  cancel-in-progress: true

• Restrinja as ferramentas. Dê ao --allowedTools só os comandos de que a tarefa precisa, e mantenha as permissions do job somente leitura em jobs de revisão, como no workflow acima.
• Mantenha o CLAUDE.md curto e específico. O Claude o carrega em toda execução, então um arquivo longo custa tokens toda vez. Como escrever o CLAUDE.md traz um modelo.
• Escreva pedidos específicos. “@claude fix the null check in parseDate” sai mais barato do que “@claude look at this”. Modelos de issue ajudam as pessoas a escrever pedidos melhores.

Armadilhas comuns

• O workflow não está na branch padrão. Workflows de issue_comment só rodam a partir da branch padrão, então faça primeiro o merge do PR de configuração.
• O CI não roda nos commits do Claude. O GitHub não inicia workflows para commits feitos com o GITHUB_TOKEN padrão. Remova github_token: ${{ secrets.GITHUB_TOKEN }} para a action usar o Claude GitHub App, ou passe um token do seu próprio app.
• A revisão não publica nada. Confira a linha --allowedTools "mcp__github_inline_comment__create_inline_comment" e veja se o PR é rascunho ou vem de um fork.
• O Claude diz que não pode rodar comandos. No modo automação nada é permitido por padrão. Adicione as ferramentas ao --allowedTools.

Quando rodar o Claude localmente

A action é boa em tarefas em que um gatilho fixo leva a um trabalho delimitado: responder uma pergunta, implementar uma issue pequena, revisar um diff, escrever um resumo diário. Ela não combina bem quando:

• Você quer guiar no caminho. Uma thread de comentários é lenta quando você precisa corrigir o agente a cada poucos minutos. Uma sessão local permite interromper, aprovar e redirecionar.
• A tarefa precisa do seu ambiente: um banco de dados rodando, um serviço local, secrets que não devem ir para o CI ou uma interface gráfica que você precisa ver.
• Você está explorando. Uma investigação longa queima minutos de runner e tokens sem ninguém olhando. Localmente, você vê quando ela sai do rumo e para.
• Você quer vários agentes ao mesmo tempo, cada um no próprio worktree, comparando abordagens.

Muitas equipes usam os dois. A action cuida das revisões de rotina e das issues pequenas, e o trabalho mais pesado acontece localmente, onde alguém acompanha.

O lado local com o AgentVera

O AgentVera é um app desktop que roda Claude Code, Codex, opencode e outras CLIs de agentes de código lado a lado, em terminais de verdade, usando as suas próprias instalações e logins. Ele cobre o lado local da divisão acima:

• Agentes em painéis e worktrees. Rode vários agentes Claude Code lado a lado, cada um no próprio git worktree, e veja diffs e commits no painel Git e GitHub.
• Revisão de código automática antes do push: quando um agente termina um turno, um modelo Claude que você escolhe revisa o que ele escreveu e lista os achados com severidade e arquivo:linha. Ele pode devolvê-los ao agente. Isso está no plano gratuito.
• Central de CI/CD lista execuções do GitHub Actions, GitLab CI e Jenkins em um só lugar. Os logs de uma execução que falhou vão para um agente novo com um clique.
• Automações (Pro e Team) podem iniciar um agente quando o CI fica vermelho ou quando um membro do repo comenta em um PR aberto. O agente trabalha no próprio worktree, e o AgentVera nunca faz push direto na branch padrão.

Como o AgentVera roda qualquer CLI de agente, a mesma configuração funciona para outros agentes também. Como usar o opencode mostra esse lado com um agente que não depende de provedor. Baixe o AgentVera para testar.

Conclusão

Para levar o Claude Code ao GitHub Actions, rode /install-github-app, faça o merge do PR que ele abre e escreva @claude em uma issue. Para revisões automáticas, adicione o workflow do plugin code-review com a linha --allowedTools. Depois mantenha tudo sob controle com --max-turns, timeouts de job, concurrency, permissões somente leitura onde der e secrets que nunca encostam no arquivo de workflow. Deixe o trabalho longo, exploratório e dependente de ambiente para uma sessão local, onde você pode acompanhar.