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

URL: https://agentvera.dev/pt/blog/claude-code-github-actions/ · Publicado: 2026-10-27

Configure o Claude Code no GitHub Actions: /install-github-app ou setup manual, menções @claude, revisão automática de PR, secrets, custos e permissões.

**Resumo:**

- Rode /install-github-app no Claude Code para instalar o Claude GitHub App, salvar sua chave como secret e abrir um PR com os arquivos de workflow, ou faça os mesmos três passos à mão.
- Sem o input prompt, a action espera por @claude em comentários de issues e PRs; com um prompt, ela roda sozinha, e é assim que se monta uma revisão automática de PR ou um relatório diário.
- Cada execução custa minutos do Actions mais tokens, então limite com --max-turns em claude_args, timeouts de job, concurrency e um --allowedTools enxuto; deixe o trabalho exploratório local.

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](/pt/blog/auto-fix-ci-failures-with-ai/ "Corrigir falhas de CI 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:

```text
/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:

```yaml
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:

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

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

```text
@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`:

```yaml
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](/pt/blog/ai-code-review/ "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:

```yaml
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:

| Input | O que faz |
| --- | --- |
| `prompt` | Texto da tarefa ou um comando de barra. Se definido, a action roda no modo automação. |
| `claude_args` | Quaisquer flags da CLI do Claude Code, como `--max-turns`, `--model`, `--allowedTools`, `--mcp-config`, `--append-system-prompt`. |
| `anthropic_api_key` | Chave de API para a API do Claude. |
| `claude_code_oauth_token` | Token de `claude setup-token`, como alternativa à chave de API. |
| `github_token` | Seu próprio token, se você não quer que o Claude GitHub App atue. |
| `trigger_phrase` | A palavra de menção. Padrão `@claude`. |
| `settings` | Configurações do Claude Code em JSON ou caminho de arquivo, para permissões, hooks e ambiente. |
| `plugin_marketplaces`, `plugins` | Carregam plugins como o `code-review`. |
| `use_bedrock`, `use_vertex`, `use_foundry` | Rodam por um provedor de nuvem em vez da API do Claude. |

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](/pt/glossary/prompt-injection/ "Prompt injection") e [segurança de agentes de código com IA](/pt/blog/ai-coding-agent-security/ "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:

```yaml
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](/pt/blog/claude-md-agents-md/ "Como escrever CLAUDE.md e AGENTS.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](/pt/glossary/git-worktree/ "O que é um git worktree"), e veja diffs e commits no painel [Git e GitHub](/pt/features/git-and-github/ "Git e GitHub").
- **[Revisão de código automática](/pt/features/code-review/ "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](/pt/features/ci-cd-center/ "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](/pt/features/automations/ "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](/pt/blog/how-to-use-opencode/ "Como usar o opencode") mostra esse lado com um agente que não depende de provedor. [Baixe o AgentVera](/pt/download/ "Baixar 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.

## Perguntas frequentes

**O Claude Code no GitHub Actions é gratuito?** Adicionar a action não custa nada, mas cada execução usa minutos do GitHub Actions no seu runner e uso do Claude. Com uma chave de API você paga por token; com um CLAUDE_CODE_OAUTH_TOKEN gerado por claude setup-token, as execuções contam na sua assinatura Pro, Max, Team ou Enterprise.

**Por que nada acontece quando escrevo @claude?** Confira se o comentário tem @claude como palavra inteira (não /claude nem @claude-bot), se você tem acesso de escrita ao repositório, se o Claude GitHub App está instalado no repo, se o arquivo de workflow está na branch padrão e se o secret da chave de API ou do token OAuth existe.

**O Claude consegue revisar pull requests automaticamente?** Sim. Um workflow disparado em pull_request com um prompt que roda o plugin code-review revisa cada PR novo ou atualizado e publica comentários inline. PRs em rascunho, fechados ou triviais são pulados. A Anthropic também vende um produto gerenciado separado, o Code Review, que não precisa de workflow.

**Devo usar uma chave de API ou um token OAuth?** Em um repositório pessoal, os dois funcionam. Em uma organização, a documentação recomenda uma chave de API do Claude Console salva como secret da organização, porque um token OAuth fica preso à assinatura de uma pessoa e para de funcionar se ela sair.

**Por que meus checks de CI não rodam nos commits que o Claude faz push?** O GitHub não inicia workflows para commits feitos com o GITHUB_TOKEN padrão. Tire github_token: ${{ secrets.GITHUB_TOKEN }} dos inputs da action para ela usar o Claude GitHub App, ou passe um token do seu próprio GitHub App.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/