Claude Code en CI/CD: ejecución headless

Eso es el modo headless: Claude Code ejecuta un prompt, realiza las acciones necesarias, y termina. Sin interacción, sin confirmaciones, sin esperas.

El flag --print en detalle

La forma más directa de usar modo headless es el flag --print (o -p):

# Ejecutar un prompt y obtener resultado
claude -p "Analiza este código y lista los bugs potenciales"

# Con output en JSON para procesamiento automático
claude -p "Lista las funciones sin tests" --output-format json

# Limitar herramientas disponibles
claude -p "Revisa el código" --allowedTools "Read,Grep,Glob"

# Pipe desde stdin
echo "Revisa este PR" | claude -p

# Con modelo específico
claude -p "Genera tests" --model claude-sonnet-4-20250514

# Con max tokens de output
claude -p "Resume el changelog" --max-tokens 2000

El flag --print es esencial: sin él, Claude Code entra en modo interactivo y el pipeline se queda esperando input que nunca llega.

Opciones avanzadas del modo --print:

• --output-format json: devuelve la respuesta en JSON estructurado, ideal para parsear con jq o scripts
• --output-format stream-json: streaming de eventos JSON, útil para mostrar progreso en tiempo real
• --allowedTools: lista de herramientas permitidas separadas por comas
• --disallowedTools: lista negra de herramientas bloqueadas
• --timeout: tiempo máximo de ejecución en milisegundos
• --max-turns: número máximo de turnos de agente (limita loops)

GitHub Actions setup completo

Claude Code tiene una GitHub Action oficial que simplifica la integración. Aquí está el setup completo paso a paso:

Paso 1: Configurar el secret

Ve a tu repositorio en GitHub, Settings, Secrets and variables, Actions, y crea un secret llamado ANTHROPIC_API_KEY con tu clave de API de Anthropic.

Paso 2: Workflow básico de revisión

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

jobs:
 review:
 runs-on: ubuntu-latest
 permissions:
   contents: read
   pull-requests: write
 steps:
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0
 - uses: anthropics/claude-code-action@v1
   with:
     anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
     prompt: |
       Revisa este PR. Busca:
       1. Bugs potenciales
       2. Problemas de seguridad
       3. Mejoras de rendimiento
       Comenta directamente en el PR.

Paso 3: Workflow con CLAUDE.md del proyecto

# .github/workflows/claude-review-context.yml
name: Claude Code Review (con contexto)
on:
 pull_request:
 types: [opened, synchronize]

jobs:
 review:
 runs-on: ubuntu-latest
 permissions:
   contents: read
   pull-requests: write
 steps:
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0
 - uses: anthropics/claude-code-action@v1
   with:
     anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
     model: claude-sonnet-4-20250514
     allowed_tools: "Read,Grep,Glob"
     prompt: |
       Lee el archivo CLAUDE.md del proyecto para entender
       las convenciones. Revisa los cambios de este PR
       verificando que cumplen con las reglas del proyecto.
       Si encuentras violaciones, comenta en las líneas
       específicas del diff.

Esta configuración hace que Claude Code revise automáticamente cada PR nuevo. Los comentarios aparecen directamente en el PR de GitHub.

Revisión automática de PRs

La revisión de PRs es el caso de uso estrella de Claude Code en CI/CD. Aquí está cómo configurar una revisión profesional:

# .github/workflows/smart-review.yml
name: Smart PR Review
on:
 pull_request:
 types: [opened, synchronize]
 paths:
   - 'src/**'
   - 'tests/**'

jobs:
 review:
 runs-on: ubuntu-latest
 permissions:
   contents: read
   pull-requests: write
 steps:
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0

 - name: Get changed files
   id: changed
   run: |
     echo "files=$(git diff --name-only origin/main...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT

 - uses: anthropics/claude-code-action@v1
   with:
     anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
     model: claude-sonnet-4-20250514
     allowed_tools: "Read,Grep,Glob"
     prompt: |
       Revisa estos archivos cambiados: ${{ steps.changed.outputs.files }}

       Criterios de revisión:
       1. Seguridad: inyección SQL, XSS, secrets hardcodeados
       2. Performance: N+1 queries, loops innecesarios
       3. Mantenibilidad: funciones > 50 líneas, código duplicado
       4. Tests: funciones nuevas sin test correspondiente

       Para cada issue encontrado, indica:
       - Archivo y línea
       - Severidad (critical/warning/info)
       - Sugerencia de fix

       Si no hay issues, di "LGTM" con un breve resumen de
       qué hace el PR.

Tips para reviews efectivas:

• Usa paths para no revisar cambios en docs, configs o assets que no necesitan review de código
• Limita a Read,Grep,Glob para que Claude solo lea, nunca modifique
• Incluye criterios específicos de tu proyecto en el prompt
• Añade fetch-depth: 0 para que Claude tenga acceso al historial completo de git

Tareas programadas (cron)

Claude Code en modo headless es ideal para tareas recurrentes que se ejecutan en horarios definidos:

# .github/workflows/weekly-audit.yml
name: Weekly Code Audit
on:
 schedule:
   - cron: '0 9 * * 1' # Lunes a las 9:00 UTC

jobs:
 audit:
 runs-on: ubuntu-latest
 permissions:
   contents: read
   issues: write
 steps:
 - uses: actions/checkout@v4

 - name: Install Claude Code
   run: npm install -g @anthropic-ai/claude-code

 - name: Run audit
   env:
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
   run: |
     claude -p "Analiza el repositorio buscando:
     1. Dependencias desactualizadas con vulnerabilidades
     2. TODOs y FIXMEs sin resolver
     3. Código muerto (funciones no referenciadas)
     4. Archivos sin tests

     Genera un informe en markdown con prioridades." \
     --allowedTools "Read,Grep,Glob,Bash" \
     --timeout 600000 > audit-report.md

 - name: Create issue with report
   uses: actions/github-script@v7
   with:
     script: |
       const fs = require('fs');
       const report = fs.readFileSync('audit-report.md', 'utf8');
       github.rest.issues.create({
         owner: context.repo.owner,
         repo: context.repo.repo,
         title: `Weekly Audit - ${new Date().toISOString().split('T')[0]}`,
         body: report,
         labels: ['audit', 'automated']
       });

Otros casos de tareas programadas:

• Nightly docs update: regenerar documentación de API cada noche basándose en el código actual
• Weekly changelog: generar un resumen de cambios de la semana para el equipo
• Monthly security scan: auditoría de seguridad profunda una vez al mes
• Daily stale PR reminder: comentar en PRs que llevan más de 3 días sin actividad

Más casos de uso en CI/CD

Generación de changelog

Al mergear a main, Claude Code analiza los commits desde el último release y genera un changelog legible con las novedades, correcciones y breaking changes.

Migración automática de código

Cuándo actualizas una dependencia, Claude Code puede ajustar automáticamente el código afectado. Por ejemplo: migrar de una API deprecada a la nueva versión.

Generación de tests

Detecta funciones sin cobertura de tests y genera tests automáticamente. Puede ejecutarse como step del pipeline y fallar si la cobertura baja del umbral.

Documentación automática

Genera o actualiza docstrings, README, y documentación de API cada vez que el código cambia.

Commit message enforcement

Verifica que los mensajes de commit sigan Conventional Commits u otra convención del proyecto. Si no cumplen, Claude sugiere el mensaje correcto.

Seguridad en CI/CD

Ejecutar un agente IA en CI/CD requiere precauciones serias. Un agente mal configurado puede filtrar secrets, modificar código de producción, o acumular costes descontrolados.

Principio de mínimo privilegio

• Limita herramientas: usa --allowedTools para restringir qué puede hacer. Para un reviewer, solo necesita leer archivos, no ejecutar comandos
• API key como secret: nunca hardcodees la API key. Usa secrets de GitHub, Vault, o el sistema de secretos de tu CI
• Sin acceso a producción: el runner de CI no debe tener credenciales de producción accesibles
• Timeout: configura un timeout máximo. Si Claude Code se queda en un loop, el job debe cancelarse
• Logs: revisa los logs del job para asegurarte de que no se filtran secretos

Configuración segura por caso de uso

# Solo lectura (review): máxima seguridad
claude -p "Revisa el código del PR" \
 --allowedTools "Read,Grep,Glob" \
 --timeout 300000 \
 --max-turns 10

# Generación de código (con escritura limitada)
claude -p "Genera tests para src/auth/" \
 --allowedTools "Read,Grep,Glob,Write" \
 --disallowedTools "Bash" \
 --timeout 600000

# Análisis completo (con bash controlado)
claude -p "Ejecuta los tests y reporta fallos" \
 --allowedTools "Read,Grep,Glob,Bash" \
 --timeout 300000

Protección contra filtración de secrets

• Usa --output-format json y filtra la respuesta antes de mostrarla en logs públicos
• Configura GitHub Actions para que el job no imprima variables de entorno
• Nunca pases secrets como parte del prompt (podrían aparecer en la respuesta)
• Revisa periódicamente los logs de CI buscando patrones de API keys o tokens

Gestión de costes

Claude Code en CI/CD puede generar costes significativos si no lo controlas. Aquí está cómo mantenerlo económico:

Coste por operación típica:

• Review de PR (Sonnet): 10.000-50.000 tokens = 0,03-0,15 USD
• Generación de tests: 20.000-100.000 tokens = 0,06-0,30 USD
• Auditoría completa de repo: 100.000-500.000 tokens = 0,30-1,50 USD
• Generación de changelog: 5.000-20.000 tokens = 0,01-0,06 USD

Estrategias para reducir costes:

• Filtra por paths: no revises cambios en archivos que no lo necesitan (docs, assets, configs)
• Usa modelos apropiados: Sonnet para reviews, Haiku para clasificación y tareas simples
• Limita frecuencia: no revises cada push, solo PRs abiertos y sincronizados
• Establece max-turns: evita que Claude entre en loops costosos
• Cachea resultados: si un archivo no cambió desde la última review, no lo revises de nuevo
• Budget alerts: configura alertas en la consola de Anthropic cuando el gasto supere un umbral

Ejemplo de presupuesto mensual para un equipo de 5 devs:

• 50 PRs/semana con review automática: ~30 USD/mes
• Auditoría semanal de repo: ~6 USD/mes
• Changelog automático por release: ~2 USD/mes
• Total: ~38 USD/mes (menos que 1 hora de un dev senior)

Workflows reales de producción

Pipeline completo: lint + review + tests

# .github/workflows/quality.yml
name: Code Quality
on: [pull_request]

jobs:
 claude-review:
 runs-on: ubuntu-latest
 permissions:
   contents: read
   pull-requests: write
 steps:
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0

 - name: Install Claude Code
   run: npm install -g @anthropic-ai/claude-code

 - name: Review code
   env:
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
   run: |
     claude -p "Revisa los cambios en este PR.
     Genera un resumen de máximo 500 palabras con:
     - Qué cambia
     - Posibles problemas
     - Sugerencias de mejora" \
     --allowedTools "Read,Grep,Glob" \
     --timeout 300000 > review.md

 - name: Post review
   uses: actions/github-script@v7
   with:
     script: |
       const fs = require('fs');
       const review = fs.readFileSync('review.md', 'utf8');
       github.rest.issues.createComment({
         owner: context.repo.owner,
         repo: context.repo.repo,
         issue_number: context.issue.number,
         body: review
       });

Auto-fix de lint errors

# .github/workflows/auto-fix.yml
name: Auto Fix
on:
 pull_request:
 types: [opened]

jobs:
 fix:
 runs-on: ubuntu-latest
 permissions:
   contents: write
   pull-requests: write
 steps:
 - uses: actions/checkout@v4
   with:
     ref: ${{ github.head_ref }}
     fetch-depth: 0

 - name: Install deps
   run: npm ci

 - name: Run linter
   id: lint
   run: npm run lint 2>&1 | tee lint-output.txt || true

 - name: Fix with Claude Code
   if: steps.lint.outcome == 'failure'
   env:
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
   run: |
     claude -p "Lee lint-output.txt y corrige todos los
     errores de lint en los archivos afectados. No cambies
     la lógica, solo el formato y estilo." \
     --allowedTools "Read,Write,Grep,Glob" \
     --timeout 300000

 - name: Commit fixes
   run: |
     git config user.name "Claude Code Bot"
     git config user.email "bot@example.com"
     git add -A
     git diff --staged --quiet || git commit -m "fix: auto-fix lint errors"
     git push

Script para generar documentación

#!/bin/bash
# scripts/generate-docs.sh
claude -p "Genera documentación actualizada para todas las
funciones públicas en src/. Formato: JSDoc.
Solo modifica archivos que necesiten actualización." \
 --allowedTools "Read,Grep,Glob,Write" \
 --timeout 600000

Siguiente paso

El modo headless convierte a Claude Code en una pieza más de tu infraestructura. Combínalo con subagents para reviews paralelos, con worktrees para cambios aislados, y con MCP GitHub para automatización completa del repositorio.

Empieza con un workflow simple (review de PRs), mide el impacto en calidad del código y tiempo de revisión, y expande gradualmente. La mayoría de equipos ven ROI positivo en la primera semana.

Preguntas frecuentes

¿Qué es el modo headless de Claude Code?

El modo headless permite ejecutar Claude Code sin interfaz interactiva, ideal para pipelines CI/CD. Se activa con el flag --print o -p, que ejecuta un prompt y devuelve el resultado sin esperar input del usuario. Es la forma de integrar Claude Code como un step más en tu pipeline de automatización.

¿Se puede usar Claude Code en GitHub Actions?

Sí. Claude Code ofrece una GitHub Action oficial (anthropics/claude-code-action@v1) que puedes integrar en tus workflows. Soporta revisión automática de PRs, generación de código, y cualquier tarea que Claude Code pueda hacer en modo headless. Solo necesitas configurar tu API key como secret del repositorio.

¿Cuánto cuesta ejecutar Claude Code en CI/CD?

El coste depende del volumen de PRs y la complejidad de las tareas. Una revisión típica de PR consume 10.000-50.000 tokens (0,03-0,15 USD con Sonnet). Para un equipo con 50 PRs/semana, el coste ronda 10-30 USD/mes. Significativamente menos que el tiempo de un developer senior haciendo reviews manuales.

¿Puedo usar Claude Code para tareas programadas?

Sí. Combina el flag --print con GitHub Actions schedule (cron) o el cron del sistema. Casos comunes incluyen: generar reportes semanales de calidad de código, actualizar documentación cada noche, hacer auditorías de seguridad periódicas, o limpiar PRs abandonados.

¿Es seguro para producción?

Sí, siempre que sigas las mejores prácticas: limita herramientas con --allowedTools, configura timeouts, nunca expongas secrets en prompts, y usa el principio de mínimo privilegio. El modo headless respeta las mismas restricciones de seguridad que el modo interactivo.