Modulo 6.7 - Pipelines CI/CD com Claude Headless

🚀 Claude em CI/CD (Automated Code Quality)

O Claude Code nao e apenas uma ferramenta interativa. Com o modo headless (claude -p), ele roda sem interface grafica, aceitando prompts via stdin e retornando resultados via stdout. Isso abre a porta para integra-lo diretamente em pipelines de CI/CD.

🎯 Conceito Principal

O modo headless transforma o Claude Code num processo automatizavel. Em vez de digitar comandos interativamente, voce passa um prompt via flag -p e recebe a resposta diretamente. Perfeito para automacao.

• Sem interacao: claude -p "Analise este codigo" retorna o resultado direto, sem esperar input
• Saida formatada: Use --output-format json para obter resultados estruturados parseados facilmente
• Integravel: Funciona em qualquer CI - GitHub Actions, GitLab CI, Jenkins, CircleCI, etc.
• Casos de uso: Code review automatico, verificacao de padroes, geracao de docs, validacao pre-deploy

💡 Dica Pratica

Teste o modo headless localmente antes de colocar no CI. Rode claude -p "Revise o arquivo src/main.ts e aponte problemas de seguranca" e veja a saida. Se funcionar no terminal, vai funcionar no CI.

🛠 GitHub Actions com claude -p

GitHub Actions e o ambiente mais comum para integrar o Claude Code em pipelines. A configuracao e surpreendentemente simples: instale o Claude Code no runner, configure a API key e rode comandos com claude -p.

🎯 Conceito Principal

A estrutura basica de uma GitHub Action com Claude:

# .github/workflows/claude-review.yml
name: Claude Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: claude -p "Revise os arquivos alterados neste PR"

• Trigger em PR: A action roda automaticamente quando um PR e aberto ou atualizado
• API Key segura: Use GitHub Secrets para armazenar a chave - nunca coloque no codigo
• Custo controlado: Cada execucao consome tokens da sua API key. Monitore com alertas de billing

💡 Dica Pratica

Comece com uma action simples que so roda em PRs para a branch main. Nao coloque em todos os pushes - isso consome muitos tokens. Use on: pull_request: branches: [main] para limitar o escopo e manter o custo sob controle.

🔒 --allowedTools para Seguranca

Em ambientes CI/CD, seguranca e fundamental. Voce nao quer que o Claude execute comandos arbitrarios no seu runner. A flag --allowedTools restringe quais ferramentas o Claude pode usar, criando um sandbox seguro.

🎯 Conceito Principal

O --allowedTools funciona como uma whitelist de permissoes. Somente as ferramentas listadas estarao disponiveis para o Claude naquela execucao. Tudo mais e bloqueado automaticamente.

# Somente leitura - seguro para code review
claude -p "Revise este codigo" \
  --allowedTools Read,Grep,Glob

# Leitura + escrita limitada
claude -p "Corrija os bugs encontrados" \
  --allowedTools Read,Write,Edit,Grep,Glob

# Nenhuma ferramenta - so analise textual
claude -p "Analise este diff: $(git diff)" \
  --allowedTools ""

• Read-only para reviews: Use Read,Grep,Glob quando o Claude so precisa analisar, nao modificar
• Sem Bash: Nunca inclua Bash na whitelist do CI a menos que seja absolutamente necessario e controlado
• Principio do menor privilegio: De ao Claude apenas as ferramentas que ele precisa para aquela tarefa especifica

💡 Dica Pratica

Para code review automatico, a combinacao --allowedTools Read,Grep,Glob e o padrao ouro. O Claude consegue ler e analisar todo o codigo sem risco de modificar nada. Comece sempre com o minimo e so adicione mais ferramentas se a tarefa realmente exigir.

🔍 Code Review Automatico em PRs

O caso de uso mais poderoso do Claude em CI/CD e o code review automatico. A cada PR aberto, o Claude analisa as mudancas, identifica bugs potenciais, sugere melhorias e posta um comentario detalhado - tudo automaticamente, antes de qualquer humano olhar.

🎯 Conceito Principal

Um pipeline de code review automatico com Claude envolve:

• Capturar o diff: Use git diff origin/main...HEAD para obter apenas as mudancas do PR
• Prompt estruturado: Passe o diff com instrucoes claras sobre o que analisar (seguranca, performance, padroes)
• Postar como comentario: Use a API do GitHub (gh pr comment) para adicionar o review como comentario no PR
• Status check: Configure como check obrigatorio para que PRs nao sejam mergeados sem review do Claude

# Exemplo completo de step de review
- name: Claude Review
  run: |
    REVIEW=$(claude -p "Analise este diff e reporte bugs, problemas de seguranca e sugestoes de melhoria. Seja conciso. $(git diff origin/main...HEAD)" --allowedTools Read,Grep,Glob)
    gh pr comment ${{ github.event.pull_request.number }} --body "$REVIEW"

💡 Dica Pratica

O segredo de um bom review automatico e o prompt bem estruturado. Inclua instrucoes sobre o que priorizar: "Foque em: 1) Bugs criticos, 2) Vulnerabilidades de seguranca, 3) Performance. Ignore: formatacao, nomes de variaveis." Quanto mais especifico o prompt, mais util o review.

🚀 Deployment Checks com Claude

Alem de code review, o Claude pode atuar como validador pre-deploy. Antes de cada deploy, ele analisa o codigo, verifica configuracoes, valida variaveis de ambiente e confirma que tudo esta pronto para ir para producao.

🎯 Conceito Principal

Deployment checks com Claude podem verificar:

• Variaveis de ambiente: Todas as envs necessarias estao definidas? Alguma esta com valor padrao inseguro?
• Migrations pendentes: Ha migrations de banco de dados que precisam rodar antes do deploy?
• Breaking changes: As mudancas na API sao retrocompativeis? Algum endpoint foi removido?
• Seguranca: Ha secrets expostos, dependencias vulneraveis ou configuracoes inseguras?

# Pre-deploy check
claude -p "Verifique se este projeto esta pronto para deploy em producao. Cheque: 1) .env.example vs variaveis usadas, 2) Migrations pendentes, 3) Secrets expostos no codigo, 4) Breaking changes na API. Retorne PASS ou FAIL com justificativa." \
--allowedTools Read,Grep,Glob

💡 Dica Pratica

Configure o deployment check como blocking step no pipeline. Se o Claude retornar FAIL, o deploy nao acontece. Isso funciona como uma camada extra de seguranca - mesmo que os testes passem, o Claude pode pegar problemas que testes automatizados nao cobrem, como configuracoes incorretas ou padroes inseguros.

📜 Pipeline Completo de Exemplo (Full YAML)

Vamos juntar tudo num pipeline completo que voce pode copiar e adaptar. Este YAML inclui code review automatico em PRs, validacao pre-deploy e notificacao dos resultados - tudo usando Claude headless com seguranca.

🎯 Conceito Principal

Pipeline completo com 3 jobs: review, quality check e deploy validation:

# .github/workflows/claude-pipeline.yml
name: Claude CI/CD Pipeline
on:
  pull_request:
    branches: [main]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm i -g @anthropic-ai/claude-code
      - name: Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          REVIEW=$(claude -p "Revise as mudancas deste PR. Foque em bugs, seguranca e performance." --allowedTools Read,Grep,Glob)
          gh pr comment $PR_NUMBER --body "$REVIEW"
        env:
          PR_NUMBER: ${{ github.event.pull_request.number }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

• fetch-depth: 0: Necessario para ter acesso ao historico completo de commits no diff
• Dois secrets: ANTHROPIC_API_KEY para o Claude e GITHUB_TOKEN para postar comentarios
• Extensivel: Adicione mais jobs (quality-check, deploy-validation) seguindo o mesmo padrao

💡 Dica Pratica

Copie este YAML como ponto de partida e adapte para seu projeto. As principais customizacoes sao: o prompt de review (adapte ao estilo do seu time) e as allowedTools (ajuste conforme o nivel de permissao desejado).

Dica de custo: adicione --max-turns 1 para limitar o Claude a uma unica resposta, evitando loops de ferramentas que consomem tokens excessivamente.

✍

Exercicio Pratico

Criar GitHub Action com claude -p e --allowedTools

Neste exercicio, voce vai configurar um pipeline real de CI/CD que usa o Claude para code review automatico em pull requests.

Passo 1: Criar o arquivo de workflow

Crie a estrutura de diretorio e o arquivo YAML:

$ mkdir -p .github/workflows
$ claude "Crie um workflow GitHub Actions em .github/workflows/claude-review.yml que faca code review automatico com claude -p e --allowedTools Read,Grep,Glob"

Passo 2: Configurar o secret

Adicione sua API key como secret no repositorio:

$ gh secret set ANTHROPIC_API_KEY

O comando vai pedir o valor da chave interativamente.

Passo 3: Testar com um PR

Crie um PR de teste para validar o pipeline:

$ git checkout -b test/claude-ci
$ git add .github/workflows/claude-review.yml
$ git commit -m "Add Claude CI review"
$ gh pr create --title "Test Claude CI" --body "Testing automated review"

Checklist de Conclusao:

☐ Criou o arquivo .github/workflows/claude-review.yml

☐ Configurou ANTHROPIC_API_KEY como GitHub Secret

☐ Usou --allowedTools para restringir permissoes

☐ Testou com um PR real e verificou o comentario do Claude

📋 Resumo do Modulo

✓

Claude headless com -p - Modo sem interface que aceita prompts via flag e retorna resultado via stdout.

✓

GitHub Actions integracao nativa - Instale no runner, configure API key como secret e rode com claude -p.

✓

--allowedTools para seguranca - Whitelist de ferramentas que restringe o que o Claude pode fazer no CI.

✓

Code review automatico em PRs - Analise automatica de bugs, seguranca e performance a cada pull request.

✓

Pipeline completo copiavel - YAML pronto para adaptar com review, quality check e deploy validation.

Proximo Modulo:

6.8 - Claude Cowork e Desktop Agent (2026)

← Modulo Anterior Voltar para Trilha Proximo Modulo →