Comment configurer le CI/CD et les tests automatisés pour un monorepo React SPA

La plupart des équipes mettent en place correctement la structure du monorepo dès le premier jour, puis passent les six mois suivants à se battre avec le processus de livraison. Une disposition d’espace de travail propre ne vous protège pas des merges cassés, des minutes CI gaspillées à reconstruire des applications inchangées, ou des déploiements en production qui sautent la vérification. Ce qui compte réellement, c’est de transformer le monorepo en un système de livraison fiable avec une validation automatisée, des règles de déploiement sensibles à l’environnement et des tests de bout en bout reproductibles.

Ce tutoriel est le compagnon pratique de CI/CD pour monorepo React SPA : comment automatiser les tests et déployer uniquement ce qui a changé. Il parcourt l’ensemble du pipeline utilisé par le dépôt react-spa-monorepo-cicd : comment les pull requests sont validées, comment les vérifications sont ré-exécutées après le merge sur staging et main, comment seules les applications modifiées sont déployées, et comment les tests E2E Playwright et les vérifications de santé post-déploiement réduisent les mauvaises livraisons. À la fin, vous aurez un flux CI/CD fonctionnel de la branche de fonctionnalité à la production avec chaque porte documentée.

Avant de commencer, clonez le dépôt :

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

Étape 1 : Cartographier le flux CI/CD du monorepo React SPA

Avant de toucher à une quelconque configuration, comprenez le chemin de livraison complet. L’idée centrale de ce dépôt n’est pas « plusieurs applications dans un dossier ». C’est « plusieurs applications avec un chemin contrôlé du changement de code au déploiement ». Le pipeline détecte les changements, exécute les portes de validation, lance les tests E2E, déploie uniquement les applications modifiées et termine par une vérification de santé.

Comprendre les points de déclenchement

Le pipeline a trois points d’entrée principaux, chacun avec un objectif distinct :

1. Pull request vers main ou staging — valide le changement proposé pendant la revue de code
2. Push vers staging — re-valide le résultat du merge et déploie dans l’environnement de staging
3. Push vers main — re-valide une dernière fois et déploie en production

Les tests sont intentionnellement ré-exécutés après le merge. Une pull request valide la branche de manière isolée, mais l’état après merge peut différer en raison de conflits ou de changements simultanés d’autres contributeurs. La validation post-merge sur staging ou main garantit que le code exactement mergé passe encore toutes les portes avant tout déploiement.

Suivre le modèle de promotion par branche

Le dépôt impose un chemin de promotion linéaire :

1. Travailler sur une branche de fonctionnalité
2. Ouvrir une pull request — le CI valide le formatage, le linting, les types, les tests unitaires, le build, l’audit de sécurité et les E2E
3. Merger dans staging pour un déploiement de pré-production
4. Vérifier le déploiement staging manuellement ou avec des tests de fumée automatisés
5. Merger staging dans main pour le déploiement en production
6. Les vérifications de santé post-déploiement confirment que la livraison est en ligne et fonctionnelle

Savoir pourquoi les déploiements sélectifs comptent

Le monorepo contient trois cibles déployables : un site marketing principal statique, un admin SPA et un portail SPA. Sans détection des changements, chaque push reconstruirait et redéploierait les trois, même si un seul fichier a changé. Ce dépôt utilise la détection intelligente des changements pour qu’un commit touchant apps/admin-spa/ ne déclenche que le build et le déploiement de l’admin SPA. Les changements sous packages/, qui contient le code partagé, déclenchent les reconstructions des deux applications SPA car elles partagent ces dépendances. Le site principal est indépendant.

Vous devriez maintenant comprendre quand ce pipeline valide le code, quand il déploie et pourquoi il ré-exécute les vérifications après le merge.

Étape 2 : Exécuter le pipeline de validation complet en local

Le moyen le plus rapide de comprendre un pipeline CI/CD est de l’exécuter sur votre propre machine avant de pousser une branche. Cela garde les boucles de feedback courtes et évite de gaspiller des minutes CI sur des commits qui n’allaient jamais passer.

Installer les outils requis

Confirmez que vous avez les prérequis documentés :

node -v    # Devrait afficher v22.x
pnpm -v    # Devrait afficher 10.x ou ultérieur
docker -v  # Devrait afficher Docker version 27.x ou ultérieur

Puis installez les dépendances :

corepack enable
pnpm install

Exécuter le pipeline local

Le dépôt fournit une seule commande qui reproduit l’ensemble du flux de validation CI :

bash scripts/run-all.sh

Ce script exécute chaque étape de validation en séquence et affiche un résumé réussite/échec à la fin. C’est ce qui se rapproche le plus d’une vérification preflight locale. Si cette commande passe, vous pouvez raisonnablement avoir confiance que le CI passera aussi.

Comprendre les catégories de validation

Le pipeline impose sept catégories de vérifications, dans l’ordre :

1. Vérification du format — Prettier assure un style de code cohérent
2. Lint — ESLint détecte les problèmes de qualité de code et les bugs potentiels
3. Vérification des types — Le compilateur TypeScript vérifie la correction des types à travers tous les packages
4. Tests unitaires — Vitest exécute des tests rapides et isolés de composants et d’utilitaires
5. Build — Vite compile chaque application en assets statiques prêts pour la production
6. Audit de sécurité — L’analyse des vulnérabilités des dépendances signale les CVE connus
7. Tests E2E — Playwright exécute des tests au niveau du navigateur contre les applications compilées

Exécutez la commande complète avec succès avant de passer à la suite. Vous devriez maintenant avoir un moyen local de reproduire les mêmes catégories de vérifications que le serveur CI imposera.

Étape 3 : Configurer les portes de test automatisées

Cette étape est le cœur du pipeline. L’objectif n’est pas seulement d’avoir des jobs qui s’exécutent, mais de comprendre pourquoi ils sont ordonnés ainsi et contre quoi chaque porte protège.

Organiser les portes par objectif

Pensez aux sept portes de validation comme une échelle de test à quatre niveaux :

Les portes de feedback rapide détectent les problèmes triviaux en quelques secondes :

pnpm format:check    # Prettier formatting
pnpm lint            # ESLint code quality
pnpm typecheck       # TypeScript compiler

Les portes de confiance vérifient que le code fonctionne et produit une sortie valide :

pnpm test                # Unit tests via Vitest
pnpm build:admin-spa     # Build admin SPA
pnpm build:portal-spa    # Build portal SPA
pnpm build:main-site     # Build main site

Les portes de sécurité vérifient les vulnérabilités connues (voir Comment renforcer votre pipeline CI/CD avec Sigstore, SLSA et les SBOM pour aller plus loin avec la signature d’artefacts et la provenance) :

pnpm audit    # Dependency security scan

Les portes de livraison valident l’artefact déployé dans un environnement réaliste :

pnpm test:e2e    # Playwright browser tests

L’ordre est important. Les vérifications de format et de lint ne coûtent presque rien à exécuter. Si elles échouent, il n’y a aucune raison de passer du temps à compiler trois applications et à lancer une stack Docker pour les E2E. Échouer tôt sur les vérifications bon marché permet de ne dépenser des ressources sur les vérifications coûteuses que lorsque les bases sont déjà propres.

Mapper les commandes locales aux jobs CI

Chacune des commandes ci-dessus correspond directement à un job dans le workflow CI. Lorsque vous lisez .github/workflows/validate-and-deploy.yml ou .gitlab-ci.yml, vous verrez les mêmes scripts appelés dans le même ordre. Cet alignement entre le comportement local et CI est intentionnel — cela signifie qu’une réussite locale est un prédicteur fiable d’une réussite CI.

Savoir que les commits locaux sont aussi contrôlés

Le dépôt impose les Conventional Commits via commitlint et exécute lint-staged via les hooks pre-commit Husky. Chaque commit local exécute automatiquement Prettier et ESLint sur les fichiers indexés avant que le commit ne soit créé. Cela signifie que les problèmes de formatage et de lint sont détectés avant même que le code ne soit poussé, réduisant le bruit dans le CI.

Comprendre pourquoi les E2E viennent après le build

Les tests E2E ont besoin d’artefacts compilés pour tester. Ils ne s’exécutent pas contre un serveur de développement car les serveurs de développement se comportent différemment des builds de production — ils utilisent le remplacement de module à chaud, sautent certaines optimisations et servent les assets différemment. Exécuter les E2E contre la sortie de build réelle détecte des problèmes qui n’apparaissent que dans des conditions proches de la production.

Vous devriez maintenant avoir une échelle de test claire : vérifications statiques d’abord, validation du build ensuite, et tests au niveau du navigateur une fois que les artefacts déployables existent.

Étape 4 : Exécuter les tests E2E Playwright dans un environnement proche de la production

Les tests E2E sont la dernière couche de confiance avant le déploiement. Cette étape couvre la séquence exacte pour les exécuter en local afin que vous puissiez reproduire et déboguer les échecs sans attendre le CI.

Compiler les SPA d’abord

Les tests Playwright ont besoin de la sortie de build de production. Compilez les deux SPA avant de démarrer l’environnement de test :

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

Démarrer l’environnement de test

Le dépôt utilise Docker Compose avec nginx pour servir les applications compilées dans une topologie qui reproduit le déploiement de production :

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

Cela démarre un conteneur nginx qui sert l’admin SPA et le portail SPA aux mêmes chemins qu’ils occuperont en production. Cela signifie que les limites de routage, les chemins d’assets et la navigation inter-applications se comportent comme après un vrai déploiement.

En CI, le pipeline utilise docker/docker-compose.ci.yml comme override qui supprime l’exposition des ports et crée un réseau bridge isolé. Cela empêche les conflits de ports sur les runners partagés tout en conservant la même topologie nginx. Vous n’avez pas besoin de l’override CI lors de l’exécution en local.

Exécuter Playwright

Avec la stack Docker en cours d’exécution, exécutez la suite E2E :

pnpm test:e2e

Le répertoire e2e/ contient des tests Playwright couvrant :

• Chargement de l’application — chaque SPA déployée rend son composant racine
• Limites de routage — le routage côté client fonctionne au sein de chaque application
• Rendu du contenu — les éléments du tableau de bord comme les cartes de statistiques, les titres et le contenu des pages s’affichent correctement
• Navigation inter-applications — les liens entre l’admin SPA et le portail SPA se résolvent sans erreur
• Régression visuelle — les captures d’écran sont comparées aux références pour détecter les changements d’interface non intentionnels
• Accessibilité — les vérifications axe-core signalent les violations WCAG 2.0/2.1 AA avant le déploiement

Arrêter proprement

Après l’exécution des tests, arrêtez la stack Docker :

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

Vous devriez maintenant être capable d’exécuter le même type de validation au niveau du navigateur que le pipeline utilise avant d’autoriser un déploiement.

Étape 5 : Ajouter la détection des changements pour ne déployer que les applications concernées

Le déploiement sélectif est l’un des plus grands avantages pratiques d’un monorepo bien structuré. Sans lui, chaque push reconstruit et redéploie tout, ce qui gaspille du calcul, ralentit le feedback et augmente le rayon d’impact de chaque livraison.

Comprendre le modèle de décision de déploiement

Le dépôt mappe les changements de fichiers aux cibles de déploiement avec des règles simples :

Chemin modifié	Ce qui est déployé
apps/main-site/	Site principal uniquement
apps/admin-spa/	Admin SPA uniquement
apps/portal-spa/	Portail SPA uniquement
packages/	Les deux SPA (dépendance partagée)
docs/ ou markdown uniquement	Validation minimale, pas de déploiement

Les changements dans packages/ déclenchent le déploiement des deux SPA car ces packages sont des dépendances partagées. Un bug dans le code partagé pourrait casser l’un ou l’autre consommateur, donc les deux doivent être reconstruits et retestés. Le site principal ne dépend pas des packages partagés, il n’est donc pas affecté.

Connaître le script pivot

Le dépôt inclut scripts/changed-files.sh, qui est le point de décision pour la validation sélective et le déploiement sélectif. Le workflow CI appelle ce script pour déterminer quelles applications ont été affectées par la plage de commits actuelle, puis exécute conditionnellement uniquement les jobs de build, test et déploiement pertinents.

Vous n’avez pas besoin de modifier ce script pour suivre le tutoriel, mais comprendre qu’il existe — et qu’il est la source unique de vérité pour « ce qui a changé » — est important pour étendre le pipeline plus tard.

Reconnaître le cas métier

La logique de déploiement sélectif affecte directement trois choses qui importent aux équipes :

• Coût CI — compiler et déployer une application au lieu de trois réduit le temps de calcul proportionnellement
• Vitesse de feedback — un pipeline ciblé se termine plus vite, ce qui signifie des cycles de revue de code plus rapides
• Risque de livraison — déployer uniquement l’application modifiée réduit la surface exposée aux régressions dans du code non lié

Vous devriez maintenant comprendre comment ce dépôt évite de tout déployer à chaque changement.

Étape 6 : Configurer les règles de livraison staging et production

Cette étape montre comment la même logique de pipeline produit un comportement de déploiement différent selon la branche qui a reçu le push. Aucun code applicatif ne change entre les environnements — seuls le mode de compilation, les secrets et la cible de déploiement diffèrent.

Comprendre la séparation des environnements

Le dépôt sépare les environnements par branche :

• Branche staging — compile en mode staging, utilise les secrets de staging, déploie sur le serveur de staging
• Branche main — compile en mode production, utilise les secrets de production, déploie sur le serveur de production

Utiliser des builds spécifiques à l’environnement

Les scripts de build acceptent un argument d’environnement qui correspond à un mode Vite :

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

Chaque mode peut définir ses propres variables d’environnement (endpoints API, feature flags, clés d’analytics) via les fichiers .env.staging et .env.production. Le workflow CI passe le mode correct automatiquement en fonction de la branche qui a déclenché le pipeline.

Configurer les secrets requis

GitHub Actions et GitLab CI ont tous deux besoin des secrets suivants configurés par environnement :

Secret	Objectif
SSH_PRIVATE_KEY	Authentification pour le déploiement rsync via SSH
DEPLOY_HOST	Nom d’hôte ou IP du serveur cible
DEPLOY_PORT	Port SSH (généralement 22)
DEPLOY_USER	Utilisateur SSH sur le serveur cible
DEPLOY_MAIN_SITE_PATH	Chemin distant pour le site principal (ex. /var/www/html)
DEPLOY_ADMIN_SPA_PATH	Chemin distant pour l’admin SPA (ex. /var/www/html/admin)
DEPLOY_PORTAL_SPA_PATH	Chemin distant pour le portail SPA (ex. /var/www/html/portal)

Configurez des valeurs séparées pour staging et production afin que chaque environnement déploie sur son propre serveur ou répertoire.

Mettre en place les portes d’approbation

Pour GitHub Actions, utilisez les Environments GitHub pour contrôler le comportement de déploiement :

• Environnement staging — configurez pour un déploiement automatique après que la validation est passée. Pas d’approbation manuelle nécessaire car le staging est une étape de vérification pré-production, pas une livraison destinée aux clients.
• Environnement production — configurez avec des reviewers requis. Après que la validation est passée, le job de déploiement se met en pause et attend qu’un membre autorisé de l’équipe approuve la mise en production dans l’interface Actions.

Vous devriez maintenant voir comment la même logique de pipeline se comporte différemment selon la branche sans changer le code applicatif.

Étape 7 : Déployer, vérifier et préparer le rollback

Le déploiement n’est pas terminé quand les fichiers sont transférés avec succès. Il est terminé quand l’application cible répond correctement et que vous avez un chemin testé pour revenir à la version précédente si quelque chose ne va pas.

Comprendre le modèle de cible de déploiement

Le dépôt déploie chaque application vers un chemin distinct sur le serveur cible en utilisant rsync via SSH :

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

Chaque script de déploiement ne transfère que la sortie de build de l’application ciblée. Les autres applications sur le serveur ne sont pas touchées, c’est pourquoi le déploiement sélectif est sûr — déployer l’admin SPA ne risque pas d’écraser les fichiers du portail SPA.

Utiliser le mode dry-run avant de déployer

Les scripts de déploiement supportent un flag dry-run qui montre exactement ce que rsync transférerait sans modifier réellement le serveur distant :

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

Utilisez cela pour vérifier l’intention de déploiement avant d’autoriser le transfert de fichiers, surtout la première fois que vous configurez un nouveau chemin cible ou serveur.

Connaître le chemin de rollback

Le dépôt crée des sauvegardes horodatées avant chaque déploiement. Si un déploiement introduit un problème, revenez à la version précédente :

bash scripts/rollback-spa.sh admin-spa

Cela restaure la sauvegarde la plus récente pour l’application spécifiée. Le rollback fait partie de la conception CI/CD, pas un script d’urgence de dernière minute. Le fait que le dépôt l’inclue par défaut signifie que l’équipe s’attend à ce que des rollbacks se produisent et en a fait une opération en une seule commande.

Vérifier avec les contrôles de santé post-déploiement

Après chaque déploiement, le pipeline exécute une vérification de santé contre l’URL déployée pour confirmer que l’application répond. Un transfert de fichiers réussi ne garantit pas une application fonctionnelle — la configuration du serveur pourrait être incorrecte, les variables d’environnement pourraient manquer, ou le build pourrait avoir été créé avec le mauvais mode.

Les vérifications de santé ferment la boucle. Si la vérification échoue, le pipeline rapporte un échec même si le déploiement lui-même a réussi, donnant à l’équipe un signal immédiat pour enquêter et potentiellement effectuer un rollback.

Vous devriez maintenant comprendre le cycle de vie complet : déployer, vérifier et récupérer si nécessaire.

Problèmes de configuration courants

Les tests E2E basés sur Docker échouent en local

Symptôme : Playwright ne démarre pas proprement, ou les tests ne peuvent pas atteindre les applications.

Cause probable : Docker n’est pas en cours d’exécution, la stack de test nginx n’est pas démarrée, ou les SPA n’ont pas été compilées en premier.

Solution : Ré-exécutez dans l’ordre documenté : compilez les SPA avec pnpm build:admin-spa et pnpm build:portal-spa, démarrez Docker Compose avec docker compose -f docker/docker-compose.yml up -d, exécutez pnpm test:e2e, puis arrêtez la stack avec docker compose -f docker/docker-compose.yml down.

Un changement de package partagé n’a pas déclenché la reconstruction attendue de la SPA

Symptôme : Une mise à jour de package passe la validation, mais l’une des SPA n’a pas été reconstruite ou redéployée.

Cause probable : Les règles de détection des changements ne prennent pas correctement en compte packages/.

Solution : Vérifiez que votre pipeline mappe les changements de packages/ aux deux SPA. Le script scripts/changed-files.sh devrait traiter tout changement de fichier sous packages/ comme affectant à la fois apps/admin-spa/ et apps/portal-spa/. Vérifiez la logique du script et les déclencheurs conditionnels de jobs du workflow CI.

Le déploiement en production ne démarre jamais après que le CI est passé

Symptôme : La validation se termine avec succès, mais le job de déploiement en production reste bloqué.

Cause probable : Les règles de protection d’environnement GitHub nécessitent l’approbation d’un reviewer.

Solution : Vérifiez l’environnement de production configuré dans les paramètres de votre dépôt sous Settings > Environments > production. Approuvez le déploiement en attente dans l’interface Actions. Si personne dans l’équipe n’a la permission d’approbation, mettez à jour la liste des reviewers requis de l’environnement.

Le déploiement réussit mais l’application est cassée dans le navigateur

Symptôme : Les fichiers ont été transférés avec succès, mais l’application déployée ne se charge pas ou se comporte incorrectement.

Cause probable : Mauvais mode d’environnement (build staging déployé en production), mauvais chemin cible, ou configuration serveur obsolète comme une configuration nginx qui ne sert pas le index.html de la SPA pour les routes côté client.

Solution : Confirmez le mapping branche-environnement dans le workflow CI. Vérifiez que scripts/build-spa.sh a reçu le bon argument de mode. Vérifiez que les chemins de déploiement correspondent à la configuration nginx sur le serveur. Utilisez le flux de vérification de santé et de rollback pour récupérer pendant que vous enquêtez.

Le pipeline est trop lent après l’ajout de plus d’applications

Symptôme : Les temps CI augmentent à mesure que le monorepo croît au-delà de trois ou quatre applications.

Cause probable : La validation sélective ou le déploiement sélectif n’est pas appliqué assez agressivement. Les nouvelles applications peuvent ne pas être intégrées dans la logique de détection des changements, ce qui fait que le pipeline reconstruit tout.

Solution : Étendez scripts/changed-files.sh pour inclure le répertoire de la nouvelle application. Mappez le nouveau chemin à ses propres jobs de build et de déploiement dans le workflow CI. Le modèle existant évolue bien tant que chaque application a son propre chemin conditionnel — la clé est de garder la détection des changements au centre de la conception du pipeline.

Conclusion

Vous avez maintenant une image complète de la façon dont ce dépôt transforme un monorepo React SPA en un système de livraison. Le pipeline valide chaque pull request avec sept portes automatisées, re-valide après le merge pour détecter les problèmes d’intégration, déploie uniquement les applications affectées par chaque changement, sépare staging de la production via des règles d’environnement basées sur les branches, et ferme la boucle avec des vérifications de santé post-déploiement et un rollback en une commande.

À partir d’ici, considérez ces prochaines étapes :

• Annotez les fichiers de workflow. Lisez .github/workflows/validate-and-deploy.yml et .gitlab-ci.yml côte à côte pour voir comment la même logique de pipeline est exprimée dans les deux systèmes CI.
• Ajoutez une nouvelle application au monorepo. Créez une quatrième SPA sous apps/, intégrez-la dans scripts/changed-files.sh, et ajoutez ses cibles de build, déploiement et E2E au workflow CI. C’est le vrai test pour savoir si le modèle de déploiement sélectif passe à l’échelle.
• Renforcez le processus d’approbation. Expérimentez avec les règles de protection de branche, les exigences de signature de commits et les fichiers CODEOWNERS pour ajouter plus de structure autour de qui peut merger dans staging et main.

Les pipelines CI/CD monorepo les plus solides ne sont pas ceux qui ont le plus de jobs. Ce sont ceux où chaque porte a un objectif clair, chaque déploiement est sélectif et chaque livraison a un chemin testé pour revenir à la version précédente.

Guides connexes

• La sécurité de la chaîne d’approvisionnement logicielle à l’ère de l’IA — ajoutez la génération de SBOM et les vérifications d’intégrité des dépendances à votre pipeline
• Comment renforcer votre pipeline CI/CD avec Sigstore, SLSA et les SBOM — signez les artefacts et imposez la provenance dans vos livraisons monorepo
• Sécuriser les workflows des agents de codage IA — isolez et révisez le code généré par l’IA avant qu’il n’entre dans votre monorepo

Questions fréquentes

Ai-je besoin de Docker pour suivre ce tutoriel ?

Oui. Les tests E2E Playwright s’exécutent contre des SPA compilées servies par un conteneur nginx via Docker Compose. Docker est requis pour l’étape 4 et pour le script complet du pipeline local de l’étape 2. Si vous sautez les étapes E2E, vous pouvez compléter la configuration des portes de validation sans Docker.

Puis-je utiliser ce pipeline uniquement avec GitHub Actions, ou ai-je aussi besoin de GitLab CI ?

Vous n’avez besoin que d’un seul système CI. Le dépôt inclut à la fois .github/workflows/validate-and-deploy.yml et .gitlab-ci.yml pour que les équipes puissent choisir la plateforme qu’elles utilisent. L’architecture du pipeline est la même dans les deux — seule la syntaxe diffère.

Combien de temps prend l’exécution complète du pipeline CI ?

Sur un runner GitHub Actions typique, le pipeline complet incluant les tests E2E se termine en 3 à 6 minutes selon les applications qui ont changé. Le déploiement sélectif signifie que la plupart des pushes ne compilent et testent qu’une seule application, ce qui garde la boucle de feedback rapide.

Que se passe-t-il si une vérification de santé post-déploiement échoue ?

Le pipeline rapporte un échec même si le transfert de fichiers a réussi. Cela donne à l’équipe un signal immédiat pour enquêter. Vous pouvez ensuite exécuter le script de rollback pour restaurer la version précédente pendant que vous diagnostiquez le problème.