docs: add server and CI/CD guides

2026-07-19 21:09:08 +02:00
parent c8a75cb64a
commit fb3d3b5443
13 changed files with 761 additions and 73 deletions
@@ -0,0 +1,103 @@
+---
+title: Intégration continue
+description: Organiser des contrôles rapides et bloquants avec GitHub Actions.
+---
+
+Un workflow GitHub Actions est un fichier YAML placé dans `.github/workflows/`. Il contient des événements déclencheurs, des jobs et des étapes exécutées par des runners.
+
+## Exemple pour un monorepo
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  backend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: backend/package-lock.json
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+
+  docker-build:
+    runs-on: ubuntu-latest
+    needs: [backend, frontend]
+    steps:
+      - uses: actions/checkout@v6
+      - run: docker compose -f docker-compose.prod.yml build
+```
+
+Le backend et le frontend s'exécutent en parallèle. `docker-build` ne démarre que si les deux ont réussi : il joue le rôle de porte de sortie.
+
+<Callout title="Adapte les scripts au dépôt" type="info">
+  Les commandes `lint`, `test` et `build` doivent exister dans les `package.json`. Si le projet possède un fichier de version Node, utilise `node-version-file` pour garder la CI alignée avec le développement.
+</Callout>
+
+## Installer de façon reproductible
+
+`npm ci` respecte le lockfile et échoue si celui-ci n'est plus cohérent avec `package.json`. Il est préférable à `npm install` dans la CI.
+
+Le cache accélère le téléchargement des paquets, mais ne remplace pas `npm ci`. Les dépendances continuent d'être vérifiées à chaque run.
+
+## Protéger la branche principale
+
+Dans les règles de branche du dépôt :
+
+1. impose une pull request avant fusion ;
+2. rends les jobs CI obligatoires ;
+3. exige que la branche soit à jour ;
+4. empêche la fusion si un job échoue ;
+5. limite les contournements administrateur.
+
+## Garder la pipeline lisible
+
+- donne aux jobs des noms qui indiquent leur responsabilité ;
+- parallélise les contrôles indépendants ;
+- place les tests lents après les vérifications rapides ;
+- évite de dupliquer la même logique dans plusieurs workflows ;
+- conserve les rapports de test utiles au diagnostic ;
+- épingle les actions tierces à un SHA de commit dans les dépôts sensibles.
+
+## Ordre recommandé
+
+```text
+format/lint → tests unitaires → build → tests d'intégration → build Docker
+```
+
+La [documentation GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions) décrit les événements, jobs, permissions et dépendances disponibles.
+