El Proyecto | Sobre nosotros | Contribuir | Donaciones | Licencia

HOME

Cerrábamos el módulo 1 con una promesa: Diego dejará de compilar en su portátil; a partir de ahí, cada cambio se verifica solo, en una máquina limpia, antes de que nadie lo fusione. Esta lección es el paso previo a cumplirla. Y es un paso que casi todo el mundo se salta, porque es tentador abrir directamente el editor y escribir YAML. El problema es que un fichero de configuración no convierte a un equipo en un equipo que practica Integración Continua, igual que comprar unas zapatillas no convierte a nadie en corredor. La CI es, antes que nada, un conjunto de prácticas y de acuerdos; la herramienta solo los hace cumplir. En esta lección veremos cuáles son esas prácticas, cómo es el ciclo de vida completo de un cambio bajo CI, qué significa exactamente que la build esté "verde" o "roja" y qué disciplina exige, y cuál es la anatomía conceptual de un workflow. Terminaremos con las seis reglas que el equipo de Reservalia acuerda antes de escribir una sola línea de configuración. En la lección 02-02 escribiremos esa configuración.

Contenido

Por qué las reglas van antes que el YAML
Las seis prácticas que constituyen la Integración Continua
El ciclo de vida de un cambio bajo CI
Build verde, build roja y la disciplina de "stop the line"
Anatomía conceptual de un workflow
El acuerdo de equipo de Reservalia
Errores Comunes y Consejos
Ejercicios
Conclusión

Por qué las reglas van antes que el YAML

Imagina dos equipos. Ambos tienen un pipeline idéntico: compila, pasa las pruebas y avisa en un canal de chat.

Equipo A: las ramas viven tres semanas. Cuando la build se pone roja, nadie la mira hasta el día siguiente. El canal de avisos está silenciado porque "siempre falla algo".
Equipo B: las ramas viven medio día. Cuando la build se pone roja, la persona que la rompió deja lo que está haciendo. Si en diez minutos no está arreglada, revierte su commit.

El equipo A tiene un servidor de builds. El equipo B practica Integración Continua. El fichero de configuración es el mismo; lo que cambia es lo que el equipo hace con la información que produce.

Esta distinción es la razón de ser de esta lección. En la 01-01 vimos la definición formal de CI; ahora vamos a desmenuzar las prácticas concretas que hay detrás, porque son ellas —y no la herramienta— las que producen los beneficios que medimos con las métricas DORA de la 01-05.

Las seis prácticas que constituyen la Integración Continua

2.1. Un repositorio único como fuente de verdad

Todo lo necesario para construir y probar el sistema vive en un solo sitio versionado: código, pruebas, scripts de build, migraciones de base de datos, configuración del pipeline y definición de la infraestructura.

La prueba práctica: si mañana desaparecen todos los portátiles del equipo, ¿puedo reconstruir el sistema clonando el repositorio? Si la respuesta contiene un "bueno, más un script que tiene Diego en su carpeta de descargas", el repositorio no es la fuente de verdad.

Reservalia cumple esto a medias. El código y las migraciones están en github.com/reservalia/reservalia, pero los comandos de despliegue viven en la memoria de Diego. Esa deuda la saldaremos en el módulo 3.

2.2. Integración frecuente en la rama principal

Cada persona integra su trabajo en main al menos una vez al día. No es un consejo de estilo: es la definición operativa de la palabra "continua".

Recuerda el diagrama del integration hell de la 01-01: el coste de fusionar crece de forma no lineal con el tiempo que las ramas viven separadas. Dos ramas de un día se fusionan solas; dos ramas de tres semanas requieren una tarde de arqueología.

Una consecuencia incómoda: si una tarea tarda cinco días, no puedes esperar cinco días para integrar. Tienes que aprender a partir el trabajo en trozos que se puedan integrar sin romper nada aunque estén incompletos. Las técnicas para hacerlo (código latente, feature flags) las veremos en la 03-05; por ahora quédate con la idea de que integrar a menudo es una habilidad, no solo una norma.

2.3. Build automatizada en cada cambio

Cada git push dispara automáticamente un proceso que construye el sistema y ejecuta las pruebas en una máquina limpia. Sin que nadie pulse nada. Sin excepciones.

Las tres palabras importantes son automática (nadie decide si se ejecuta), cada (no solo antes de una release) y limpia (una máquina que parte de cero, sin las 47 herramientas que Diego tiene instaladas desde 2021).

2.4. La rama principal siempre desplegable

En cualquier momento del día, el último commit de main debe ser candidato válido a producción. No "casi listo": desplegable.

Esta es la práctica más exigente de las seis y la que más cambia la forma de trabajar de un equipo, porque prohíbe la frase "lo subo ahora y lo arreglo por la tarde". Y es también la que hace posible todo el módulo 3: si main siempre está sana, desplegar deja de ser un evento y se convierte en un trámite.

2.5. Si la build se rompe, el equipo para ("stop the line")

Es la práctica que más se incumple, y la desarrollamos en el apartado 4. En una frase: una build roja es un problema del equipo, no de quien la rompió, y arreglarla tiene prioridad sobre cualquier funcionalidad.

2.6. Feedback rápido

Un pipeline que tarda 45 minutos no da feedback: da un informe forense. Cuando llega la respuesta, quien hizo el cambio ya está en otra tarea y ha perdido el contexto.

La referencia práctica, y una de las frases que Diego ya soltó en el módulo 1 —"si el CI tarda más que ir a por un café..."—, es la siguiente:

Tiempo del pipeline	Qué ocurre en la práctica
< 10 min	La persona espera el resultado y lo corrige en caliente. Feedback real.
10–20 min	Cambia de tarea; volver cuesta unos minutos de recontextualización.
20–40 min	Se acumulan varios PR sin verificar; el fallo llega mezclado con otros cambios.
> 40 min	El equipo empieza a ignorar el pipeline y a saltárselo "solo esta vez".

El objetivo de Reservalia para el CI de este módulo será menos de 10 minutos en un pull request típico.

El ciclo de vida de un cambio bajo CI

Veamos el recorrido completo de un cambio concreto: Diego arregla un error en el cálculo de disponibilidad que hace que dos citas puedan solaparse cuando el negocio tiene un descanso a mediodía.

flowchart TD
    A["Diego crea la rama<br/>arreglo/solape-descanso"] --> B["Escribe la prueba que<br/>reproduce el fallo (falla)"]
    B --> C["Corrige el código<br/>hasta que la prueba pasa"]
    C --> D["Verificación local rápida<br/>npm run lint && npm test"]
    D --> E["git push"]
    E --> F["Abre un Pull Request<br/>hacia main"]
    F --> G{"El pipeline<br/>se dispara solo"}
    G --> H["Máquina limpia:<br/>checkout + instalar deps"]
    H --> I["Calidad · Pruebas · Build"]
    I --> J{"¿Todo verde?"}
    J -- No --> K["Diego corrige<br/>y vuelve a empujar"]
    K --> G
    J -- Sí --> L["Revisión humana:<br/>diseño, no comas ni tabs"]
    L --> M["Merge a main"]
    M --> N["El pipeline se ejecuta<br/>otra vez sobre main"]
    N --> O["Artefacto publicado<br/>reservalia/api:a3f9c21"]

Hay cuatro detalles de este flujo que conviene subrayar:

La verificación local existe, pero es corta. Diego no ejecuta toda la suite antes de empujar: ejecuta lo rápido (lint y pruebas unitarias). Lo lento lo hace la máquina. Un equipo que exige ejecutar todo en local antes de cada push está desperdiciando aquello para lo que sirve el CI.

El pipeline se ejecuta dos veces: una sobre el pull request y otra sobre main después del merge. No es redundancia inútil. El PR se verifica como estaba tu rama; después del merge, main puede contener commits que entraron mientras tanto. Esta ventana es exactamente el problema que resuelve la merge queue de la lección 02-07.

La revisión humana llega después del verde. Nadie debería revisar un PR cuyo pipeline está en rojo: es tiempo humano gastado en algo que la máquina ya sabe que está mal. Y como la máquina se ocupa del formato, del estilo y de los tipos (lección 02-05), la revisión humana puede hablar de lo que importa: si el diseño es correcto.

Del merge sale un artefacto identificado por el SHA. El commit a3f9c21 produce la imagen reservalia/api:a3f9c21. Esa trazabilidad es la materia de la lección 02-06.

Build verde, build roja y la disciplina de "stop the line"

4.1. Qué significa "verde"

Un pipeline no entiende de matices: cada paso termina con un código de salida. Cero significa éxito; cualquier otro valor, fallo. Puedes comprobarlo en tu terminal:

npm test              # ejecuta las pruebas
echo $?               # imprime el código de salida del comando anterior
# 0  → todas pasaron   → paso verde
# 1  → alguna falló    → paso rojo, el pipeline se detiene ahí

"Build verde" significa, por tanto, que todos los pasos devolvieron 0. No significa "el código es bueno": significa que ninguna de las comprobaciones automáticas que hemos decidido ejecutar ha encontrado un problema. La calidad de tu verde es exactamente la calidad de tus comprobaciones.

4.2. La metáfora de la línea de montaje

La expresión stop the line viene del sistema de producción de Toyota: cualquier operario puede detener la cadena de montaje al detectar un defecto. Parece carísimo parar una fábrica entera; resulta ser mucho más barato que dejar que el defecto avance por todas las estaciones siguientes.

En software es idéntico. Si main está roja y el equipo sigue empujando cambios encima:

Los siguientes commits se construyen sobre una base defectuosa.
Cada nueva build roja puede tener una causa distinta, y ahora hay varias mezcladas.
Nadie sabe si su cambio funciona, porque el fallo ya estaba antes.
La señal se pierde: el rojo deja de significar nada.

Esto último tiene nombre: ceguera a las alarmas. Cuando la build lleva tres días roja, el rojo ya no es información, es decorado.

4.3. El protocolo cuando la build se rompe

Un protocolo que funciona, escrito de forma explícita:

La persona que empujó el cambio es la responsable de la reparación. No por culpa: por contexto. Es quien sabe qué acaba de cambiar.
Se anuncia en el canal del equipo. "Main está roja, lo estoy mirando." Evita que tres personas depuren lo mismo en paralelo.
Nadie fusiona nada mientras tanto. Fusionar sobre una base rota es añadir variables a una ecuación que ya no cuadra.
Regla de los 10 minutos: si en diez minutos no está arreglada, se revierte el commit culpable. Revertir no es un fracaso personal; es la vía más rápida de volver a un estado conocido. El arreglo tranquilo se hace después, en una rama nueva.
Si el fallo es de una prueba inestable (flaky), no se relanza y se olvida: se anota. La política de cuarentena de pruebas inestables la veremos en la 02-04.

La trampa del "relanzar y a ver". Volver a lanzar la build hasta que salga verde es la forma más eficaz de destruir la confianza en el pipeline. Si una prueba pasa a veces, tienes un problema ahora, aunque el rojo desaparezca.

Anatomía conceptual de un workflow

Antes de escribir configuración real en la 02-02, conviene tener el modelo mental. Todas las herramientas del mercado —GitHub Actions, GitLab CI, Jenkins, CircleCI— comparten las mismas cuatro piezas, aunque las llamen distinto.

flowchart LR
    E["EVENTO<br/>push, pull_request,<br/>etiqueta, cron, manual"] --> W["WORKFLOW<br/>(pipeline)"]
    W --> J1["JOB calidad"]
    W --> J2["JOB test"]
    W --> J3["JOB build"]
    J1 --> S["STEPS<br/>pasos secuenciales<br/>dentro del job"]
    J2 --> R["RUNNER<br/>máquina limpia<br/>que ejecuta el job"]

Pieza	Qué es	Detalle importante
Evento	El hecho que dispara la ejecución	No lo lanza una persona: lo lanza algo que ha ocurrido en el repositorio
Workflow	El fichero que describe qué hacer ante ese evento	Vive dentro del repositorio, versionado junto al código
Job	Una unidad de trabajo independiente	Cada job corre en su propia máquina; por defecto, en paralelo con los demás
Step	Un paso dentro de un job	Se ejecutan en orden; si uno falla, los siguientes no se ejecutan
Runner	La máquina (normalmente un contenedor o una VM) donde corre un job	Efímera: nace limpia y muere al terminar

Tres consecuencias de este modelo que sorprenden a todo el mundo la primera vez:

Los jobs no comparten disco. Si el job build genera dist/ y el job publicar lo necesita, hay que pasárselo explícitamente (artefactos del workflow, lección 02-06). Los steps de un mismo job sí comparten el disco entre ellos.
El runner es efímero. Todo lo que instales desaparece al acabar. Por eso la caché de dependencias no es un lujo, es lo que evita reinstalar el mundo en cada ejecución (lección 02-03).
El workflow está versionado con el código. Cambiar el pipeline es un commit, se revisa en un PR y se puede revertir. Esto es pipeline as code, y lo profundizaremos en la 04-05.

En pseudocódigo, la estructura que escribiremos en la próxima lección se lee así:

CUANDO ocurra (pull_request hacia main)
  EJECUTA el job "test"
    EN una máquina Ubuntu limpia
      PASO 1: descargar el código del repositorio
      PASO 2: instalar Node 20.11.0
      PASO 3: npm ci
      PASO 4: npm test

Nada más. Todo lo que veremos en el resto del módulo son variaciones y refinamientos sobre estas cuatro líneas.

El acuerdo de equipo de Reservalia

Marta convoca a Diego y a Nuria una hora. No abren ningún editor. Salen con seis reglas escritas en el README.md del repositorio:

#	Regla	Por qué
1	Ninguna rama vive más de 2 días. Si el trabajo es mayor, se parte.	Evita el integration hell y mantiene los PR pequeños
2	Nadie empuja directamente a `main`. Todo entra por pull request.	`main` solo recibe código verificado
3	Un PR no se fusiona con el pipeline en rojo, sin excepciones ni "es que corre prisa".	Una sola excepción convierte la regla en una sugerencia
4	Main roja = prioridad máxima del equipo. A los 10 minutos sin arreglo, se revierte.	La señal solo vale si se respeta
5	El pipeline de un PR debe tardar menos de 10 minutos. Si sube, se trata como un fallo.	El feedback lento se acaba ignorando
6	Toda prueba inestable se anota y se pone en cuarentena el mismo día; no se relanza sin más.	Un verde poco fiable es peor que un rojo

Fíjate en que ninguna de las seis menciona GitHub Actions, YAML ni ningún producto. Son reglas de comportamiento; la herramienta solo servirá para que sean fáciles de cumplir y difíciles de saltarse. En la lección 02-07 traduciremos las reglas 2 y 3 en configuración técnica real (reglas de protección de rama) para que dejen de depender de la buena voluntad.

Y una expectativa realista: la CI no va a mejorar las métricas DORA de Reservalia de la noche a la mañana. Lo primero que hará será revelar problemas que ya existían pero eran invisibles: pruebas que no pasaban desde hace meses, dependencias que solo funcionan en el portátil de Diego, avisos de tipos ignorados. Las primeras dos semanas de CI suelen ser incómodas. Es la señal de que está funcionando.

Errores Comunes y Consejos

Error 1: creer que instalar la herramienta es adoptar CI. Es el error central de esta lección. Un pipeline con ramas de tres semanas es un servidor de builds caro. Antes de configurar nada, acuerda las reglas.

Error 2: normalizar la build roja. El momento exacto en que un equipo pierde la CI es la primera vez que alguien dice "sí, lleva rota desde el martes, pero es un fallo conocido". A partir de ahí, el rojo no informa de nada.

Error 3: pipelines que crecen sin control. Cada semana alguien añade un paso "por si acaso" y nadie quita ninguno. A los seis meses, el pipeline tarda 40 minutos y el equipo lo esquiva. Trata el tiempo del pipeline como un presupuesto: si quieres añadir tres minutos, busca de dónde quitarlos.

Error 4: confundir "el PR está verde" con "el código es correcto". El verde significa que ninguna de tus comprobaciones ha encontrado nada. Si no tienes pruebas para el caso del descanso a mediodía, el pipeline seguirá verde con el error dentro.

Consejo 1: empieza con un pipeline mínimo y hazlo crecer. Un workflow que solo ejecute npm ci && npm test y esté verde desde el primer día vale más que uno perfecto que nunca llega a estar en verde.

Consejo 2: haz visible el estado. Una insignia de estado en el README.md y un aviso en el canal del equipo cuando main se pone roja cuestan cinco minutos y multiplican la probabilidad de que alguien reaccione.

Consejo 3: mide el tiempo del pipeline desde el primer día. Es la métrica que más silenciosamente se degrada y la que más determina si el equipo confía en la CI.

Ejercicios

Ejercicio 1

Un equipo afirma practicar Integración Continua. Estos son los hechos observables de su última semana:

Tienen un workflow que ejecuta las pruebas en cada push.
Las ramas de funcionalidad viven entre 8 y 15 días.
La rama main lleva 4 días en rojo por una prueba "que ya se sabe que falla".
El pipeline tarda 35 minutos.
Se fusiona a main los jueves, en una sesión conjunta.

Indica, para cada una de las seis prácticas del apartado 2, si el equipo la cumple, y ordena las incumplidas por el orden en que las arreglarías.

Ejercicio 2

Diego empuja a las 17:40 un cambio en apps/api que pone main en rojo: falla una prueba de integración de disponibilidad. A las 17:55 sigue sin encontrar la causa y tiene que irse. Marta necesita fusionar un arreglo urgente para un cliente antes de las 18:30.

Describe qué debe pasar exactamente, en orden, según el acuerdo del apartado 6. Justifica la decisión clave.

Ejercicio 3

Escribe, en el pseudocódigo del apartado 5 (CUANDO / EJECUTA / EN / PASO), un workflow conceptual que, al fusionarse un PR en main, ejecute dos jobs independientes: uno que pase el lint y otro que ejecute las pruebas. Después responde: ¿podría el segundo job reutilizar los ficheros que instaló el primero? ¿Por qué?

Soluciones

Solución 1.

Práctica	¿Cumple?	Motivo
Repositorio único	Probablemente sí	Nada indica lo contrario
Integración frecuente	No	Ramas de 8-15 días e integración semanal: lo contrario de "al menos diaria"
Build automatizada en cada cambio	Sí	El workflow se dispara en cada push
`main` siempre desplegable	No	Lleva 4 días en rojo
Stop the line	No	El fallo se ha normalizado
Feedback rápido	No	35 minutos, muy por encima del umbral útil

Orden de reparación: (1) poner main en verde hoy —arreglando o revirtiendo la prueba que falla—, porque sin una señal fiable ninguna otra mejora es medible; (2) adoptar el stop the line, para que no vuelva a ocurrir; (3) reducir el tiempo del pipeline, porque mientras tarde 35 minutos el equipo tenderá a integrar poco; (4) acortar las ramas e integrar a diario, que es el cambio cultural más profundo y el que necesita apoyarse en los tres anteriores. Fusionar a diario con un pipeline lento y poco fiable es un desastre garantizado.

Solución 2. Orden correcto: (1) Diego anuncia en el canal que main está roja y que se marcha; (2) se aplica la regla de los 10 minutos, ya superados: se revierte el commit de Diego, con lo que main vuelve a verde en un par de minutos; (3) Marta abre su arreglo urgente como PR sobre la main ya sana, espera el verde y fusiona; (4) al día siguiente, Diego rehace su cambio en una rama nueva con la prueba corregida.

La decisión clave es revertir en lugar de "fusionar el arreglo urgente encima". Fusionar sobre una main roja significa que el pipeline del PR de Marta también saldrá rojo: nadie podrá distinguir si su arreglo funciona o no, y el cliente recibiría un cambio sin verificar. Revertir no juzga el trabajo de Diego: solo devuelve el sistema a un estado conocido.

Solución 3.

CUANDO ocurra (push sobre main)
  EJECUTA el job "calidad"
    EN una máquina Ubuntu limpia
      PASO 1: descargar el código
      PASO 2: instalar Node 20.11.0
      PASO 3: npm ci
      PASO 4: npm run lint
  EJECUTA el job "test"
    EN otra máquina Ubuntu limpia
      PASO 1: descargar el código
      PASO 2: instalar Node 20.11.0
      PASO 3: npm ci
      PASO 4: npm test

No, el segundo job no puede reutilizar los ficheros del primero: cada job corre en su propio runner efímero, con su propio disco, y ambos pueden ejecutarse a la vez. Por eso los dos repiten checkout y npm ci. Lo que sí evita reinstalar todo desde internet es la caché de dependencias, que veremos en la 02-03; y lo que permite pasar ficheros de un job a otro son los artefactos del workflow, materia de la 02-06.

Conclusión

Esta lección ha puesto los cimientos sobre los que se construye el resto del módulo:

La Integración Continua se sostiene sobre seis prácticas: repositorio único como fuente de verdad, integración al menos diaria en la rama principal, build automatizada en cada cambio, rama principal siempre desplegable, stop the line cuando algo se rompe y feedback en menos de diez minutos. Ninguna de las seis menciona una herramienta.
El ciclo de vida de un cambio va de la rama corta al artefacto identificado por SHA, pasando por un pipeline que se ejecuta dos veces —sobre el PR y sobre main— y por una revisión humana que llega después del verde.
Verde y rojo son códigos de salida, no opiniones. Un verde vale exactamente lo que valen tus comprobaciones, y un rojo que se normaliza deja de ser información.
La anatomía de cualquier workflow son cuatro piezas: evento, job, steps y runner. Los jobs son independientes y no comparten disco; el runner es efímero; el workflow vive versionado dentro del repositorio.
Reservalia ya tiene sus seis reglas escritas antes de tocar el YAML, y una expectativa honesta: las primeras semanas de CI van a sacar a la luz problemas que llevaban meses escondidos.

Ahora sí toca escribir configuración. En la siguiente lección, Configuración de un Entorno de CI, creamos el fichero .github/workflows/ci.yml de Reservalia desde cero y lo explicamos línea a línea: el evento que lo dispara, el runner sobre el que corre, cómo se descarga el código, cómo se fija Node 20.11.0 leyendo el .nvmrc, cómo se levanta un PostgreSQL 16.3 para las pruebas y qué hacer cuando el workflow falla y los logs no dicen nada evidente. Al terminarla, cada pull request de Reservalia se verificará solo.

Introducción a la Integración Continua