El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència

HOME

Tancàvem el mòdul 1 amb una promesa: en Diego deixarà de compilar al seu portàtil; a partir d'aquí, cada canvi es verifica sol, en una màquina neta, abans que ningú el fusioni. Aquesta lliçó és el pas previ per complir-la. I és un pas que gairebé tothom es salta, perquè és temptador obrir directament l'editor i escriure YAML. El problema és que un fitxer de configuració no converteix un equip en un equip que practica Integració Contínua, igual que comprar unes sabatilles no converteix ningú en corredor. La CI és, abans que res, un conjunt de pràctiques i d'acords; l'eina només els fa complir. En aquesta lliçó veurem quines són aquestes pràctiques, com és el cicle de vida complet d'un canvi sota CI, què significa exactament que la build estigui "verda" o "vermella" i quina disciplina exigeix, i quina és l'anatomia conceptual d'un flux de treball. Acabarem amb les sis regles que l'equip de Reservalia acorda abans d'escriure una sola línia de configuració. A la lliçó 02-02 escriurem aquesta configuració.

Contingut

Per què les regles van abans que el YAML
Les sis pràctiques que constitueixen la Integració Contínua
El cicle de vida d'un canvi sota CI
Build verda, build vermella i la disciplina de "stop the line"
Anatomia conceptual d'un flux de treball
L'acord d'equip de Reservalia
Errors Comuns i Consells
Exercicis
Conclusió

Per què les regles van abans que el YAML

Imagina't dos equips. Tots dos tenen un pipeline idèntic: compila, passa les proves i avisa en un canal de xat.

Equip A: les branques viuen tres setmanes. Quan la build es posa vermella, ningú no la mira fins l'endemà. El canal d'avisos està silenciat perquè "sempre falla alguna cosa".
Equip B: les branques viuen mig dia. Quan la build es posa vermella, la persona que l'ha trencada deixa el que està fent. Si en deu minuts no està arreglada, reverteix el seu commit.

L'equip A té un servidor de builds. L'equip B practica Integració Contínua. El fitxer de configuració és el mateix; el que canvia és el que l'equip fa amb la informació que produeix.

Aquesta distinció és la raó de ser d'aquesta lliçó. A la 01-01 vam veure la definició formal de CI; ara desgranarem les pràctiques concretes que hi ha al darrere, perquè són elles —i no l'eina— les que produeixen els beneficis que mesurem amb les mètriques DORA de la 01-05.

Les sis pràctiques que constitueixen la Integració Contínua

2.1. Un repositori únic com a font de veritat

Tot el necessari per construir i provar el sistema viu en un sol lloc versionat: codi, proves, scripts de build, migracions de base de dades, configuració del pipeline i definició de la infraestructura.

La prova pràctica: si demà desapareixen tots els portàtils de l'equip, puc reconstruir el sistema clonant el repositori? Si la resposta conté un "bé, més un script que té en Diego a la seva carpeta de descàrregues", el repositori no és la font de veritat.

Reservalia ho compleix a mitges. El codi i les migracions són a github.com/reservalia/reservalia, però les ordres de desplegament viuen a la memòria d'en Diego. Aquest deute el saldarem al mòdul 3.

2.2. Integració freqüent a la branca principal

Cada persona integra la seva feina a main almenys un cop al dia. No és un consell d'estil: és la definició operativa de la paraula "contínua".

Recorda el diagrama de l'integration hell de la 01-01: el cost de fusionar creix de manera no lineal amb el temps que les branques viuen separades. Dues branques d'un dia es fusionen soles; dues branques de tres setmanes requereixen una tarda d'arqueologia.

Una conseqüència incòmoda: si una tasca triga cinc dies, no pots esperar cinc dies per integrar. Has d'aprendre a partir la feina en trossos que es puguin integrar sense trencar res encara que estiguin incomplets. Les tècniques per fer-ho (codi latent, feature flags) les veurem a la 03-05; de moment queda't amb la idea que integrar sovint és una habilitat, no només una norma.

2.3. Build automatitzada a cada canvi

Cada git push dispara automàticament un procés que construeix el sistema i executa les proves en una màquina neta. Sense que ningú premi res. Sense excepcions.

Les tres paraules importants són automàtica (ningú no decideix si s'executa), cada (no només abans d'una release) i neta (una màquina que parteix de zero, sense les 47 eines que en Diego té instal·lades des del 2021).

2.4. La branca principal sempre desplegable

En qualsevol moment del dia, l'últim commit de main ha de ser candidat vàlid a producció. No "gairebé a punt": desplegable.

Aquesta és la pràctica més exigent de les sis i la que més canvia la manera de treballar d'un equip, perquè prohibeix la frase "ho pujo ara i ho arreglo a la tarda". I és també la que fa possible tot el mòdul 3: si main sempre està sana, desplegar deixa de ser un esdeveniment i es converteix en un tràmit.

2.5. Si la build es trenca, l'equip para ("stop the line")

És la pràctica que més s'incompleix, i la desenvolupem a l'apartat 4. En una frase: una build vermella és un problema de l'equip, no de qui l'ha trencada, i arreglar-la té prioritat sobre qualsevol funcionalitat.

2.6. Retroalimentació ràpida

Un pipeline que triga 45 minuts no dona retroalimentació: dona un informe forense. Quan arriba la resposta, qui va fer el canvi ja és en una altra tasca i ha perdut el context.

La referència pràctica, i una de les frases que en Diego ja va deixar anar al mòdul 1 —"si el CI triga més que anar a buscar un cafè..."—, és la següent:

Temps del pipeline	Què passa a la pràctica
< 10 min	La persona espera el resultat i el corregeix en calent. Retroalimentació real.
10–20 min	Canvia de tasca; tornar-hi costa uns minuts de recontextualització.
20–40 min	S'acumulen diversos PR sense verificar; la fallada arriba barrejada amb altres canvis.
> 40 min	L'equip comença a ignorar el pipeline i a saltar-se'l "només aquesta vegada".

L'objectiu de Reservalia per al CI d'aquest mòdul serà menys de 10 minuts en un pull request típic.

El cicle de vida d'un canvi sota CI

Vegem el recorregut complet d'un canvi concret: en Diego arregla un error en el càlcul de disponibilitat que fa que dues cites es puguin solapar quan el negoci té un descans al migdia.

flowchart TD
    A["Diego crea la branca<br/>arranjament/solapament-descans"] --> B["Escriu la prova que<br/>reprodueix la fallada i falla"]
    B --> C["Corregeix el codi<br/>fins que la prova passa"]
    C --> D["Verificacio local rapida<br/>npm run lint && npm test"]
    D --> E["git push"]
    E --> F["Obre un Pull Request<br/>cap a main"]
    F --> G{"El pipeline<br/>es dispara sol"}
    G --> H["Maquina neta:<br/>checkout + installar deps"]
    H --> I["Qualitat · Proves · Build"]
    I --> J{"Tot verd?"}
    J -- No --> K["Diego corregeix<br/>i torna a empenyer"]
    K --> G
    J -- Si --> L["Revisio humana:<br/>disseny, no comes ni tabs"]
    L --> M["Merge a main"]
    M --> N["El pipeline s executa<br/>un altre cop sobre main"]
    N --> O["Artefacte publicat<br/>reservalia/api:a3f9c21"]

Hi ha quatre detalls d'aquest flux que convé subratllar:

La verificació local existeix, però és curta. En Diego no executa tot el conjunt abans d'empènyer: executa el que és ràpid (lint i proves unitàries). El que és lent ho fa la màquina. Un equip que exigeix executar-ho tot en local abans de cada push està malbaratant allò per al qual serveix el CI.

El pipeline s'executa dues vegades: una sobre el pull request i una altra sobre main després del merge. No és redundància inútil. El PR es verifica tal com estava la teva branca; després del merge, main pot contenir commits que hi han entrat mentrestant. Aquesta finestra és exactament el problema que resol la merge queue de la lliçó 02-07.

La revisió humana arriba després del verd. Ningú no hauria de revisar un PR el pipeline del qual està en vermell: és temps humà gastat en una cosa que la màquina ja sap que està malament. I com que la màquina s'ocupa del format, de l'estil i dels tipus (lliçó 02-05), la revisió humana pot parlar del que importa: si el disseny és correcte.

Del merge en surt un artefacte identificat pel SHA. El commit a3f9c21 produeix la imatge reservalia/api:a3f9c21. Aquesta traçabilitat és la matèria de la lliçó 02-06.

Build verda, build vermella i la disciplina de "stop the line"

4.1. Què significa "verd"

Un pipeline no entén de matisos: cada pas acaba amb un codi de sortida. Zero significa èxit; qualsevol altre valor, fallada. Ho pots comprovar a la teva terminal:

npm test              # executa les proves
echo $?               # imprimeix el codi de sortida de l ordre anterior
# 0  → totes van passar → pas verd
# 1  → alguna va fallar → pas vermell, el pipeline s atura aqui

"Build verda" significa, per tant, que tots els passos van retornar 0. No significa "el codi és bo": significa que cap de les comprovacions automàtiques que hem decidit executar no ha trobat cap problema. La qualitat del teu verd és exactament la qualitat de les teves comprovacions.

4.2. La metàfora de la línia de muntatge

L'expressió stop the line ve del sistema de producció de Toyota: qualsevol operari pot aturar la cadena de muntatge en detectar un defecte. Sembla caríssim aturar una fàbrica sencera; resulta ser molt més barat que deixar que el defecte avanci per totes les estacions següents.

En programari és idèntic. Si main està vermella i l'equip continua empenyent canvis a sobre:

Els commits següents es construeixen sobre una base defectuosa.
Cada nova build vermella pot tenir una causa diferent, i ara n'hi ha diverses de barrejades.
Ningú no sap si el seu canvi funciona, perquè la fallada ja hi era abans.
El senyal es perd: el vermell deixa de significar res.

Això últim té nom: ceguesa a les alarmes. Quan la build fa tres dies que és vermella, el vermell ja no és informació, és decoració.

4.3. El protocol quan la build es trenca

Un protocol que funciona, escrit de manera explícita:

La persona que va empènyer el canvi és la responsable de la reparació. No per culpa: per context. És qui sap què acaba de canviar.
S'anuncia al canal de l'equip. "Main està vermella, ho estic mirant." Evita que tres persones depurin el mateix en paral·lel.
Ningú no fusiona res mentrestant. Fusionar sobre una base trencada és afegir variables a una equació que ja no quadra.
Regla dels 10 minuts: si en deu minuts no està arreglada, es reverteix el commit culpable. Revertir no és un fracàs personal; és la via més ràpida de tornar a un estat conegut. L'arranjament tranquil es fa després, en una branca nova.
Si la fallada és d'una prova inestable (flaky), no es rellança i s'oblida: s'anota. La política de quarantena de proves inestables la veurem a la 02-04.

El parany del "rellançar i a veure". Tornar a llançar la build fins que surti verda és la manera més eficaç de destruir la confiança en el pipeline. Si una prova passa a vegades, tens un problema ara, encara que el vermell desaparegui.

Anatomia conceptual d'un flux de treball

Abans d'escriure configuració real a la 02-02, convé tenir el model mental. Totes les eines del mercat —GitHub Actions, GitLab CI, Jenkins, CircleCI— comparteixen les mateixes quatre peces, encara que les anomenin diferent.

flowchart LR
    E["ESDEVENIMENT<br/>push, pull_request,<br/>etiqueta, cron, manual"] --> W["FLUX DE TREBALL<br/>pipeline"]
    W --> J1["JOB qualitat"]
    W --> J2["JOB test"]
    W --> J3["JOB build"]
    J1 --> S["STEPS<br/>passos sequencials<br/>dins del job"]
    J2 --> R["RUNNER<br/>maquina neta<br/>que executa el job"]

Peça	Què és	Detall important
Esdeveniment	El fet que dispara l'execució	No el llança una persona: el llança una cosa que ha passat al repositori
Flux de treball	El fitxer que descriu què fer davant d'aquest esdeveniment	Viu dins del repositori, versionat al costat del codi
Job	Una unitat de treball independent	Cada job corre a la seva pròpia màquina; per defecte, en paral·lel amb els altres
Step	Un pas dins d'un job	S'executen en ordre; si un falla, els següents no s'executen
Runner	La màquina (normalment un contenidor o una VM) on corre un job	Efímera: neix neta i mor en acabar

Tres conseqüències d'aquest model que sorprenen tothom el primer cop:

Els jobs no comparteixen disc. Si el job build genera dist/ i el job publicar el necessita, cal passar-l'hi explícitament (artefactes del flux de treball, lliçó 02-06). Els steps d'un mateix job sí que comparteixen el disc entre ells.
El runner és efímer. Tot el que hi instal·lis desapareix en acabar. Per això la memòria cau de dependències no és un luxe, és el que evita reinstal·lar el món a cada execució (lliçó 02-03).
El flux de treball està versionat amb el codi. Canviar el pipeline és un commit, es revisa en un PR i es pot revertir. Això és pipeline as code, i hi aprofundirem a la 04-05.

En pseudocodi, l'estructura que escriurem a la lliçó següent es llegeix així:

QUAN passi (pull_request cap a main)
  EXECUTA el job "test"
    EN una maquina Ubuntu neta
      PAS 1: descarregar el codi del repositori
      PAS 2: installar Node 20.11.0
      PAS 3: npm ci
      PAS 4: npm test

Res més. Tot el que veurem a la resta del mòdul són variacions i refinaments sobre aquestes quatre línies.

L'acord d'equip de Reservalia

La Marta convoca en Diego i la Nuria una hora. No obren cap editor. En surten amb sis regles escrites al README.md del repositori:

#	Regla	Per què
1	Cap branca no viu més de 2 dies. Si la feina és més gran, es parteix.	Evita l'integration hell i manté els PR petits
2	Ningú no empeny directament a `main`. Tot hi entra per pull request.	`main` només rep codi verificat
3	Un PR no es fusiona amb el pipeline en vermell, sense excepcions ni "és que corre pressa".	Una sola excepció converteix la regla en un suggeriment
4	Main vermella = prioritat màxima de l'equip. Als 10 minuts sense arranjament, es reverteix.	El senyal només val si es respecta
5	El pipeline d'un PR ha de trigar menys de 10 minuts. Si puja, es tracta com una fallada.	La retroalimentació lenta s'acaba ignorant
6	Tota prova inestable s'anota i es posa en quarantena el mateix dia; no es rellança sense més.	Un verd poc fiable és pitjor que un vermell

Fixa't que cap de les sis no menciona GitHub Actions, YAML ni cap producte. Són regles de comportament; l'eina només servirà perquè siguin fàcils de complir i difícils de saltar-se. A la lliçó 02-07 traduirem les regles 2 i 3 en configuració tècnica real (regles de protecció de branca) perquè deixin de dependre de la bona voluntat.

I una expectativa realista: la CI no millorarà les mètriques DORA de Reservalia de la nit al dia. El primer que farà serà revelar problemes que ja existien però eren invisibles: proves que no passaven des de feia mesos, dependències que només funcionen al portàtil d'en Diego, avisos de tipus ignorats. Les primeres dues setmanes de CI solen ser incòmodes. És el senyal que està funcionant.

Errors Comuns i Consells

Error 1: creure que instal·lar l'eina és adoptar CI. És l'error central d'aquesta lliçó. Un pipeline amb branques de tres setmanes és un servidor de builds car. Abans de configurar res, acorda les regles.

Error 2: normalitzar la build vermella. El moment exacte en què un equip perd la CI és la primera vegada que algú diu "sí, està trencada des de dimarts, però és una fallada coneguda". A partir d'aquí, el vermell no informa de res.

Error 3: pipelines que creixen sense control. Cada setmana algú hi afegeix un pas "per si de cas" i ningú no en treu cap. Al cap de sis mesos, el pipeline triga 40 minuts i l'equip l'esquiva. Tracta el temps del pipeline com un pressupost: si vols afegir-hi tres minuts, busca d'on treure'ls.

Error 4: confondre "el PR és verd" amb "el codi és correcte". El verd significa que cap de les teves comprovacions no ha trobat res. Si no tens proves per al cas del descans al migdia, el pipeline continuarà verd amb l'error a dins.

Consell 1: comença amb un pipeline mínim i fes-lo créixer. Un flux de treball que només executi npm ci && npm test i estigui verd des del primer dia val més que un de perfecte que mai no arriba a estar en verd.

Consell 2: fes visible l'estat. Una insígnia d'estat al README.md i un avís al canal de l'equip quan main es posa vermella costen cinc minuts i multipliquen la probabilitat que algú reaccioni.

Consell 3: mesura el temps del pipeline des del primer dia. És la mètrica que es degrada més silenciosament i la que més determina si l'equip confia en la CI.

Exercicis

Exercici 1

Un equip afirma practicar Integració Contínua. Aquests són els fets observables de la seva darrera setmana:

Tenen un flux de treball que executa les proves a cada push.
Les branques de funcionalitat viuen entre 8 i 15 dies.
La branca main fa 4 dies que està en vermell per una prova "que ja se sap que falla".
El pipeline triga 35 minuts.
Es fusiona a main els dijous, en una sessió conjunta.

Indica, per a cadascuna de les sis pràctiques de l'apartat 2, si l'equip la compleix, i ordena les incomplides per l'ordre en què les arreglaries.

Exercici 2

En Diego empeny a les 17:40 un canvi a apps/api que posa main en vermell: falla una prova d'integració de disponibilitat. A les 17:55 encara no en troba la causa i se n'ha d'anar. La Marta necessita fusionar un arranjament urgent per a un client abans de les 18:30.

Descriu què ha de passar exactament, en ordre, segons l'acord de l'apartat 6. Justifica la decisió clau.

Exercici 3

Escriu, en el pseudocodi de l'apartat 5 (QUAN / EXECUTA / EN / PAS), un flux de treball conceptual que, en fusionar-se un PR a main, executi dos jobs independents: un que passi el lint i un altre que executi les proves. Després respon: podria el segon job reutilitzar els fitxers que va instal·lar el primer? Per què?

Solucions

Solució 1.

Pràctica	La compleix?	Motiu
Repositori únic	Probablement sí	Res no indica el contrari
Integració freqüent	No	Branques de 8-15 dies i integració setmanal: el contrari de "com a mínim diària"
Build automatitzada a cada canvi	Sí	El flux de treball es dispara a cada push
`main` sempre desplegable	No	Fa 4 dies que està en vermell
Stop the line	No	La fallada s'ha normalitzat
Retroalimentació ràpida	No	35 minuts, molt per sobre del llindar útil

Ordre de reparació: (1) posar main en verd avui —arreglant o revertint la prova que falla—, perquè sense un senyal fiable cap altra millora no és mesurable; (2) adoptar el stop the line, perquè no torni a passar; (3) reduir el temps del pipeline, perquè mentre trigui 35 minuts l'equip tendirà a integrar poc; (4) escurçar les branques i integrar cada dia, que és el canvi cultural més profund i el que necessita recolzar-se en els tres anteriors. Fusionar cada dia amb un pipeline lent i poc fiable és un desastre garantit.

Solució 2. Ordre correcte: (1) en Diego anuncia al canal que main està vermella i que se'n va; (2) s'aplica la regla dels 10 minuts, ja superats: es reverteix el commit d'en Diego, amb la qual cosa main torna a verd en un parell de minuts; (3) la Marta obre el seu arranjament urgent com a PR sobre la main ja sana, espera el verd i fusiona; (4) l'endemà, en Diego refà el seu canvi en una branca nova amb la prova corregida.

La decisió clau és revertir en comptes de "fusionar l'arranjament urgent a sobre". Fusionar sobre una main vermella significa que el pipeline del PR de la Marta també sortirà vermell: ningú no podrà distingir si el seu arranjament funciona o no, i el client rebria un canvi sense verificar. Revertir no jutja la feina d'en Diego: només retorna el sistema a un estat conegut.

Solució 3.

QUAN passi (push sobre main)
  EXECUTA el job "qualitat"
    EN una maquina Ubuntu neta
      PAS 1: descarregar el codi
      PAS 2: installar Node 20.11.0
      PAS 3: npm ci
      PAS 4: npm run lint
  EXECUTA el job "test"
    EN una altra maquina Ubuntu neta
      PAS 1: descarregar el codi
      PAS 2: installar Node 20.11.0
      PAS 3: npm ci
      PAS 4: npm test

No, el segon job no pot reutilitzar els fitxers del primer: cada job corre al seu propi runner efímer, amb el seu propi disc, i tots dos es poden executar alhora. Per això tots dos repeteixen checkout i npm ci. El que sí que evita reinstal·lar-ho tot des d'internet és la memòria cau de dependències, que veurem a la 02-03; i el que permet passar fitxers d'un job a un altre són els artefactes del flux de treball, matèria de la 02-06.

Conclusió

Aquesta lliçó ha posat els fonaments sobre els quals es construeix la resta del mòdul:

La Integració Contínua se sosté sobre sis pràctiques: repositori únic com a font de veritat, integració almenys diària a la branca principal, build automatitzada a cada canvi, branca principal sempre desplegable, stop the line quan alguna cosa es trenca i retroalimentació en menys de deu minuts. Cap de les sis no menciona una eina.
El cicle de vida d'un canvi va de la branca curta a l'artefacte identificat per SHA, passant per un pipeline que s'executa dues vegades —sobre el PR i sobre main— i per una revisió humana que arriba després del verd.
Verd i vermell són codis de sortida, no opinions. Un verd val exactament el que valen les teves comprovacions, i un vermell que es normalitza deixa de ser informació.
L'anatomia de qualsevol flux de treball són quatre peces: esdeveniment, job, steps i runner. Els jobs són independents i no comparteixen disc; el runner és efímer; el flux de treball viu versionat dins del repositori.
Reservalia ja té les seves sis regles escrites abans de tocar el YAML, i una expectativa honesta: les primeres setmanes de CI trauran a la llum problemes que feia mesos que estaven amagats.

Ara sí que toca escriure configuració. A la lliçó següent, Configuració d'un Entorn de CI, creem el fitxer .github/workflows/ci.yml de Reservalia des de zero i l'expliquem línia a línia: l'esdeveniment que el dispara, el runner sobre el qual corre, com es descarrega el codi, com es fixa Node 20.11.0 llegint el .nvmrc, com s'aixeca un PostgreSQL 16.3 per a les proves i què fer quan el flux de treball falla i els registres (log) no diuen res evident. En acabar-la, cada pull request de Reservalia es verificarà sol.

Introducció a la Integració Contínua