Pular para o conteudo
AI Coding Flow
Voltar aos artigos
claude-codegithub-actionsci-cdtutorial

Claude Code + GitHub Actions: Setup Completo e Casos de Uso

Configure o Claude Code para rodar dentro do GitHub Actions. Setup passo a passo, workflows prontos para copiar e casos de uso avançados para automatizar code review, triagem de issues e mais.

9 min de leitura

Claude Code + GitHub Actions: Setup Completo e Casos de Uso

No terminal, Claude Code funciona como um assistente interativo. A conversa acontece em tempo real — pergunta, resposta, edição, commit. Mas código não vive só na sua máquina. Ele vive no GitHub.

E se Claude Code pudesse rodar lá também? Revisando PRs automaticamente, respondendo quando alguém menciona @claude em uma issue, ou até tentando corrigir falhas de CI sozinho?

É exatamente isso que o claude-code-action faz. A Action oficial da Anthropic coloca Claude Code dentro do GitHub Actions — o mesmo modelo, as mesmas capacidades, rodando em resposta a eventos do repositório.

O que é o claude-code-action

O claude-code-action é a GitHub Action oficial mantida pela Anthropic. Ele permite que Claude Code execute dentro dos runners do GitHub Actions, com acesso ao código do repositório e capacidade de interagir via comentários.

Na prática, funciona assim: um evento acontece no GitHub (PR aberto, comentário criado, issue aberta), o workflow é disparado, e Claude Code analisa o contexto e responde.

O modelo é o mesmo que roda no terminal. O CLAUDE.md do repositório é respeitado. A diferença é o contexto de execução — em vez de uma conversa interativa, Claude recebe a tarefa, executa e responde.

Para entender a hierarquia:

  • Workflow (arquivo .yml) define quando e como Claude roda
  • Action (claude-code-action) é o que executa
  • Plugin (opcional) define um comportamento específico — como code review estruturado

Setup passo a passo

O setup envolve três etapas: instalar o GitHub App, configurar autenticação e criar os arquivos de workflow.

Pré-requisitos

  • Um repositório no GitHub
  • Claude Code com assinatura ativa ou uma API key da Anthropic

Passo 1 — Instalar o GitHub App do Claude

Acesse github.com/apps/claude e instale o app no seu repositório (ou em toda a organização).

O app precisa destas permissões:

  • Contents — Read & Write
  • Issues — Read & Write
  • Pull Requests — Read & Write

Sem o app instalado, Claude não consegue postar comentários nem interagir com PRs e issues.

Passo 2 — Configurar autenticação

Existem duas formas de autenticar. A escolha depende de como você quer pagar pelo uso.

Opção A: API Key (pagamento por token)

Gere uma chave na Console da Anthropic e adicione como secret no repositório:

# Settings → Secrets and variables → Actions → New repository secret
# Nome: ANTHROPIC_API_KEY
# Valor: sk-ant-...

Opção B: OAuth Token (usa cota da assinatura)

Se você tem uma assinatura Pro ou Max do Claude, pode usar a cota existente em vez de pagar por token. Gere o token no terminal:

claude setup-token

Copie o token gerado e adicione como secret:

# Settings → Secrets and variables → Actions → New repository secret
# Nome: CLAUDE_CODE_OAUTH_TOKEN
# Valor: (token gerado pelo comando acima)

Passo 3 — Criar os workflows

Crie a pasta .github/workflows/ na raiz do repositório (se ainda não existir) e adicione os arquivos abaixo.

Workflow 1: Assistente interativo (menções @claude)

Este workflow faz Claude responder sempre que alguém mencionar @claude em comentários de PRs, issues ou code reviews.

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    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:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Agora, em qualquer PR ou issue, basta escrever algo como @claude explique o que essa função faz e Claude responde diretamente no GitHub.

Workflow 2: Code review automático em PRs

Este workflow dispara automaticamente quando um PR é aberto ou atualizado. Ele usa o plugin oficial de code review para uma análise estruturada.

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  claude-review:
    if: github.actor != 'dependabot[bot]'
    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:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
          plugins: 'code-review@claude-code-plugins'
          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'

Note o if: github.actor != 'dependabot[bot]' — isso evita que Claude gaste tokens revisando PRs automáticos do Dependabot.

Billing: API Key vs OAuth Token

A forma de autenticação determina como o uso é cobrado. Essa tabela resume as diferenças:

Aspecto API Key OAuth Token
Cobrança Por token consumido Cota da assinatura
Custo Variável, pode ser alto em volume Mensal previsível
Ideal para Times, volume alto Devs solo, assinantes Pro/Max
Configuração Console Anthropic → API Keys claude setup-token no terminal

Um detalhe importante: se ambos ANTHROPIC_API_KEY e OAuth estiverem configurados no mesmo repositório, a API key tem prioridade. Isso significa cobrança por token mesmo tendo OAuth configurado. Para usar a cota da assinatura, remova a API key dos secrets.

Casos de uso avançados

Os dois workflows acima cobrem os cenários mais comuns. Mas dá para ir além.

Triagem automática de issues

Claude pode classificar issues novas, sugerir labels e adicionar um comentário inicial com análise.

name: Issue Triage
on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Analyze this new issue. Classify it as bug, feature, question, or docs.
            Suggest appropriate labels. If it's a bug, try to identify
            which files might be involved based on the description.

Review focado em segurança

Para repositórios com rotas de autenticação ou APIs sensíveis, é possível configurar um review com foco em segurança.

- uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    prompt: |
      Review this PR with a security-first mindset aligned with OWASP Top 10.
      Focus on: input validation, authentication flows, SQL injection,
      XSS vectors, secrets exposure, and insecure dependencies.
      Flag any finding as [CRITICAL], [HIGH], [MEDIUM], or [LOW].

Manutenção programada

Um workflow agendado que roda semanalmente para verificar dependências desatualizadas e TODOs esquecidos no código.

name: Weekly Maintenance
on:
  schedule:
    - cron: '0 9 * * 1'  # Segunda-feira às 9h UTC

jobs:
  maintenance:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Run a weekly maintenance check:
            1. List any TODO/FIXME/HACK comments with file locations
            2. Check for potential security issues in dependencies
            3. Identify dead code or unused exports
            Create a GitHub issue summarizing the findings.

Auto-fix de falhas no CI

Quando o CI falha, Claude pode analisar o erro e criar um branch com a correção.

name: CI Auto-Fix
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  auto-fix:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            The CI workflow failed. Analyze the failure logs,
            identify the root cause, and attempt to fix it.
            Push the fix to a new branch named fix/ci-<short-description>.

Referência de configuração

A tabela abaixo lista os parâmetros principais do claude-code-action:

Parâmetro Descrição
claude_code_oauth_token Token OAuth (cobrança via assinatura)
anthropic_api_key API key (cobrança por token)
prompt Instruções customizadas para a tarefa
claude_args Argumentos do CLI (--model, --max-turns, --allowedTools)
trigger_phrase Frase de ativação customizada (padrão: @claude)
allowed_bots Nomes de bots autorizados a disparar o workflow
track_progress Exibir checkboxes de progresso no comentário
use_commit_signing Assinar commits via GitHub API
plugin_marketplaces URLs de repositórios de plugins
plugins Plugins a carregar (ex: code-review@claude-code-plugins)

Para a lista completa de parâmetros, consulte a documentação oficial de configuração.

CLI vs Action vs Web

Claude Code pode rodar em três contextos diferentes. Cada um tem seu lugar.

CLI (Terminal) Action (GitHub) Web (claude.ai/code)
Execução Sua máquina Runners do GitHub VMs da Anthropic
Disparo Comando manual Eventos do GitHub Navegador ou celular
Interatividade Conversa completa Dispara e executa Interativo, direcionável
Contexto Memories, CLAUDE.md, conversa Repo + CLAUDE.md Repo + CLAUDE.md + sessão
Custo de compute Nenhum Minutos do GitHub Actions Incluso na assinatura
Custo do modelo Assinatura API tokens ou OAuth Assinatura
Ideal para Desenvolvimento diário CI/CD automatizado Tarefas remotas, mobile

A combinação mais comum: CLI no dia a dia, Action para automação no repositório. A versão Web é útil quando você quer delegar uma tarefa mais longa e acompanhar pelo celular.

Dicas e armadilhas

PRs do Dependabot. Sempre exclua com if: github.actor != 'dependabot[bot]'. Sem isso, cada bump de versão consome tokens desnecessariamente.

Override de modelo. Para tarefas que exigem mais raciocínio, force um modelo específico:

claude_args: '--model claude-opus-4-6'

Timeout. Defina um limite no job para evitar execuções travadas:

jobs:
  claude:
    timeout-minutes: 15

Concorrência. Evite execuções paralelas na mesma issue ou PR:

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

Limitações para manter em mente:

  • Claude não pode modificar arquivos de workflow (.github/workflows/) — restrição de segurança do GitHub
  • Claude não cria PRs diretamente — ele faz push para um branch e fornece o link
  • Apenas usuários com permissão de escrita no repositório podem acionar @claude

Referências