Módulo 1: Claude Code en GitHub Actions

Descripción

Hasta ahora, en las guías 1-9 del path, has usado Claude Code en tu máquina local: lo abres, le das una tarea, ves el resultado. Es poderoso, pero limitado a tu sesión activa. Esta guía cierra esa limitación: vas a configurar Claude Code para que opere automáticamente en cada pull request, en cada push, sin que tengas que abrir nada.

Este módulo es el punto de entrada. GitHub Actions es la plataforma de CI/CD más adoptada en la industria — el 65% de los repositorios públicos en GitHub la usan, y la mayoría de los proyectos profesionales también. Configurar Claude Code como un step en un workflow de GitHub Actions es la forma más directa de dar el salto de "herramienta local" a "agente de producción".

Al terminar las 5 cápsulas, vas a tener un workflow YAML que ejecuta Claude Code en cada pull request, con secrets manejados de forma segura, output parseado correctamente, y costos controlados con rate limiting básico. Es la base sobre la que se construye todo el pipeline de la guía.

Dónde Estamos en la Guía

Phase 1: Pre-Merge Automation (Módulos 1-2)
├── Módulo 1: Claude Code en GitHub Actions ← ESTÁS AQUÍ
│   → Workflow YAML, secrets, output parsing, costos
└── Módulo 2: Code Review Automático en PRs
    → Bot que comenta inline en PRs

Phase 2: Cross-Platform y Deployment (Módulos 3-4)
├── Módulo 3: GitLab CI/CD y SDK Headless
└── Módulo 4: Deployment Automation

Phase 3: Resiliencia y Proyecto (Módulos 5-6)
├── Módulo 5: Security Scanning y Rollback
└── Módulo 6: Proyecto Integrador — Pipeline Completo

Este es el Módulo 1 de 6 — el cimiento. Cada módulo posterior agrega capacidades al pipeline que arrancas aquí. Sin este módulo funcional, los demás módulos pierden contexto.

El Cambio Mental: De Local a Automático

Hay una diferencia categórica entre "usar Claude Code" y "tener Claude Code trabajando por ti":

USO LOCAL (lo que ya sabes):
→ Abres tu terminal, lanzas Claude Code
→ Le das una tarea: "revisa este código"
→ Esperas, ves el resultado
→ Cierras la sesión
→ Mañana lo repites para el siguiente PR

USO EN CI/CD (lo que aprendes en esta guía):
→ Abres un PR en GitHub
→ Claude Code analiza el código sin que hagas nada
→ Ves el resultado en la página del PR
→ Continúas con tu siguiente tarea
→ Esto pasa en cada PR, automáticamente, para siempre

La diferencia no es velocidad — es escalabilidad y consistencia. El primer modo depende de que tú recuerdes hacerlo. El segundo no depende de nada — pasa solo. Y cuando pasa solo, pasa en cada PR de cada miembro del equipo, no solo cuando tú estás disponible.

Una Tarea Real: Antes y Después

Para anclar el módulo, considera un escenario típico de un equipo de tres developers:

Tarea del equipo: Asegurar que cada PR pase por análisis de Claude Code antes de que un humano lo revise. El objetivo: detectar problemas obvios temprano y que el reviewer humano se enfoque en cosas que requieren juicio.

Enfoque A: Sin CI/CD (lo que hacen muchos equipos hoy)

Lunes 10:00 → Developer abre PR
Lunes 11:00 → Reviewer humano nota que hay algo raro
Lunes 11:15 → Reviewer pide a developer que pase Claude Code
              al diff en local
Lunes 14:00 → Developer encuentra tiempo, lo hace, encuentra
              2 issues, los arregla
Lunes 16:00 → Re-review, merge

PROBLEMAS:
- Inconsistente: depende de que el reviewer pida análisis
- Tardío: los issues se detectan después de que el reviewer
  ya invirtió tiempo
- No escala: cada developer tiene que recordar hacerlo
- No queda registro: el análisis no vive en el PR

Enfoque B: Con GitHub Actions (lo que aprendes aquí)

Lunes 10:00 → Developer abre PR
Lunes 10:01 → GitHub Actions dispara workflow automáticamente
Lunes 10:03 → Claude Code completa su análisis
Lunes 10:03 → El análisis aparece como check en el PR
              + comentario con resumen de hallazgos
Lunes 10:30 → Reviewer humano ve el PR YA con el análisis hecho
              y se enfoca en lo que el agente no puede juzgar
Lunes 11:00 → Merge

VENTAJAS:
- Consistente: pasa en CADA PR, sin excepción
- Temprano: issues se detectan antes del review humano
- Escala: aplica al equipo entero sin esfuerzo individual
- Registro: el análisis vive en el PR para auditoría futura

Misma tarea. Mismo equipo. Resultado radicalmente distinto en consistencia y velocidad.

La diferencia no fue la calidad del análisis — el análisis es el mismo Claude Code. La diferencia fue automatizar el disparo y estandarizar el output. Esas son las dos cosas que enseña este módulo.

Prerequisitos

Conocimiento requerido:

✅ Guías 1-9 del path completadas (Claude Code básico, prompt engineering, MCP, debugging, testing, refactoring, advanced workflows)
✅ SDK headless de Claude Code (Guía 9, módulo 6) — la base técnica de este módulo
✅ Familiaridad con Git y pull requests
✅ Una cuenta de GitHub con un repositorio donde puedas hacer push

NO requerido:

❌ No necesitas haber escrito un workflow de GitHub Actions desde cero
❌ No necesitas conocer GitLab CI/CD ni otras plataformas (eso es Módulo 3)
❌ No necesitas Docker (los workflows básicos no lo requieren)

Roadmap del Módulo

Cápsula 01 — Introducción al módulo (esta cápsula)

Contexto del cambio de local a CI/CD. El escenario antes/después.

Cápsula 02 — Tu primer workflow YAML

Anatomía de un workflow de GitHub Actions: triggers, jobs, steps. Tu primer YAML que ejecuta Claude Code en cada PR. Ejecutarlo y ver el resultado.

Cápsula 03 — Secrets management con GitHub Secrets

Cómo manejar tu ANTHROPIC_API_KEY de forma segura. Por qué nunca debe ir en el YAML. Secrets a nivel repositorio, organización, y environment. Limitaciones y buenas prácticas.

Cápsula 04 — Parsear output y generar artefactos

Claude Code produce texto — necesitas convertirlo en algo útil. PR comments, annotations, artifacts descargables. Estrategias según el caso de uso.

Cápsula 05 — Costos y rate limiting

Cada ejecución cuesta dinero. Cómo calcular el costo por PR. Estrategias para ejecutar selectivamente: solo en PRs relevantes, solo en archivos modificados, solo si pasaron tests previos. Cuándo skipear.

Mapa de progresión

Cápsula 01 (esta)  → Por qué CI/CD para Claude Code
Cápsula 02         → Tu primer workflow funcional
Cápsula 03         → Secrets management seguro
Cápsula 04         → Output útil (no logs ignorados)
Cápsula 05         → Costos bajo control

Dificultad: ⭐⭐ ──────────────────▶ ⭐⭐⭐

Qué Lograrás en Este Módulo

Al completar las 5 cápsulas, podrás:

Crear un workflow YAML que ejecuta Claude Code en cada pull request
Configurar triggers apropiados (pull_request: opened, synchronize) sin generar ejecuciones innecesarias
Manejar secrets de forma segura con GitHub Secrets — sin filtrar API keys
Parsear el output de Claude Code y generar artefactos visibles (comments, annotations)
Calcular y controlar costos — saber cuánto cuesta cada PR run y cómo optimizarlo
Ejecutar el workflow end-to-end y verificar que corre en PRs reales

El antes y después

ANTES del módulo:
→ "Claude Code es una herramienta que abro cuando lo necesito"
→ "El análisis depende de que yo lo recuerde"
→ "Cada developer del equipo lo usa diferente"

DESPUÉS del módulo:
→ Claude Code corre en CADA PR sin que nadie lo dispare
→ Los resultados son consistentes para todo el equipo
→ Los costos están controlados y son predecibles
→ El análisis vive como parte del PR, no como conversación efímera

Qué NO Cubre Este Módulo

Tema	Dónde se cubre
Comentarios inline en PRs (line-level)	Módulo 2
GitLab CI/CD	Módulo 3
Deployment automation	Módulo 4
Security scanning con Claude Code	Módulo 5
Pipeline completo end-to-end	Módulo 6
Vulnerabilidades específicas de código AI	Guía #11 (Security)

Este módulo es el cimiento: aprendes a poner Claude Code en GitHub Actions de forma técnica y operativa. Las aplicaciones específicas (review, deployment, security) vienen en módulos posteriores.

Trampas a Evitar al Cursar Este Módulo

Cinco malentendidos previsibles. Anticípalos antes de empezar.

1. "Hardcodear la API key en el YAML 'temporalmente'"

No. Hardcodear secrets en YAML los expone en el historial de git para siempre, aunque después los muevas a Secrets. La regla del módulo es absoluta: API keys van a GitHub Secrets desde el primer commit, sin excepciones. Si rotas la key después, el daño ya está hecho — y rotar requiere revocar la antigua, lo cual interrumpe a todo el equipo.

2. "Configurar triggers en push sin filtros"

Ejecutar el workflow en cada push (no solo PRs) genera costos innecesarios y satura el dashboard de Actions. Lo correcto es configurar triggers específicos — pull_request: [opened, synchronize] y opcionalmente push: [main] con filtros de paths. La cápsula 05 desarrolla la economía de cuándo ejecutar y cuándo no.

3. "Ignorar costos porque 'Claude Code es barato'"

Cada API call cuesta. Con un equipo de 5 developers y 10 PRs por semana, 5 actualizaciones por PR, son 250 ejecuciones semanales. A unos centavos por ejecución, son varios cientos de dólares al mes — no insignificante. La cápsula 05 te enseña a presupuestar y optimizar.

4. "Output como log que nadie lee"

Claude Code genera texto. Si ese texto solo termina en los logs de GitHub Actions, nadie lo lee. Los developers ven los PRs, no los logs de workflows. Cualquier hallazgo útil tiene que aterrizar en el PR mismo: como comentario, annotation, o check status. La cápsula 04 desarrolla las estrategias.

5. "Tratar el workflow como código de descarte"

Un workflow YAML es código de producción: corre en cada PR, afecta al equipo entero, y sus errores son visibles. Necesita el mismo cuidado que cualquier código: review, versioning de actions, comentarios cuando algo no es obvio. Tratar el YAML como "configuración rápida que puedo cambiar después" lleva a workflows frágiles que se rompen sin razón aparente.

Diagnóstico: ¿Cuál es tu Punto de Partida?

Cinco preguntas para calibrar antes de empezar.

Pregunta 1: ¿Has escrito un workflow de GitHub Actions antes? Si sí, ¿lo escribiste tú o lo copiaste?

Si lo escribiste tú: vas con ventaja. El módulo formaliza lo que ya intuyes y agrega Claude Code.

Si lo copiaste: está bien — la mayoría empieza así. La cápsula 02 te explica la anatomía pieza por pieza para que dejes de copiar y empieces a escribir.

Pregunta 2: ¿Sabes la diferencia entre un secret a nivel repositorio, organización, y environment?

Si sí: la cápsula 03 formaliza lo que ya intuyes y agrega buenas prácticas.

Si no: es exactamente lo que la cápsula 03 te enseña. La distinción importa para no exponer secrets a más de lo necesario.

Pregunta 3: ¿Cuánto crees que cuesta correr Claude Code 100 veces en un mes?

Si tienes una cifra: la cápsula 05 te ayuda a validarla y controlarla.

Si no: la mayoría no la tiene — y por eso las facturas sorprenden. La cápsula 05 te da el cálculo y las estrategias de optimización.

Pregunta 4: Si Claude Code analiza un PR y encuentra algo importante, ¿dónde aparece ese hallazgo?

Si dijiste "en los logs del workflow": funciona técnicamente, pero nadie los lee. La cápsula 04 te muestra cómo aterrizar el hallazgo en el PR mismo.

Si dijiste "como comentario o check del PR": vas bien. La cápsula 04 te da las técnicas concretas.

Pregunta 5: ¿Qué pasa si tu workflow falla (no Claude Code, sino el YAML mismo)?

Si tienes un plan: la cápsula 02 lo formaliza con debugging de workflows.

Si no: los workflows fallan más a menudo de lo que parece (acción deprecated, sintaxis YAML, permisos faltantes). La cápsula 02 te enseña a leer logs y corregir.

Si dudaste en 3 o más: este módulo es prioritario antes de seguir. Si respondiste todas con seguridad, úsalo como repaso enfocado en la cápsula 05 (costos y rate limiting), que casi nadie domina al inicio.

Cómo Trabajar Este Módulo

La cápsula 02 es la más práctica. Léela con un repositorio de GitHub abierto al lado para hacer cada paso.
La cápsula 03 es la más importante para producción. Secrets mal manejados son la causa #1 de incidents en CI/CD.
La cápsula 04 es donde el módulo se vuelve útil. Sin output visible, todo lo anterior es puro ejercicio.
La cápsula 05 es la que ahorra dinero a tu equipo. No la trates como opcional.

Tiempo estimado:

Cápsula 01 (esta)  →  10 min lectura
Cápsula 02         →  20 min + práctica
Cápsula 03         →  15 min + setup de secrets
Cápsula 04         →  20 min + práctica
Cápsula 05         →  15 min + cálculo de costos

Total: ~1.25-1.5 horas

Evidencia de Éxito

Antes de avanzar al Módulo 2 (Code Review Automático), deberías poder:

✅ Crear un workflow YAML desde cero que ejecuta Claude Code en pull requests, sin copiar templates
✅ Configurar GitHub Secrets con tu API key y referenciarla correctamente en el YAML
✅ Identificar qué triggers son apropiados según el caso de uso (PR vs push, con o sin filtros)
✅ Generar output visible en el PR — al menos un comentario o check con el resultado del análisis
✅ Estimar el costo de un mes de ejecución del workflow para tu equipo
✅ Diagnosticar un workflow que falla leyendo los logs de Actions

Si alguno no se cumple al final, regresa a la cápsula correspondiente. El Módulo 2 (Code Review) construye directamente sobre estas bases — sin un workflow funcional aquí, no hay sobre qué construir.

Resumen

Este módulo es el punto de entrada a CI/CD para Claude Code
El cambio clave: de local a automático — el agente trabaja sin que lo dispares
GitHub Actions es la plataforma elegida por adopción y porque es la base del pipeline completo
Secrets management es innegociable desde el primer commit
Costos importan — diseñar para eficiencia desde el inicio, no como afterthought
Output útil > logs ignorados — el hallazgo tiene que aterrizar en el PR
La diferencia entre el "Lunes 16:00 con merge" y "Lunes 11:00 con merge" del escenario inicial es exactamente lo que enseña este módulo

Siguiente cápsula: 02 — Tu primer workflow YAML. Empezamos por la anatomía de un workflow de GitHub Actions y construimos paso a paso uno que ejecuta Claude Code en cada PR. Sin ceremonia teórica — código que copias, ejecutas, y ves correr.

Recursos Adicionales

GitHub Actions Documentation — Documentación oficial completa
GitHub Actions Workflow Syntax — Referencia de sintaxis YAML
Anthropic API Documentation — Cómo se autentica Claude Code en CI
Claude Code SDK Headless — La capa técnica que usaremos en CI
GitHub Secrets Documentation — Cómo manejar secrets correctamente
GitHub Octoverse 2025 — Datos de adopción de GitHub Actions y CI/CD

Siguiente →Tu Primer Workflow YAML con Claude Code

Módulo 1: Claude Code en GitHub Actions

Módulo 1: Claude Code en GitHub Actions

Descripción

Dónde Estamos en la Guía

El Cambio Mental: De Local a Automático

Una Tarea Real: Antes y Después

Enfoque A: Sin CI/CD (lo que hacen muchos equipos hoy)

Enfoque B: Con GitHub Actions (lo que aprendes aquí)

Prerequisitos

Conocimiento requerido:

Recomendado:

NO requerido:

Roadmap del Módulo

Cápsula 01 — Introducción al módulo (esta cápsula)

Cápsula 02 — Tu primer workflow YAML

Cápsula 03 — Secrets management con GitHub Secrets

Cápsula 04 — Parsear output y generar artefactos

Cápsula 05 — Costos y rate limiting

Mapa de progresión

Qué Lograrás en Este Módulo

El antes y después

Qué NO Cubre Este Módulo

Trampas a Evitar al Cursar Este Módulo

1. "Hardcodear la API key en el YAML 'temporalmente'"

2. "Configurar triggers en push sin filtros"

3. "Ignorar costos porque 'Claude Code es barato'"

4. "Output como log que nadie lee"

5. "Tratar el workflow como código de descarte"

Diagnóstico: ¿Cuál es tu Punto de Partida?

Cómo Trabajar Este Módulo

Tiempo estimado:

Evidencia de Éxito

Resumen

Recursos Adicionales