CI/CD

Objet et périmètre¶

Cette politique définit les standards techniques, processus et workflows pour le développement, l'intégration continue et le déploiement de SalamBot. Elle s'applique à tous les contributeurs et maintient la cohérence technique du projet.

Périmètre : Repository principal salambot, packages, services, infrastructure et documentation.

Toolchain et versions figées¶

Baseline technique obligatoire¶

Configuration dans workflows GitHub Actions¶

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm
- uses: pnpm/action-setup@v4
  with:
    version: 10
- run: pnpm install --frozen-lockfile

Structure des workspaces¶

Le projet utilise pnpm workspaces avec l'organisation suivante (définie dans pnpm-workspace.yaml) :

Note : Les structures apps/ et services/ coexistent selon les besoins du projet. Référence canonique : pnpm-workspace.yaml.

Modèle de branches¶

Structure des branches¶

• main : Production, protégée, squash-merge uniquement
• develop : Intégration continue (optionnel selon équipe)
• feature/* : Nouvelles fonctionnalités
• fix/* : Corrections de bugs
• chore/* : Maintenance, refactoring, deps
• hotfix/* : Corrections critiques en production
• docs/* : Documentation uniquement

Règles de protection main¶

• Review obligatoire (1+ approbation)
• Check requis : QA (aggregate) ✅
• Squash-merge forcé
• Suppression automatique des branches mergées
• Aucun bypass admin autorisé

Conventional Commits¶

Format obligatoire¶

<type>(<scope>): <description>

[body optionnel]

[footer optionnel]

Types standards¶

Breaking changes¶

feat(api)!: migrate to v2 endpoints

BREAKING CHANGE: /v1/generate endpoint removed, use /v2/generate

Règles de Pull Request¶

Template PR obligatoire¶

Chaque PR doit utiliser le template .github/PULL_REQUEST_TEMPLATE.md avec :

• Type : feat/fix/chore/docs/refactor
• Description : Résumé des changements
• Tests : Couverture, scénarios validés
• Breaking changes : Impact sur l'API
• Checklist : Lint, build, tests passés

Auto-merge autorisé¶

Uniquement pour ces types de PR :

1. "Version Packages" (Changesets) - Release automation
2. "dependencies" (Dependabot) - Mises à jour de dépendances

Conditions :

• ✅ Check QA (aggregate) en SUCCESS
• ✅ Aucun conflit
• ✅ Review automatique ou humaine selon le type

Workflow de review¶

flowchart TD
  A[PR ouverte] --> B[Jobs lint/typecheck/test]
  B --> C{QA aggregate}
  C -- vert --> D{Type de PR ?}
  D -- Version Packages --> E[Auto-merge squash]
  D -- dependencies --> E
  D -- autre --> F[Review humaine / Supervisor]
  C -- rouge --> G[Label blocked + commentaire + update-branch]

Labels standards¶

Le projet utilise des labels standardisés pour la classification des PR et issues, synchronisés automatiquement via le workflow sync-labels.yml :

# .github/labels.yml
- name: release
  color: '8a2be2'
  description: 'Version/Release automation'
- name: blocked
  color: 'fc1429'
  description: 'Blocked by failing CI or policy'
- name: dependencies
  color: '0366d6'
  description: 'Dependabot or dependency bump'

Application automatique :

• release : PR Changesets "Version Packages"
• blocked : Check QA (aggregate) en échec
• dependencies : PR Dependabot

CI: Jobs standards¶

Pipeline principal (.github/workflows/ci.yml)¶

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - run: pnpm install --frozen-lockfile
      - run: pnpm -w lint

  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - run: pnpm install --frozen-lockfile
      - run: pnpm -w typecheck

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - run: pnpm install --frozen-lockfile
      - run: pnpm -w test

Gate CI — QA (aggregate)¶

jobs:
  qa_aggregate:
    name: QA (aggregate)
    if: always()
    needs: [lint, typecheck, test]
    runs-on: ubuntu-latest
    steps:
      - name: Résumé checks
        env:
          NEEDS_JSON: ${{ toJson(needs) }}
        run: |
          echo "$NEEDS_JSON" | jq .
          FAILS=$(echo "$NEEDS_JSON" | jq -r \
            'to_entries | map(select(.value.result != "success")) | length')
          if [ "$FAILS" -gt 0 ]; then exit 1; fi

Importance : Ce job est le seul check requis pour merger. Son nom exact "QA (aggregate)" est référencé dans tous les workflows d'auto-merge.

Maintenance automatisée¶

Dependabot (hebdomadaire)¶

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: '/'
    schedule:
      interval: weekly
      day: monday
      time: '09:00'
    open-pull-requests-limit: 5
    reviewers: ['salambot-team']
    labels: ['dependencies']

Workflow de nettoyage hebdomadaire¶

Nettoyage automatique des branches mergées :

# cleanup-branches.yml (exemple)
name: Cleanup merged branches
on:
  schedule: [{ cron: '17 3 * * 1' }]
  workflow_dispatch:

permissions:
  contents: write

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cli/gh-actions@v2
      - name: Delete merged branches except protected/default
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          DEFAULT=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
          PROTECTED=$(gh api repos/${GITHUB_REPOSITORY}/branches?protected=true \
             --paginate -q '.[].name')
          EXCLUDE="$DEFAULT $PROTECTED"
          gh api repos/${GITHUB_REPOSITORY}/branches?per_page=100 --paginate \
            -q '.[] | select(.commit != null) | .name' | while read BR; do
              if echo "$EXCLUDE" | grep -qx "$BR"; then continue; fi
              MERGED=$(gh pr list --head "$BR" --state merged \
                 --json number -q 'length')
              if [ "$MERGED" -gt 0 ]; then
                gh api -X DELETE \
                  repos/${GITHUB_REPOSITORY}/git/refs/heads/$BR || true
              fi
            done

Exécution : Tous les lundis à 03:17 UTC + déclenchement manuel.

Changesets et releases¶

Configuration¶

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "restricted",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

Workflow release¶

1. Développeur : Ajoute changeset avec pnpm changeset
2. CI : Crée PR "Version Packages" automatiquement
3. Auto-merge : Si QA (aggregate) ✅
4. Release : Publication automatique sur merge

Agents et permissions¶

SalamCoreBuilder¶

• Scope : Code, architecture, CI/CD
• Permissions : Création PR, auto-merge autorisé
• Responsabilités : Implémentation, tests, workflows

SalamBot Supervisor¶

• Scope : Review, validation, release
• Permissions : Approbation PR, merge manuel
• Responsabilités : Qualité, conformité, décisions techniques

DocScribe¶

• Scope : Documentation, guides, policies
• Permissions : Édition docs/, validation markdown
• Responsabilités : Cohérence doc, liens, standards

Checklists¶

Avant PR¶

• [ ] pnpm -w lint ✅
• [ ] pnpm -w build ✅
• [ ] pnpm -w test ✅
• [ ] Conventional commit format
• [ ] Template PR complété
• [ ] Tests ajoutés si nouvelle fonctionnalité
• [ ] Documentation mise à jour si API change

Après merge¶

• [ ] Check QA (aggregate) passé
• [ ] Branche source supprimée
• [ ] Changeset ajouté si release nécessaire
• [ ] Labels appropriés appliqués
• [ ] Notifications équipe si breaking change

Dépannage¶

Check QA (aggregate) en échec¶

• Logs détaillés dans Actions → job QA (aggregate)
• Vérifier les outputs des jobs individuels

Liens connexes¶

• Principes d'ingénierie
• Guide qualité global
• Architecture technique
• API Reference

Dernière mise à jour : 2025-08-29T10:55:50Z Propriétaire : Engineering Team
Statut : Stable — Application obligatoire