Cómo configurar CI/CD y pruebas automatizadas para un monorepo React SPA

La mayoría de los equipos aciertan con la estructura del monorepo el primer día y luego pasan los siguientes seis meses luchando con el proceso de entrega. Un diseño limpio de workspace no te protege de merges rotos, minutos de CI desperdiciados reconstruyendo aplicaciones sin cambios, o despliegues a producción que omiten la verificación. La parte que realmente importa es convertir el monorepo en un sistema de entregas confiable con validación automatizada, reglas de despliegue conscientes del entorno y pruebas de extremo a extremo repetibles.

Este tutorial es el complemento práctico de React SPA Monorepo CI/CD: cómo automatizar pruebas y desplegar solo lo que cambió. Recorre el pipeline completo usado por el repositorio react-spa-monorepo-cicd: cómo se validan los pull requests, cómo las verificaciones se re-ejecutan después del merge en staging y main, cómo solo las aplicaciones que cambiaron se despliegan, y cómo las pruebas E2E con Playwright y los health checks post-despliegue reducen las entregas fallidas. Al finalizar tendrás un flujo de CI/CD funcional desde la rama de feature hasta producción con cada puerta documentada.

Antes de comenzar, clona el repositorio:

git clone https://github.com/InkByteStudio/react-spa-monorepo-cicd.git
cd react-spa-monorepo-cicd

Paso 1: Mapear el flujo de CI/CD del monorepo React SPA

Antes de tocar cualquier configuración, comprende la ruta completa de entrega. La idea central de este repositorio no es “múltiples aplicaciones en una carpeta”. Es “múltiples aplicaciones con una ruta controlada desde el cambio de código hasta el despliegue”. El pipeline detecta cambios, ejecuta puertas de validación, ejecuta pruebas E2E, despliega solo las aplicaciones que cambiaron y finaliza con un health check.

Comprender los puntos de activación

El pipeline tiene tres puntos de entrada principales, cada uno con un propósito distinto:

1. Pull request a main o staging — valida el cambio propuesto durante la revisión de código
2. Push a staging — re-valida el resultado del merge y despliega al entorno de staging
3. Push a main — re-valida una vez más y despliega a producción

Las pruebas se re-ejecutan intencionalmente después del merge. Un pull request valida la rama de forma aislada, pero el estado después del merge puede diferir debido a conflictos o cambios concurrentes de otros contribuidores. La validación post-merge en staging o main asegura que el código exacto del merge aún pasa cada puerta antes de que se despliegue algo.

Seguir el modelo de promoción por ramas

El repositorio aplica una ruta de promoción lineal:

1. Trabaja en una rama de feature
2. Abre un pull request — CI valida formato, linting, tipos, pruebas unitarias, build, auditoría de seguridad y E2E
3. Merge en staging para un despliegue de pre-producción
4. Verifica el despliegue de staging manual o con pruebas de humo automatizadas
5. Merge de staging en main para el despliegue a producción
6. Los health checks post-despliegue confirman que la entrega está activa y saludable

Saber por qué importan los despliegues selectivos

El monorepo contiene tres objetivos desplegables: un sitio principal estático de marketing, un admin SPA y un portal SPA. Sin detección de cambios, cada push reconstruiría y redesplegaría los tres, incluso si solo cambió un archivo. Este repositorio usa detección inteligente de cambios para que un commit que toca apps/admin-spa/ solo active el build y despliegue del admin SPA. Los cambios bajo packages/, que contiene código compartido, activan reconstrucciones para ambas aplicaciones SPA porque comparten esas dependencias. El sitio principal es independiente.

Ahora deberías entender cuándo este pipeline valida código, cuándo despliega y por qué re-ejecuta verificaciones después del merge.

Paso 2: Ejecutar el pipeline de validación completo localmente

La forma más rápida de entender un pipeline de CI/CD es ejecutarlo en tu propia máquina antes de hacer push de una rama. Esto mantiene los ciclos de retroalimentación cortos y evita desperdiciar minutos de CI en commits que nunca iban a pasar.

Instalar las herramientas necesarias

Confirma que tienes los prerequisitos documentados:

node -v    # Debería mostrar v22.x
pnpm -v    # Debería mostrar 10.x o posterior
docker -v  # Debería mostrar Docker version 27.x o posterior

Luego instala las dependencias:

corepack enable
pnpm install

Ejecutar el pipeline local

El repositorio proporciona un solo comando que reproduce el flujo completo de validación de CI:

bash scripts/run-all.sh

Este script ejecuta cada etapa de validación en secuencia e imprime un resumen de aprobado/fallido al final. Es lo más cercano a una verificación previa local. Si este comando pasa, puedes estar razonablemente seguro de que CI también pasará.

Comprender las categorías de validación

El pipeline aplica siete categorías de verificaciones, en orden:

1. Verificación de formato — Prettier asegura un estilo de código consistente
2. Lint — ESLint detecta problemas de calidad de código y errores potenciales
3. Verificación de tipos — el compilador de TypeScript verifica la corrección de tipos en todos los paquetes
4. Pruebas unitarias — Vitest ejecuta pruebas rápidas y aisladas de componentes y utilidades
5. Build — Vite compila cada aplicación en activos estáticos listos para producción
6. Auditoría de seguridad — el escaneo de vulnerabilidades de dependencias señala CVEs conocidos
7. Pruebas E2E — Playwright ejecuta pruebas a nivel de navegador contra las aplicaciones construidas

Ejecuta el comando completo exitosamente antes de continuar. Ahora deberías tener una forma local de reproducir las mismas categorías de verificaciones que el servidor de CI aplicará.

Paso 3: Configurar las puertas de pruebas automatizadas

Este paso es el corazón del pipeline. El objetivo no es solo tener jobs que se ejecuten, sino entender por qué están ordenados de la manera en que están y qué protege cada puerta.

Organizar las puertas por propósito

Piensa en las siete puertas de validación como una escalera de pruebas con cuatro niveles:

Puertas de retroalimentación rápida detectan problemas triviales en segundos:

pnpm format:check    # Formato con Prettier
pnpm lint            # Calidad de código con ESLint
pnpm typecheck       # Compilador de TypeScript

Puertas de confianza verifican que el código funciona y produce una salida válida:

pnpm test                # Pruebas unitarias vía Vitest
pnpm build:admin-spa     # Build del admin SPA
pnpm build:portal-spa    # Build del portal SPA
pnpm build:main-site     # Build del sitio principal

Puertas de seguridad verifican vulnerabilidades conocidas (consulta Cómo fortalecer tu pipeline de CI/CD con Sigstore, SLSA y SBOMs para ir más allá con firma de artefactos y procedencia):

pnpm audit    # Escaneo de seguridad de dependencias

Puertas de entrega validan el artefacto desplegado en un entorno realista:

pnpm test:e2e    # Pruebas de navegador con Playwright

El orden importa. Las verificaciones de formato y lint no cuestan casi nada de ejecutar. Si fallan, no hay razón para gastar tiempo construyendo tres aplicaciones y levantando un stack de Docker para E2E. Falla temprano en verificaciones baratas para que solo gastes recursos en verificaciones costosas cuando lo básico ya está limpio.

Mapear comandos locales a jobs de CI

Cada uno de los comandos anteriores se mapea directamente a un job en el workflow de CI. Cuando leas .github/workflows/validate-and-deploy.yml o .gitlab-ci.yml, verás los mismos scripts ejecutados en el mismo orden. Esa alineación entre el comportamiento local y de CI es intencional — significa que un pase local es un predictor confiable de un pase de CI.

Saber que los commits locales también están protegidos

El repositorio aplica Conventional Commits a través de commitlint y ejecuta lint-staged vía hooks pre-commit de Husky. Cada commit local ejecuta automáticamente Prettier y ESLint sobre los archivos en staging antes de crear el commit. Esto significa que los problemas de formato y lint se detectan antes de que el código se suba, reduciendo el ruido en CI.

Entender por qué E2E viene después del build

Las pruebas E2E necesitan artefactos construidos para probar. No se ejecutan contra un servidor de desarrollo porque los servidores de desarrollo se comportan de manera diferente a los builds de producción — usan hot module replacement, omiten ciertas optimizaciones y sirven activos de manera diferente. Ejecutar E2E contra la salida real del build detecta problemas que solo aparecen en condiciones similares a producción.

Ahora deberías tener una escalera de pruebas clara: verificaciones estáticas primero, validación del build segundo, y pruebas a nivel de navegador después de que existan los artefactos desplegables.

Paso 4: Ejecutar pruebas E2E con Playwright en un entorno similar a producción

Las pruebas E2E son la capa final de confianza antes del despliegue. Este paso cubre la secuencia exacta para ejecutarlas localmente para que puedas reproducir y depurar fallos sin esperar al CI.

Construir los SPAs primero

Las pruebas de Playwright necesitan la salida del build de producción. Construye ambos SPAs antes de iniciar el entorno de pruebas:

pnpm build:admin-spa
pnpm build:portal-spa

Iniciar el entorno de pruebas

El repositorio usa Docker Compose con nginx para servir las aplicaciones construidas en una topología que refleja el despliegue de producción:

docker compose -f docker/docker-compose.yml up -d

Esto inicia un contenedor nginx que sirve el admin SPA y el portal SPA en las mismas rutas que ocuparán en producción. Eso significa que los límites de rutas, las rutas de activos y la navegación entre aplicaciones se comportan de la manera en que lo harán después de un despliegue real.

En CI, el pipeline usa docker/docker-compose.ci.yml como override que elimina la exposición de puertos y crea una red bridge aislada. Esto previene conflictos de puertos en runners compartidos mientras mantiene la misma topología de nginx. No necesitas el override de CI cuando ejecutas localmente.

Ejecutar Playwright

Con el stack de Docker ejecutándose, ejecuta la suite E2E:

pnpm test:e2e

El directorio e2e/ contiene pruebas de Playwright que cubren:

• Carga de aplicación — cada SPA desplegado renderiza su componente raíz
• Límites de rutas — el enrutamiento del lado del cliente funciona dentro de cada aplicación
• Renderizado de contenido — elementos del dashboard como tarjetas de estadísticas, encabezados y contenido de página se muestran correctamente
• Navegación entre aplicaciones — los enlaces entre el admin y el portal SPA se resuelven sin errores
• Regresión visual — las capturas de pantalla se comparan contra líneas base para detectar cambios no intencionados en la UI
• Accesibilidad — las verificaciones de axe-core señalan violaciones WCAG 2.0/2.1 AA antes del despliegue

Apagar limpiamente

Después de que las pruebas completen, detén el stack de Docker:

docker compose -f docker/docker-compose.yml down

Ahora deberías poder ejecutar el mismo tipo de validación a nivel de navegador que el pipeline usa antes de permitir un despliegue.

Paso 5: Agregar detección de cambios para que solo las aplicaciones afectadas se desplieguen

El despliegue selectivo es una de las mayores ventajas prácticas de un monorepo bien estructurado. Sin él, cada push reconstruye y redespliega todo, lo que desperdicia cómputo, ralentiza la retroalimentación y aumenta el radio de impacto de cada entrega.

Comprender el modelo de decisión de despliegue

El repositorio mapea cambios de archivos a objetivos de despliegue con reglas simples:

Ruta modificada	Qué se despliega
apps/main-site/	Solo el sitio principal
apps/admin-spa/	Solo el admin SPA
apps/portal-spa/	Solo el portal SPA
packages/	Ambos SPAs (dependencia compartida)
docs/ o solo markdown	Validación mínima, sin despliegue

Los cambios en packages/ activan ambos despliegues SPA porque esos paquetes son dependencias compartidas. Un error en código compartido podría romper cualquier consumidor, por lo que ambos deben ser reconstruidos y re-testeados. El sitio principal no depende de los paquetes compartidos, por lo que no se ve afectado.

Conocer el script pivote

El repositorio incluye scripts/changed-files.sh, que es el punto de decisión tanto para la validación selectiva como para el despliegue selectivo. El workflow de CI llama a este script para determinar qué aplicaciones fueron afectadas por el rango de commits actual, luego ejecuta condicionalmente solo los jobs relevantes de build, pruebas y despliegue.

No necesitas modificar este script para seguir el tutorial, pero entender que existe — y que es la única fuente de verdad para “qué cambió” — es importante para extender el pipeline después.

Reconocer el caso de negocio

La lógica de despliegue selectivo afecta directamente tres cosas que les importan a los equipos:

• Costo de CI — construir y desplegar una aplicación en lugar de tres reduce el tiempo de cómputo proporcionalmente
• Velocidad de retroalimentación — un pipeline dirigido termina más rápido, lo que significa ciclos de revisión de código más rápidos
• Riesgo de entrega — desplegar solo la aplicación que cambió reduce la superficie para regresiones en código no relacionado

Ahora deberías entender cómo este repositorio evita desplegar todo en cada cambio.

Paso 6: Configurar reglas de entrega para staging y producción

Este paso muestra cómo la misma lógica de pipeline produce un comportamiento de despliegue diferente dependiendo de qué rama recibió el push. No cambia ningún código de aplicación entre entornos — solo difieren el modo de build, los secretos y el objetivo de despliegue.

Comprender la separación de entornos

El repositorio separa los entornos por rama:

• Rama staging — construye con modo staging, usa secretos de staging, despliega al servidor de staging
• Rama main — construye con modo producción, usa secretos de producción, despliega al servidor de producción

Usar builds específicos por entorno

Los scripts de build aceptan un argumento de entorno que se mapea a un modo de Vite:

bash scripts/build-spa.sh admin-spa staging
bash scripts/build-spa.sh admin-spa production

Cada modo puede definir sus propias variables de entorno (endpoints de API, feature flags, claves de analytics) a través de archivos .env.staging y .env.production. El workflow de CI pasa el modo correcto automáticamente basándose en la rama que activó el pipeline.

Configurar los secretos necesarios

Tanto GitHub Actions como GitLab CI necesitan los siguientes secretos configurados por entorno:

Secreto	Propósito
SSH_PRIVATE_KEY	Autenticación para despliegue con rsync sobre SSH
DEPLOY_HOST	Nombre de host o IP del servidor destino
DEPLOY_PORT	Puerto SSH (generalmente 22)
DEPLOY_USER	Usuario SSH en el servidor destino
DEPLOY_MAIN_SITE_PATH	Ruta remota para el sitio principal (ej., /var/www/html)
DEPLOY_ADMIN_SPA_PATH	Ruta remota para el admin SPA (ej., /var/www/html/admin)
DEPLOY_PORTAL_SPA_PATH	Ruta remota para el portal SPA (ej., /var/www/html/portal)

Configura valores separados para staging y producción para que cada entorno despliegue a su propio servidor o directorio.

Configurar puertas de aprobación

Para GitHub Actions, usa GitHub Environments para controlar el comportamiento de despliegue:

• Entorno de staging — configúralo para auto-desplegar después de que la validación pase. No se necesita aprobación manual porque staging es un paso de verificación de pre-producción, no una entrega al cliente.
• Entorno de producción — configúralo con revisores requeridos. Después de que la validación pase, el job de despliegue se pausa y espera a que un miembro autorizado del equipo apruebe la entrega en la UI de Actions.

Ahora deberías ver cómo la misma lógica de pipeline se comporta de manera diferente según la rama sin cambiar el código de aplicación.

Paso 7: Desplegar, verificar y prepararse para el rollback

El despliegue no está completo cuando los archivos se transfieren exitosamente. Está completo cuando la aplicación destino responde correctamente y tienes una ruta probada de vuelta a la versión anterior si algo sale mal.

Comprender el modelo de objetivo de despliegue

El repositorio despliega cada aplicación a una ruta distinta en el servidor destino usando rsync sobre SSH:

DEPLOY_MAIN_SITE_PATH=/var/www/html
DEPLOY_ADMIN_SPA_PATH=/var/www/html/admin
DEPLOY_PORTAL_SPA_PATH=/var/www/html/portal

Cada script de despliegue transfiere solo la salida del build para la aplicación objetivo. Las otras aplicaciones en el servidor no se tocan, por eso el despliegue selectivo es seguro — desplegar el admin SPA no corre el riesgo de sobrescribir los archivos del portal SPA.

Usar el modo dry-run antes de desplegar

Los scripts de despliegue soportan un flag de dry-run que muestra exactamente qué transferiría rsync sin modificar realmente el servidor remoto:

DRY_RUN=true bash scripts/deploy-spa.sh admin-spa

Usa esto para verificar la intención del despliegue antes de permitir la transferencia de archivos, especialmente la primera vez que configuras una nueva ruta destino o servidor.

Conocer la ruta de rollback

El repositorio crea backups con marca de tiempo antes de cada despliegue. Si un despliegue introduce un problema, haz rollback a la versión anterior:

bash scripts/rollback-spa.sh admin-spa

Esto restaura el backup más reciente para la aplicación especificada. El rollback es parte del diseño de CI/CD, no un script de emergencia de último momento. El hecho de que el repositorio lo incluya por defecto significa que el equipo espera que los rollbacks ocurran y los ha convertido en una operación de un solo comando.

Verificar con health checks post-despliegue

Después de cada despliegue, el pipeline ejecuta un health check contra la URL desplegada para confirmar que la aplicación está respondiendo. Una transferencia de archivos exitosa no garantiza una aplicación funcionando — la configuración del servidor podría estar mal, las variables de entorno podrían faltar, o el build podría haberse creado con el modo incorrecto.

Los health checks cierran el ciclo. Si la verificación falla, el pipeline reporta un fallo aunque el despliegue en sí haya sido exitoso, dándole al equipo una señal inmediata para investigar y potencialmente hacer rollback.

Ahora deberías entender el ciclo de vida completo: desplegar, verificar y recuperar si es necesario.

Problemas comunes de configuración

Las pruebas E2E basadas en Docker fallan localmente

Síntoma: Playwright no inicia limpiamente, o las pruebas no pueden alcanzar las aplicaciones.

Causa probable: Docker no está ejecutándose, el stack de pruebas de nginx no está levantado, o los SPAs no fueron construidos primero.

Solución: Re-ejecuta el orden documentado: construye los SPAs con pnpm build:admin-spa y pnpm build:portal-spa, inicia Docker Compose con docker compose -f docker/docker-compose.yml up -d, ejecuta pnpm test:e2e, luego detén el stack con docker compose -f docker/docker-compose.yml down.

Un cambio en un paquete compartido no activó la reconstrucción esperada del SPA

Síntoma: Una actualización de paquete pasa la validación, pero uno de los SPAs no fue reconstruido o redesplegado.

Causa probable: Las reglas de detección de cambios no están contabilizando packages/ correctamente.

Solución: Verifica que tu pipeline mapee los cambios de packages/ a ambos SPAs. El script scripts/changed-files.sh debería tratar cualquier cambio de archivo bajo packages/ como afectando tanto a apps/admin-spa/ como a apps/portal-spa/. Revisa la lógica del script y los triggers condicionales de jobs del workflow de CI.

El despliegue a producción nunca inicia después de que CI pasa

Síntoma: La validación completa exitosamente, pero el job de despliegue a producción permanece bloqueado.

Causa probable: Las reglas de protección de GitHub Environment requieren aprobación de un revisor.

Solución: Revisa el entorno de producción configurado en la configuración de tu repositorio en Settings > Environments > production. Aprueba el despliegue pendiente en la UI de Actions. Si nadie en el equipo tiene permiso de aprobación, actualiza la lista de revisores requeridos del entorno.

El despliegue tiene éxito pero la aplicación está rota en el navegador

Síntoma: Los archivos se transfirieron exitosamente, pero la aplicación desplegada no carga o se comporta incorrectamente.

Causa probable: Modo de entorno incorrecto (build de staging desplegado a producción), ruta destino incorrecta, o configuración obsoleta del servidor como una configuración de nginx que no sirve el index.html del SPA para rutas del lado del cliente.

Solución: Confirma el mapeo de rama a entorno en el workflow de CI. Verifica que scripts/build-spa.sh recibió el argumento de modo correcto. Comprueba que las rutas de despliegue coincidan con la configuración de nginx en el servidor. Usa el flujo de health check y rollback para recuperarte mientras investigas.

El pipeline es demasiado lento después de agregar más aplicaciones

Síntoma: Los tiempos de CI aumentan a medida que el monorepo crece más allá de tres o cuatro aplicaciones.

Causa probable: La validación selectiva o el despliegue selectivo no se están aplicando lo suficientemente agresivamente. Las nuevas aplicaciones podrían no estar conectadas a la lógica de detección de cambios, causando que el pipeline reconstruya todo.

Solución: Extiende scripts/changed-files.sh para incluir el directorio de la nueva aplicación. Mapea la nueva ruta a sus propios jobs de build y despliegue en el workflow de CI. El modelo existente escala bien siempre que cada aplicación tenga su propia ruta condicional — la clave es mantener la detección de cambios central al diseño del pipeline.

Conclusión

Ahora tienes una imagen completa de cómo este repositorio convierte un monorepo React SPA en un sistema de entregas. El pipeline valida cada pull request con siete puertas automatizadas, re-valida después del merge para detectar problemas de integración, despliega solo las aplicaciones afectadas por cada cambio, separa staging de producción a través de reglas de entorno basadas en ramas, y cierra el ciclo con health checks post-despliegue y rollback de un solo comando.

A partir de aquí, considera estos próximos pasos:

• Anota los archivos de workflow. Lee .github/workflows/validate-and-deploy.yml y .gitlab-ci.yml lado a lado para ver cómo la misma lógica de pipeline se expresa en ambos sistemas de CI.
• Agrega una nueva aplicación al monorepo. Crea un cuarto SPA bajo apps/, conéctalo a scripts/changed-files.sh, y agrega sus targets de build, despliegue y E2E al workflow de CI. Esta es la prueba real de si el modelo de despliegue selectivo escala.
• Refuerza el proceso de aprobación. Experimenta con reglas de protección de ramas, requisitos de firma de commits y archivos CODEOWNERS para agregar más estructura sobre quién puede hacer merge en staging y main.

Los pipelines de CI/CD de monorepo más sólidos no son los que tienen más jobs. Son aquellos donde cada puerta tiene un propósito claro, cada despliegue es selectivo, y cada entrega tiene una ruta probada de vuelta a la versión anterior.

Guías relacionadas

• Seguridad de la cadena de suministro de software en la era de la IA — agrega generación de SBOM y verificaciones de integridad de dependencias a tu pipeline
• Cómo fortalecer tu pipeline de CI/CD con Sigstore, SLSA y SBOMs — firma artefactos y aplica procedencia en tus entregas de monorepo
• Asegurando flujos de trabajo de agentes de codificación con IA — sandboxing y revisión de código generado por IA antes de que entre en tu monorepo

Preguntas frecuentes

¿Necesito Docker instalado para seguir este tutorial?

Sí. Las pruebas E2E de Playwright se ejecutan contra SPAs construidos servidos por un contenedor nginx a través de Docker Compose. Docker es necesario para el Paso 4 y para el script completo del pipeline local en el Paso 2. Si omites los pasos de E2E, puedes completar la configuración de puertas de validación sin Docker.

¿Puedo usar este pipeline solo con GitHub Actions, o también necesito GitLab CI?

Solo necesitas un sistema de CI. El repositorio incluye tanto .github/workflows/validate-and-deploy.yml como .gitlab-ci.yml para que los equipos puedan elegir la plataforma que usen. La arquitectura del pipeline es la misma en ambos — solo difiere la sintaxis.

¿Cuánto tarda en ejecutarse el pipeline completo de CI?

En un runner típico de GitHub Actions, el pipeline completo incluyendo pruebas E2E se completa en 3 a 6 minutos dependiendo de qué aplicaciones cambiaron. El despliegue selectivo significa que la mayoría de los pushes solo construyen y prueban una aplicación, lo que mantiene el ciclo de retroalimentación rápido.

¿Qué sucede si un health check post-despliegue falla?

El pipeline reporta un fallo aunque la transferencia de archivos haya sido exitosa. Esto le da al equipo una señal inmediata para investigar. Luego puedes ejecutar el script de rollback para restaurar la versión anterior mientras diagnosticas el problema.