roadwave/docs/adr/022-strategie-cicd-monorepo.md

ADR-022 : Stratégie CI/CD avec Path Filters pour Monorepo

Statut : Accepté (non implémenté) Date : 2026-02-01

Contexte

RoadWave est organisé en monorepo contenant backend Go, mobile Flutter, documentation et features BDD (ADR-014). Sans optimisation, chaque commit déclencherait tous les builds (backend + mobile + docs), même si seul un composant a changé.

Problématique :

• ❌ Temps de CI/CD inutilement longs (rebuild complet ~15 min)
• ❌ Gaspillage de ressources GitHub Actions
• ❌ Ralentissement du feedback développeur
• ❌ Coûts CI/CD élevés pour changements isolés

Exemple : Modification d'un fichier markdown dans /docs déclenche les tests backend (5 min) + tests mobile (8 min) + build (2 min) alors que seule la validation docs (~30s) est nécessaire.

Décision

Workflows GitHub Actions séparés avec path filters pour rebuild sélectif basé sur les fichiers modifiés.

Alternatives considérées

Option	Optimisation	Complexité	Maintenance	Coût CI
Workflows séparés + path filters	Excellente (~70%)	Faible	Simple	Minimal
Workflow monolithique	Nulle	Très faible	Simple	Élevé
Turborepo/Nx orchestration	Bonne (~50%)	Élevée	Complexe	Moyen
Multirepo (repos séparés)	Excellente	Élevée	Complexe	Variable

Architecture

Structure Workflows

.github/workflows/
├── backend.yml    # Backend Go (tests, lint, build)
├── mobile.yml     # Mobile Flutter (tests, lint, build)
└── shared.yml     # Docs + code partagé (validation, génération)

Configuration Path Filters

Workflow Backend (backend.yml)

Déclencheurs :

• Branches : main, develop
• Chemins surveillés :
  • backend/** : Code Go, migrations, configuration
  • features/api/** : Features BDD des tests API
  • features/e2e/** : Features BDD end-to-end impliquant le backend
  • .github/workflows/backend.yml : Modifications du workflow lui-même

Jobs exécutés :

• Tests unitaires : Exécution go test sur tous les packages
• Tests d'intégration : Utilisation de Testcontainers avec PostgreSQL/PostGIS
• Tests BDD : Exécution Godog sur features api/ et e2e/
• Lint : Vérification golangci-lint
• Build : Compilation binaire production (dépend de tous les jobs précédents)

Environnement : Ubuntu latest, Go 1.21+

---

Workflow Mobile (mobile.yml)

Déclencheurs :

• Branches : main, develop
• Chemins surveillés :
  • mobile/** : Code Flutter/Dart, assets, configuration
  • features/ui/** : Features BDD des tests UI
  • features/e2e/** : Features BDD end-to-end impliquant le mobile
  • .github/workflows/mobile.yml : Modifications du workflow lui-même

Jobs exécutés :

• Tests unitaires : Exécution flutter test sur widgets et logique métier
• Tests d'intégration : Tests d'intégration Flutter (interactions UI complexes)
• Lint : Analyse statique flutter analyze
• Build Android : Compilation APK release (dépend des tests)
• Build iOS : Compilation IPA release sans codesign (dépend des tests)

Environnement :

• Tests/Lint/Build Android : Ubuntu latest
• Build iOS : macOS latest (requis pour Xcode)
• Flutter 3.16.0+

---

Workflow Shared (shared.yml)

Déclencheurs :

• Branches : main, develop
• Chemins surveillés :
  • docs/** : ADR, règles métier, documentation technique
  • shared/** : Contrats API, types partagés
  • .github/workflows/shared.yml : Modifications du workflow lui-même

Jobs exécutés :

• Validation documentation : Build MkDocs en mode strict (détecte erreurs markdown)
• Vérification liens : Validation des liens internes/externes dans documentation
• Tests code partagé : Exécution tests si du code partagé backend-mobile existe

Environnement : Ubuntu latest, Python 3.11+

---

Matrice de Déclenchement

Modification	Backend	Mobile	Shared	Temps total
backend/internal/auth/service.go	✅	❌	❌	~5 min
mobile/lib/screens/home.dart	❌	✅	❌	~8 min
features/api/authentication/*.feature	✅	❌	❌	~5 min
features/ui/audio-guides/*.feature	❌	✅	❌	~8 min
features/e2e/abonnements/*.feature	✅	✅	❌	~13 min (parallèle)
docs/adr/016-email.md	❌	❌	✅	~30s
Commit mixte (backend + mobile + docs)	✅	✅	✅	~13 min (parallèle)

Économie de temps :

• Commit backend-only : ~5 min (vs 15 min sans path filters) = 67% plus rapide
• Commit docs-only : ~30s (vs 15 min) = 97% plus rapide

Cas Particulier : Features E2E

Les tests end-to-end dans /features/e2e/ déclenchent les deux workflows (backend ET mobile) car ils testent l'intégration complète :

Exemples de features E2E :

• features/e2e/abonnements/ : Formulaire mobile → API Zitadel → API RoadWave → Mangopay → Confirmation UI
• features/e2e/error-handling/ : Perte réseau → Fallback mode offline → Reprise auto après reconnexion

Justification : Les features E2E valident le contrat backend-mobile, donc les deux doivent être testés.

---

Justification

Avantages

✅ Rebuild sélectif : changement backend → seulement backend rebuild (~5 min au lieu de 15 min)

✅ Économie de temps CI : ~70% de réduction sur commits isolés (backend-only ou mobile-only)

✅ Économie de coûts : GitHub Actions facturé à la minute → réduction proportionnelle des coûts

✅ Parallélisation : workflows indépendants exécutés en parallèle par GitHub Actions

✅ Features E2E : déclenchent backend ET mobile → cohérence end-to-end garantie

✅ Feedback rapide : développeur backend voit uniquement résultats backend (moins de bruit)

✅ Scalabilité : ajout de nouveaux composants (admin panel, worker, etc.) = nouveau workflow isolé

Inconvénients

❌ Duplication config : certains éléments (checkout, cache) dupliqués entre workflows

❌ Maintenance : 3 workflows à maintenir au lieu de 1

❌ Complexité initiale : setup plus complexe que workflow monolithique

Mitigation :

• Utiliser des composite actions pour partager la config commune
• Documentation claire dans ce ADR
• Coût initial faible (~2h setup) vs gains à long terme importants

---

Implémentation

Prérequis

• ✅ Code backend implémenté avec tests unitaires + intégration
• ✅ Code mobile implémenté avec tests Flutter
• ✅ Step definitions BDD implémentées pour api/, ui/, e2e/
• ✅ Catégorisation features BDD en /features/{api,ui,e2e} (ADR-007)

Plan d'Implémentation

Phase 1 : Setup workflows de base (~1h)

• Créer backend.yml avec jobs test + lint + build
• Créer mobile.yml avec jobs test + lint + build
• Créer shared.yml avec validation docs

Phase 2 : Configuration path filters (~30 min)

• Ajouter paths: à chaque workflow
• Tester avec commits isolés (backend-only, mobile-only, docs-only)

Phase 3 : Optimisations (~30 min)

• Ajouter caching (Go modules, Flutter dependencies, node_modules)
• Créer composite actions pour config partagée
• Ajouter badges status dans README

Effort total estimé : ~2h

Validation

Scénarios de test à valider :

1. Commit backend uniquement : Modifications dans /backend → Vérifier exécution isolée de backend.yml
2. Commit mobile uniquement : Modifications dans /mobile → Vérifier exécution isolée de mobile.yml
3. Commit features E2E : Modifications dans /features/e2e → Vérifier exécution conjointe de backend.yml ET mobile.yml
4. Commit documentation uniquement : Modifications dans /docs → Vérifier exécution isolée de shared.yml
5. Commit mixte : Modifications backend + mobile + docs → Vérifier exécution des 3 workflows en parallèle

Vérifications : Consulter l'onglet "Actions" de GitHub pour confirmer quels workflows se sont déclenchés.

---

Conséquences

Positives

• Productivité développeur : feedback 3x plus rapide sur commits isolés
• Coûts réduits : ~70% d'économie sur minutes GitHub Actions
• Meilleure expérience PR : reviews plus rapides, moins d'attente CI
• Scalabilité : facile d'ajouter nouveaux composants (worker, admin, etc.)

Négatives

• Maintenance : 3 workflows à maintenir vs 1
• Setup initial : ~2h vs ~30 min pour workflow simple
• Complexité : nécessite compréhension path filters GitHub Actions

Risques

⚠️ Faux négatifs : path filter mal configuré → test non exécuté → bug en production

Mitigation :

• Features E2E déclenchent toujours backend + mobile (safety net)
• Tests de validation dans le plan d'implémentation
• Review obligatoire des modifications de workflows

---

Références

• ADR-007 - Tests BDD et Catégorisation Features
• ADR-014 - Organisation Monorepo
• GitHub Actions - Path Filters
• Monorepo CI/CD Best Practices

---

Statut d'Implémentation

Actuel : Documenté mais non implémenté

Quand : Lors du Sprint d'implémentation backend/mobile (code production)

Pourquoi reporté : Le projet est actuellement en phase de documentation uniquement. Aucun code backend/mobile n'est implémenté, donc pas de tests à exécuter. L'implémentation CI/CD sera faite lors du développement.

Prochaines étapes :

1. Implémenter code backend avec tests
2. Implémenter code mobile avec tests
3. Implémenter step definitions BDD
4. Créer workflows CI/CD selon ce ADR
5. Valider avec commits de test