Referencias Oficiales: GitHub Actions · Overview · SDK
Ruta del currículo
- CLAUDE.md Mastery — memoria del repo y reglas
- Effective Prompting — framing de tareas y restricciones
- MCP Power Tools — herramientas y contexto vivo
- Multi-Agent Workflows — delegación y ejecución en paralelo
- Hooks Automation — enforcement local del flujo de trabajo
- GitHub Actions Workflows — automatización repetida de equipo ← Estás aquí
- Claude Loop Seguro del Primer Día — onboarding seguro para principiantes
- Playbook Claude para Refactor de Tamaño Medio — disciplina intermedia por lanes
- Gobernanza de Cambios de Alto Riesgo con Claude — control avanzado de release
- Manual Operativo de Claude — ritmo operativo a escala de equipo
Documentación oficial usada en esta guía
- Claude Code dentro de GitHub Actions — GitHub Actions
- Superficie de automatización y SDK — SDK
- Cómo encaja en workflows más amplios — Overview
Dónde Encaja Claude Code en Automatización de Equipo
Claude Code brilla en desarrollo interactivo, pero Anthropic también soporta su uso en GitHub Actions y flujos automatizados.
Buenos usos:
- review de PRs con checklist
- triage de issues
- resúmenes de checks fallidos
- borradores de release notes
- tareas repetidas disparadas por labels o comentarios
Buenas Tareas para Automatizar
Funciona bien cuando el trabajo es:
- acotado
- revisable
- asociado a un PR o issue real
- útil aunque la decisión final siga siendo humana
Malas Tareas para Automatizar
No fuerces Claude Code en trabajos que requieren invención amplia, acceso muy sensible o cambios de alto riesgo sin review.
Patrón Práctico
- trigger por PR, issue o label
- contexto claro del repo
- Claude ejecuta un trabajo estrecho
- salida como comentario, resumen o artifact
- humano sigue en el camino del merge
Configuración Básica
Registrar la clave de API
Ve a Settings → Secrets and variables → Actions en tu repositorio y añade ANTHROPIC_API_KEY. Sin esta clave, el workflow no podrá ejecutarse.
Usar la acción oficial
Anthropic ofrece anthropics/claude-code-action@v1 como la forma oficial de ejecutar Claude Code dentro de GitHub Actions. No necesitas instalar ni configurar nada extra.
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "Describe aquí la tarea que quieres que realice Claude."Si tu repositorio tiene un archivo CLAUDE.md en la raíz, la acción lo lee automáticamente para entender las convenciones de código y la arquitectura del proyecto. Es una de las formas más sencillas de mejorar la calidad de la automatización.
Workflow de Revisión Automática de PRs
Claude publica comentarios de revisión automáticamente cada vez que se abre un PR o se añaden nuevos commits.
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Revisa este PR teniendo en cuenta:
- Vulnerabilidades de seguridad
- Problemas de rendimiento
- Consistencia del estilo de código
Proporciona feedback concreto y accionable como comentarios en el PR.pull-requests: write es obligatorio en permissions. Sin él, la acción no puede publicar comentarios.
Los prompts específicos producen mejores resultados. "Revisa este código" es demasiado vago. "Concéntrate en riesgos de migración y gestión de errores faltante" le da a Claude un objetivo claro con resultados medibles.
Workflow de Triage de Issues
Cuando se registra un nuevo issue, Claude lo lee y automáticamente le asigna etiquetas y publica una respuesta inicial.
name: Issue Triage
on:
issues:
types: [opened]
jobs:
triage:
runs-on: ubuntu-latest
permissions:
contents: read
issues: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Analiza este issue recién registrado:
Título: ${{ github.event.issue.title }}
Contenido: ${{ github.event.issue.body }}
Por favor realiza lo siguiente:
1. Clasifícalo como reporte de bug, solicitud de funcionalidad o pregunta
2. Si faltan pasos de reproducción o contexto, publica un comentario solicitándolos
3. Sugiere etiquetas apropiadas (bug, enhancement, question, needs-info)
4. Evalúa la urgencia (critical, high, medium, low)
Publica un resumen del triage como comentario en el issue.El triage de issues es especialmente útil en proyectos de código abierto donde el volumen de issues entrantes hace que la primera respuesta manual sea lenta e inconsistente.
Workflow de Análisis de Fallos
Cuando un workflow de CI falla, Claude lee los logs, analiza la causa raíz y publica un comentario resumen en el PR relacionado.
name: Analyze Failure
on:
workflow_run:
workflows: ["CI"]
types: [completed]
jobs:
analyze:
if: ${{ github.event.workflow_run.conclusion == 'failure' }}
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
actions: read
steps:
- name: Obtener logs del workflow
id: logs
uses: actions/github-script@v7
with:
script: |
const logs = await github.rest.actions.downloadWorkflowRunLogs({
owner: context.repo.owner,
repo: context.repo.repo,
run_id: context.payload.workflow_run.id,
});
return Buffer.from(logs.data).toString('utf-8').slice(0, 8000);
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Aquí están los logs del workflow de CI que ha fallado:
${{ steps.logs.outputs.result }}
Por favor analiza:
1. Qué falló primero
2. La causa raíz más probable
3. Próximos pasos concretos para solucionarlo
Publica el análisis como comentario en el PR relacionado.Pasar los logs completos consume muchos tokens. Recortarlos a la parte relevante con slice(0, 8000) o similar mantiene los costes razonables sin perder la información importante.
Seguridad y Permisos
Principio de mínimos privilegios
Otorga solo los permisos que el workflow realmente necesita. Si solo publica comentarios, pull-requests: write es suficiente. contents: write solo es necesario cuando la acción modifica archivos directamente.
permissions:
contents: read # leer código fuente
pull-requests: write # publicar comentarios en PRs
issues: write # publicar comentarios y aplicar etiquetas en issues
# actions: read # leer logs de workflows (solo cuando sea necesario)Gestión de secretos
- Guarda siempre
ANTHROPIC_API_KEYen GitHub Secrets. Nunca la pongas directamente en los archivos de workflow. - Usa GitHub Environments si necesitas claves separadas por entorno.
- Rota las claves de forma regular.
Límite de peticiones y consideraciones de coste
Cada ejecución de GitHub Actions que llama a la API de Claude consume créditos de la API de Anthropic. Algunos puntos a tener en cuenta:
- En repositorios grandes, los PRs pueden abrirse con mucha frecuencia. Asociar un workflow de revisión a cada PR puede acumular costes rápidamente.
- Usa filtros
pathspara ejecutar el workflow solo cuando cambien archivos relevantes. - Usa
concurrencypara evitar ejecuciones duplicadas en el mismo PR.
on:
pull_request:
paths:
- "src/**"
- "tests/**"
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: trueBuenas Prácticas
1. Empieza con acciones de solo lectura
Comienza con comentarios, resúmenes y borradores antes de intentar acciones de escritura o auto-merge. Construye confianza en la calidad del output antes de ampliar el alcance.
2. Mantén a las personas en el camino del merge
Aunque los comentarios de Claude sean de alta calidad, la decisión final de hacer merge debe quedarse con un revisor humano. El comportamiento de auto-merge es tentador pero hace que el análisis de causas raíz sea mucho más difícil cuando algo sale mal.
3. Establece límites de tiempo
Evita workflows que se ejecuten indefinidamente usando timeout-minutes.
jobs:
review:
runs-on: ubuntu-latest
timeout-minutes: 104. Usa CLAUDE.md para dar contexto del repo a la acción
Pon tus convenciones de código, decisiones de arquitectura y checklists de revisión en CLAUDE.md en la raíz del repositorio. La acción lo recoge automáticamente y produce resultados significativamente mejores cuando entiende el contexto del proyecto.
Ejemplo de contenido de CLAUDE.md para automatización:
## Reglas de Código
- TypeScript en modo strict obligatorio
- Todos los endpoints de API deben tener gestión de errores
- Las nuevas funcionalidades requieren tests
## Checklist de Revisión
- Verificar vectores de inyección SQL
- Comprobar autenticación y autorización
- Validar todos los inputs externos5. Escribe prompts específicos
Los prompts vagos producen resultados vagos. Sé explícito sobre qué debe verificar Claude y en qué formato debe presentar el output. Trata el prompt como una descripción de puesto para un revisor cuidadoso.
Complementar con Guías del Repositorio
La automatización mejora cuando el repo ya tiene instrucciones sólidas.
Fuentes de guía útiles:
CLAUDE.mdpara reglas de código y arquitectura- plantillas de issues para dar forma a las tareas
- checklists de revisión para política estable
- hooks para enforcement local durante el trabajo interactivo
Si las guías de tu repo son débiles, la automatización de GitHub solo escalará la ambigüedad más rápido.
Automatización Avanzada con el SDK
Además de la acción oficial, puedes usar el CLI de Claude Code directamente en CI para tener un control más preciso.
name: Claude Code CI Tasks
on:
push:
branches: [main]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Security Audit
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude -p "Audit the files changed in this push for security vulnerabilities. \
Focus on: SQL injection, XSS, auth bypasses. \
Output a markdown summary." \
--output-format text > security-report.md
- name: Upload Report
uses: actions/upload-artifact@v4
with:
name: security-report
path: security-report.md- El CLI te da más control que la acción: formatos de salida personalizados, piping y encadenamiento.
- Usa
--model haikupara análisis masivos con coste reducido. - Combínalo con
--allowedTools "Read,Glob,Grep"para restringir a operaciones de solo lectura.
Generación Automática de Release Notes
Cuando se crea un release, Claude analiza el historial de commits y genera las notas de lanzamiento automáticamente.
name: Release Notes
on:
release:
types: [created]
jobs:
generate-notes:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Full history for commit analysis
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Generate release notes for tag ${{ github.event.release.tag_name }}.
Analyze all commits since the previous tag:
1. Group changes by category (Features, Bug Fixes, Performance, Documentation)
2. Write user-facing descriptions (not commit hashes)
3. Highlight breaking changes with ⚠️ prefix
4. Include migration steps if needed
Format as GitHub-flavored markdown.
Update the release body with the generated notes.fetch-depth: 0es imprescindible: Claude necesita el historial completo de git para comparar tags.- Funciona mejor con Conventional Commits (
feat:,fix:,breaking:). - Combínalo con reglas en
CLAUDE.mdsobre el formato de tu changelog para obtener resultados más consistentes.
Estrategia Matrix para Reviews en Paralelo
Ejecuta múltiples revisiones especializadas en paralelo usando la estrategia matrix de GitHub Actions.
name: Multi-Aspect Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
strategy:
matrix:
aspect:
- name: security
prompt: "Review for OWASP Top 10 vulnerabilities, injection risks, and auth issues"
- name: performance
prompt: "Review for N+1 queries, memory leaks, unnecessary re-renders, and heavy computations"
- name: maintainability
prompt: "Review for code duplication, complex functions (>20 lines), missing error handling, and unclear naming"
permissions:
contents: read
pull-requests: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
You are a ${{ matrix.aspect.name }} specialist.
${{ matrix.aspect.prompt }}
Be specific: reference file names and line numbers.
If no issues found, say "✅ No ${{ matrix.aspect.name }} issues found."- Cada aspecto se ejecuta en un job separado, es decir, verdadero paralelismo, no ejecución secuencial.
- Cada revisión se enfoca en una sola dimensión, evitando revisiones amplias pero superficiales.
- Coste: aproximadamente 3x el de una revisión única, pero mucho más exhaustivo.
- Agrega
if: contains(github.event.pull_request.labels.*.name, 'deep-review')para activarlo solo cuando sea necesario.
Automatización de Actualización de Dependencias
Ejecuta una revisión semanal de dependencias y crea PRs automáticamente para parches de seguridad.
name: Weekly Dependency Check
on:
schedule:
- cron: "0 9 * * 1" # Every Monday at 9 AM
workflow_dispatch: # Manual trigger
jobs:
check-deps:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Check for outdated dependencies in this project:
1. Run `npm outdated` (or equivalent for the package manager used)
2. For each outdated package, check:
- Is it a major version bump? (potential breaking changes)
- Does the changelog mention security fixes?
- Are there known vulnerabilities? (check `npm audit`)
3. Create a summary categorized by:
- 🔴 Security patches (update immediately)
- 🟡 Minor updates (safe to update)
- 🟠 Major updates (needs review)
4. If there are security patches, create a PR with those updates
Be conservative — only auto-update for security patches.
Major version bumps should only be recommended, not applied.- Programa con cron para mantenimiento regular.
workflow_dispatchpermite ejecuciones manuales cuando sea necesario.- Enfoque conservador: PR automático solo para seguridad, recomendaciones para todo lo demás.
- Combínalo con reglas en
CLAUDE.mdsobre políticas de gestión de dependencias.
Claude vs Codex en CI
- Claude: mejor para review, síntesis y explicación
- Codex: mejor para ejecución acotada, cambios y validación
Empieza Comentando, No Mergeando
El mejor primer paso suele ser automatización que comenta, resume o redacta, no que mergea sola.
Ejemplos:
- comentarios de revisión en PRs
- resúmenes de fallos en trabajos de CI
- release notes generadas
Saltar directamente a comportamiento de merge autónomo suele ser el punto de partida equivocado.
El Valor Real
El beneficio real no es la autonomía llamativa. Es hacer que los flujos de trabajo repetidos del equipo sean más rápidos, más consistentes y más fáciles de revisar.
Ahí es donde la automatización con Claude Code se vuelve genuinamente útil.