Aller au contenu

PD-231 — Retour d'expérience

📚 Navigation User Story | Document | | | ---------- | -- | | 📋 [Spécification](PD-231-specification.md) | | | 🛠️ [Plan d'implémentation](PD-231-plan.md) | | | ✅ [Critères d'acceptation](PD-231-acceptability.md) | | | 📝 **Retour d'expérience** | *(ce document)* | [← Retour à site-vitrine](../PD-225-epic.md) · [↑ Index User Story](index.md)

1. Résumé exécutif

La User Story PD-231 visait à automatiser le build et le déploiement du site vitrine via GitLab CI/CD et GitLab Pages, avec preview MR et validation manuelle avant production. L'implémentation initiale a été refusée en raison d'un écart BLOQUANT (absence totale de prévisualisation MR) et de plusieurs écarts majeurs (pas de validation manuelle, pipeline incomplet, scripts npm manquants). Après correction de l'ensemble des écarts, la User Story a été acceptée. Verdict : ACCEPTÉ.

2. Points fluides

  • Configuration GitLab Pages native : le job pages avec artefacts public/ fonctionne sans configuration supplémentaire
  • Structure de stages claire : build → validate → test → deploy
  • Cache CI par branche (${CI_COMMIT_REF_SLUG}) évitant les rebuilds inutiles
  • Headers de sécurité via public/_headers (CSP, X-Frame-Options, etc.)
  • Environnements GitLab (production, review/) permettant le suivi des déploiements
  • Expiration automatique des previews (7 jours) via auto_stop_in

3. Points difficiles

Difficulté Contexte
Preview MR initialement absente L'implémentation initiale ne contenait qu'un job pages sur main, sans aucun mécanisme de preview pour les MR. Cela a causé l'écart E-01 BLOQUANT.
Validation manuelle oubliée Le job pages déployait directement sans when: manual, contrevenant à l'invariant 2 qui exige une approbation avant production.
Pipeline minimaliste Un seul stage deploy au lieu de la séparation build/test prévue dans le plan.
Configuration pa11y en ESM Le format pa11y.config.js avec export default n'est pas supporté par pa11y-ci v4 ; migration vers .pa11yci.json nécessaire.

4. Hypothèses révélées tardivement

Hypothèse Découverte
pa11y-ci supporte ESM Faux — pa11y-ci v4 ne supporte pas export default. La configuration doit être en JSON (.pa11yci.json) ou CommonJS.
GitLab Pages Preview URLs La variable $CI_PAGES_URL n'est disponible que dans certains contextes ; l'URL de preview doit être construite explicitement.
_headers supporté Confirmé — GitLab Pages interprète correctement le fichier public/_headers pour les headers HTTP.

5. Invariants complexes

Invariant Difficulté
INV-1 : Déploiement auto sur main Simple avec rules: - if: $CI_COMMIT_BRANCH == "main"
INV-2 : Preview MR + validation manuelle Complexe : nécessite job séparé, environment, when: manual pour prod

6. Dette technique

Élément Description Impact
Pas de notifications Le plan prévoyait des notifications Slack en cas d'échec (.notify_failure). Non implémenté. Faible (alertes GitLab suffisantes)
Script deploy-preview.sh non créé Le plan mentionnait un script optionnel pour les previews. Géré inline dans le job. Aucun

7. Risques résiduels

Risque Probabilité Impact Mitigation
Preview non testée avant prod Faible Moyen when: manual sur job pages
Accumulation d'environnements Faible Faible auto_stop_in: 7 days + on_stop
Régression après deploy Faible Élevé Re-run pipeline sur commit précédent

8. Améliorations processus

Suggestion Bénéfice attendu
Prévoir preview dès la première itération Aurait évité l'écart E-01 BLOQUANT
Tester la configuration pa11y localement Aurait détecté l'incompatibilité ESM avant la CI
Séparer build/test/deploy dès le départ Évite le refactoring du pipeline après revue
Documenter les variables CI utilisées Facilite la maintenance et le debug

9. Enseignements clés

  1. La preview MR est un invariant critique — L'absence de preview a causé un rejet immédiat. La fonctionnalité doit être implémentée dès la première version.

  2. pa11y-ci v4 ne supporte pas ESM — Utiliser .pa11yci.json (JSON) ou .pa11ycirc au lieu de pa11y.config.js avec export default.

  3. when: manual est essentiel pour la prod — Sans validation explicite, le déploiement automatique contredit les exigences de revue avant mise en production.

  4. Le pipeline doit refléter le plan — Un pipeline à un seul stage deploy ne correspond pas à une architecture build/test/deploy. Le refactoring post-revue est coûteux.

  5. GitLab Pages est fiable — Les headers _headers, les environments, et les artefacts fonctionnent comme documenté.

Document généré le 2025-12-21