Módulo 3: GitLab CI/CD y SDK Headless

Descripción

Los Módulos 1-2 te dieron Claude Code operando en GitHub Actions: workflows funcionales, code review automático con inline comments. Pero hay un detalle: todo lo que construiste está atado a GitHub. Si tu equipo migra a GitLab, si trabajas con un cliente que usa Bitbucket, si necesitas correr el mismo análisis en Jenkins — tendrías que reescribir todo.

Este módulo resuelve ese problema mostrando una capa de abstracción: el SDK headless de Claude Code. La lección no es "cómo usar GitLab" — es portabilidad. Escribes la lógica una vez en Python o TypeScript usando el SDK, y la ejecutas en cualquier plataforma de CI/CD: GitHub Actions, GitLab CI/CD, Jenkins, CircleCI, lo que venga después.

GitLab CI/CD es el caso de estudio porque tiene adopción significativa (~25% del mercado, dominante en enterprise y self-hosted) y porque su modelo de stages/jobs es lo suficientemente diferente de GitHub Actions para que la portabilidad sea genuina, no un copy-paste con cambios de sintaxis.

Al terminar las 5 cápsulas, vas a tener pipelines de GitLab CI/CD funcionales con Claude Code integrado, vas a entender por qué el SDK headless es la abstracción correcta, y vas a poder portar tu lógica a cualquier plataforma futura.

Dónde Estamos en la Guía

Phase 1: Pre-Merge Automation (Módulos 1-2)
├── Módulo 1: Claude Code en GitHub Actions ✅
└── Módulo 2: Code Review Automático en PRs ✅

Phase 2: Cross-Platform y Deployment (Módulos 3-4)
├── Módulo 3: GitLab CI/CD y SDK Headless ← ESTÁS AQUÍ
│   → Portabilidad, GitLab pipelines, SDK como abstracción
└── 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 3 de 6 — la transición de "Claude Code en GitHub" a "Claude Code en cualquier plataforma". Los Módulos 4-5 vuelven a usar GitHub Actions como ejemplo principal, pero las técnicas que aprendes aquí aplican universalmente.

El Punto Real: Portabilidad

Hay una analogía útil para entender por qué este módulo importa más allá de GitLab:

SIN SDK HEADLESS:
→ Tu lógica de code review está en YAML de GitHub Actions
→ Si migras a GitLab: reescribir todo en YAML de GitLab CI/CD
→ Si después usas Jenkins: reescribir todo en Groovy
→ La lógica de negocio (qué analizar, cómo) se mezcla con
  la lógica de plataforma (cómo orquestar)

CON SDK HEADLESS (este módulo):
→ Escribes la lógica una vez: review.py o review.ts
→ El YAML de cada plataforma solo orquesta: "ejecuta este
  script en este step"
→ Cambiar de plataforma = cambiar el YAML, no la lógica
→ Separación clara: el script tiene la inteligencia, el YAML
  solo lo dispara

El SDK headless es a Claude Code lo que un SDK de cloud provider es a infraestructura. No te ata a una plataforma — te abstrae sobre ella.

Una Decisión Real: Cliente Enterprise

Para anclar el módulo, considera un caso típico de un developer freelance o consultor:

Situación: Trabajas con dos clientes. El Cliente A usa GitHub Actions, el Cliente B usa GitLab self-hosted (enterprise). Ambos quieren el mismo bot de code review que armaste en el Módulo 2.

Enfoque A: Reescribir todo

Para Cliente A (GitHub):
- Workflow YAML completo en .github/workflows/
- Lógica de extracción del diff embebida en YAML
- Llamadas a GitHub API embebidas en bash
- ~150 líneas de YAML

Para Cliente B (GitLab):
- Pipeline YAML completo en .gitlab-ci.yml
- Lógica de extracción del diff REESCRITA (CI_MERGE_REQUEST_*
  variables son distintas a GITHUB_*)
- Llamadas a GitLab API REESCRITAS (estructura diferente)
- ~150 líneas de YAML

Tiempo total: 2× — escribiste todo dos veces
Mantenimiento: 2× — cualquier mejora va a ambos lados
Bugs específicos: aparecen en uno y no en otro

Enfoque B: SDK headless (este módulo)

Lógica compartida (escrita una vez):
- review.py: ~80 líneas que usan el SDK de Claude Code
- Toma el diff como argumento (no asume plataforma)
- Toma el repo URL como argumento
- Devuelve estructura JSON con los hallazgos

Para Cliente A (GitHub):
- Workflow YAML de ~25 líneas que:
  → checkout
  → instala el SDK
  → ejecuta `python review.py`
  → publica resultados via GitHub API

Para Cliente B (GitLab):
- Pipeline YAML de ~25 líneas que:
  → ejecuta el mismo `python review.py`
  → publica resultados via GitLab API

Tiempo total: 1× lógica + 2× orquestación delgada
Mantenimiento: mejoras a la lógica benefician a ambos clientes
Bugs: si funciona en uno, funciona en el otro

Misma capacidad. Mismo agente. Diferencia: la lógica de negocio vive en un script Python, no en YAML de plataforma.

Este principio escala más allá de GitHub vs GitLab — si en 2 años aparece una nueva plataforma de CI/CD, tu lógica sigue funcionando.

Prerequisitos

Conocimiento requerido:

✅ Módulos 1-2 completados (Claude Code en GitHub Actions con code review)
✅ Python o TypeScript a nivel intermedio
✅ Familiaridad con Docker (los jobs de GitLab corren en containers)

NO requerido:

❌ No necesitas haber configurado un pipeline de GitLab antes
❌ No necesitas conocer Jenkins ni otras plataformas (las menciones son referenciales)

Roadmap del Módulo

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

Por qué portabilidad importa. El escenario de los dos clientes.

Cápsula 02 — SDK headless: Python y TypeScript

Anatomía del SDK de Claude Code. Cómo se invoca desde un script. Diferencias entre el SDK Python y el TypeScript. Cuándo elegir cada uno.

Cápsula 03 — GitLab CI/CD: stages, jobs, artifacts

Las diferencias clave entre GitHub Actions (workflows + jobs + steps) y GitLab CI/CD (pipelines + stages + jobs). Variables de environment específicas. Artifacts. Docker executor.

Cápsula 04 — Pipeline GitLab con SDK headless

Tu primer pipeline de GitLab CI/CD funcional ejecutando el script SDK. Configuración de Docker executor con dependencias. Manejo de secrets en GitLab.

Cápsula 05 — Proyecto: Portar el bot del Módulo 2 a GitLab

Tomar el bot de code review del Módulo 2 (que vive en GitHub Actions YAML), refactorizar la lógica al SDK headless, y demostrar que el mismo script corre en ambas plataformas.

Mapa de progresión

Cápsula 01 (esta)  → Por qué portabilidad
Cápsula 02         → SDK headless explicado
Cápsula 03         → GitLab CI/CD vs GitHub Actions
Cápsula 04         → Pipeline GitLab funcional
Cápsula 05         → Proyecto: bot portado

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

Qué Lograrás en Este Módulo

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

Escribir scripts en Python o TypeScript que invocan el SDK headless de Claude Code
Distinguir entre GitHub Actions y GitLab CI/CD a nivel arquitectural (no solo sintáctico)
Configurar pipelines de GitLab CI/CD con stages apropiados para Claude Code
Manejar secrets y variables en GitLab (CI/CD variables, masked, protected)
Demostrar portabilidad ejecutando el mismo script en ambas plataformas
Tomar decisiones arquitecturales sobre dónde poner la lógica (script vs YAML)

El antes y después

ANTES del módulo:
→ "Mi lógica de Claude Code está en YAML"
→ "Cambiar de plataforma significa reescribir todo"
→ "GitLab y GitHub son básicamente lo mismo"

DESPUÉS del módulo:
→ Lógica en script SDK, orquestación en YAML
→ Cambiar de plataforma = cambiar 25 líneas de YAML
→ Las diferencias arquitecturales entre GitHub y GitLab
  están claras, y sé cómo abstraerlas

Trampas a Evitar al Cursar Este Módulo

Cinco malentendidos previsibles. Anticípalos antes de empezar.

1. "Voy a copiar el YAML de GitHub Actions y cambiarle la sintaxis"

No funciona. Los modelos son distintos: GitHub usa workflow → job → step, GitLab usa pipeline → stage → job. Las variables de environment son distintas (GITHUB_* vs CI_*). Los artifacts y caches operan de forma diferente. Traducir línea por línea da pipelines frágiles. La cápsula 03 te explica los modelos, no solo la sintaxis.

2. "El SDK headless es solo para automatización avanzada"

No. El SDK headless es la forma correcta de usar Claude Code en cualquier script — no solo en CI/CD. Es la API que te da control programático: pasas el contexto, especificas el prompt, recibes la respuesta como datos estructurados. El modo interactivo (terminal) es para humanos; el SDK es para automatización. La cápsula 02 desarrolla esto.

3. "Voy a meter toda la lógica en el YAML de cada plataforma"

Lo opuesto del módulo. Toda lógica de negocio en script, toda lógica de orquestación en YAML. Si tu YAML tiene más de 50 líneas, probablemente está haciendo demasiado. La cápsula 04 muestra el balance correcto: YAML delgado que solo invoca scripts ricos.

4. "GitLab no es importante porque uso GitHub"

Es exactamente la trampa que el módulo evita. No es sobre GitLab — es sobre que tu lógica no esté atada a una plataforma. Aunque uses GitHub para siempre, escribir la lógica con SDK te da: testing más fácil (puedes correr el script localmente), debugging más fácil (no dependes del runner), y futuro-proofing.

5. "El SDK Python y el SDK TypeScript son intercambiables"

Tienen feature parity, pero hay diferencias. Python es más común en data/ML/scripts; TypeScript es más natural en JS/TS projects. Los tipos son más expresivos en TypeScript; el ecosistema es más rico en Python. La cápsula 02 te ayuda a elegir según tu contexto y stack.

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

Cinco preguntas para calibrar antes de empezar.

Pregunta 1: ¿Has usado el SDK headless de Claude Code antes (Guía 9)?

Si sí: vas con la base. Este módulo aplica el SDK al contexto específico de CI/CD.

Si no: revisa Guía 9 Módulo 6 antes — el SDK es prerrequisito técnico de este módulo.

Pregunta 2: ¿Has configurado un pipeline de GitLab CI/CD antes?

Si sí: la cápsula 03 te da una vista comparativa con GitHub Actions.

Si no: la cápsula 03 te enseña desde cero, con foco en lo que difiere de GitHub.

Pregunta 3: Si tuvieras que correr el mismo script en GitHub Actions y GitLab CI/CD, ¿qué cambiarías?

Si dijiste "el YAML, no el script": vas con el modelo mental correcto.

Si dijiste "la lógica del script": la trampa #3 te aplica. La cápsula 04 desarrolla la separación.

Pregunta 4: ¿Sabes qué es un Docker executor en GitLab CI/CD?

Si sí: la cápsula 04 te muestra cómo configurarlo para el SDK.

Si no: los jobs de GitLab corren en containers Docker. La cápsula 04 te enseña cómo el container trae las dependencias.

Pregunta 5: ¿Por qué importaría escribir lógica en SDK en lugar de YAML, aunque solo uses una plataforma?

Si tienes razones: las cápsulas 02 y 04 las refuerzan.

Si no: razones principales — testing local, debugging, futuro-proofing, claridad arquitectural. La cápsula 02 desarrolla cada una.

Si dudaste en 3 o más: este módulo te llena vacíos importantes para los siguientes. Si respondiste todas con seguridad, úsalo enfocado en la cápsula 05 (proyecto), que es donde se internaliza la portabilidad.

Conexión con el Proyecto Final

En el Módulo 6 (Proyecto Integrador), el pipeline completo se construye primariamente en GitHub Actions, pero la portabilidad demostrada aquí permite adaptarlo a GitLab o cualquier otra plataforma. La lección del módulo es que tu inversión técnica no se ata a una plataforma específica.

Cómo Trabajar Este Módulo

La cápsula 02 es la base técnica. Sin entender el SDK, las cápsulas 04-05 no se pueden ejecutar.
La cápsula 03 es estratégica. Te da el modelo mental para distinguir GitHub Actions de GitLab más allá de la sintaxis.
La cápsula 04 es la práctica concreta. Léela con una cuenta de GitLab abierta.
La cápsula 05 internaliza el concepto. Portar el bot a GitLab es donde se siente la portabilidad.

Tiempo estimado:

Cápsula 01 (esta)  →  10 min lectura
Cápsula 02         →  20 min + práctica con SDK
Cápsula 03         →  15 min lectura comparativa
Cápsula 04         →  25 min + setup de GitLab
Cápsula 05         →  30 min + portar bot

Total: ~1.5-2 horas

Evidencia de Éxito

Antes de avanzar al Módulo 4 (Deployment Automation), deberías poder:

✅ Escribir un script que use el SDK headless de Claude Code para una tarea específica
✅ Comparar las arquitecturas de GitHub Actions y GitLab CI/CD (no solo sintaxis)
✅ Configurar un pipeline de GitLab CI/CD con Docker executor y SDK
✅ Manejar variables y secrets en GitLab de forma segura
✅ Ejecutar el mismo script en GitHub Actions y GitLab CI/CD con cambios mínimos en el YAML
✅ Decidir conscientemente dónde poner cada pieza: lógica en script, orquestación en YAML

Si alguno no se cumple al final, regresa a la cápsula correspondiente. El Módulo 4 (deployment) asume que ya entiendes la separación lógica-script / orquestación-YAML.

Resumen

Este módulo te da portabilidad cross-platform vía SDK headless
GitLab CI/CD es el caso de estudio, no el destino — el principio aplica universalmente
SDK = lógica, YAML = orquestación es la separación arquitectural correcta
Docker executor es el enabler en GitLab — el container trae todas las dependencias
Tu lógica de Claude Code no debe atarse a una plataforma específica
La diferencia entre "reescribir todo dos veces" y "lógica una vez, orquestación delgada" del escenario inicial es exactamente este módulo

Siguiente cápsula: 02 — SDK headless: Python y TypeScript. Empezamos por entender el SDK como interfaz programática a Claude Code — la base técnica sobre la que construimos la portabilidad. Sin esto, las cápsulas 04-05 son ejecución sin entender qué pasa por debajo.

Recursos Adicionales

Claude Code SDK Documentation — Referencia oficial del SDK
GitLab CI/CD Documentation — Documentación oficial completa
GitLab CI/CD Variables — Cómo se manejan variables y secrets
GitLab Docker Executor — Configuración del executor
GitHub Actions vs GitLab CI/CD — Guía oficial de GitLab para migración
SDK Python para Anthropic — Repositorio oficial del SDK Python
SDK TypeScript para Anthropic — Repositorio oficial del SDK TypeScript

← AnteriorManejar PRs Grandes con Chunking Siguiente →SDK Headless: Python y TypeScript

Módulo 3: GitLab CI/CD y SDK Headless

Módulo 3: GitLab CI/CD y SDK Headless

Descripción

Dónde Estamos en la Guía

El Punto Real: Portabilidad

Una Decisión Real: Cliente Enterprise

Enfoque A: Reescribir todo

Enfoque B: SDK headless (este módulo)

Prerequisitos

Conocimiento requerido:

Recomendado:

NO requerido:

Roadmap del Módulo

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

Cápsula 02 — SDK headless: Python y TypeScript

Cápsula 03 — GitLab CI/CD: stages, jobs, artifacts

Cápsula 04 — Pipeline GitLab con SDK headless

Cápsula 05 — Proyecto: Portar el bot del Módulo 2 a GitLab

Mapa de progresión

Qué Lograrás en Este Módulo

El antes y después

Trampas a Evitar al Cursar Este Módulo

1. "Voy a copiar el YAML de GitHub Actions y cambiarle la sintaxis"

2. "El SDK headless es solo para automatización avanzada"

3. "Voy a meter toda la lógica en el YAML de cada plataforma"

4. "GitLab no es importante porque uso GitHub"

5. "El SDK Python y el SDK TypeScript son intercambiables"

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

Conexión con el Proyecto Final

Cómo Trabajar Este Módulo

Tiempo estimado:

Evidencia de Éxito

Resumen

Recursos Adicionales