lightweight-sdk/spec/ci-cd.md

CI/CD

Workflows

Les workflows vivent dans .forgejo/workflows/ (pas .github/workflows/ — ce dernier n'est probablement pas surveillé par Forgejo Actions sur cette instance).

ci.yml

Déclenché uniquement sur pull_request vers main (pas de trigger push séparé sur la branche source : il ferait tourner la même vérification deux fois sur le même commit dès qu'une PR est ouverte — deux statuts distincts pour un seul résultat logique, et une exposition doublée aux flakys du runner). Étapes : install (--frozen-lockfile) → pnpm lint → pnpm build → pnpm test → pnpm docs:check. Ne nécessite aucun secret (les dépendances internes entre packages passent par workspace:*, résolu localement).

release.yml

Déclenché sur push vers main (typiquement après le merge d'une PR "Version Packages"). Étapes : install → build → ajout dynamique d'une ligne d'authentification dans .npmrc (jamais committée) → pnpm changeset:publish.

changeset publish est idempotent par package : il republie uniquement les packages dont la version locale n'existe pas encore sur le registre. Un push sur main sans bump de version ne publie donc rien.

Flux Changesets (versioning + publication)

1. Pendant une PR de feature, ajouter un changeset : pnpm changeset (choisir le(s) package(s) concerné(s), le type de bump, décrire le changement). Le fichier généré dans .changeset/ est commité avec la PR.
2. Quand on est prêt à publier, en local : pnpm changeset version — bump les package.json concernés et génère/met à jour leurs CHANGELOG.md.
3. Ouvrir une PR "Version Packages" avec ce résultat, la relire, la merger soi-même (jamais d'auto-merge).
4. Le merge sur main déclenche release.yml, qui publie effectivement sur le registre les packages dont la version a changé.

Pas de bot automatique type changesets/action (spécifique GitHub, incertain sur Forgejo) : le flux est volontairement manuel aux étapes 1-3.

Registre npm privé Forgejo

• URL : https://git.dev.kyuno.fr/api/packages/kyuno/npm/ (owner Forgejo = kyuno, indépendant du scope npm @lightweight-sdk — les deux ne sont pas liés).
• .npmrc (racine, committé) : @lightweight-sdk:registry=https://git.dev.kyuno.fr/api/packages/kyuno/npm/.
• Authentification : //git.dev.kyuno.fr/api/packages/kyuno/npm/:_authToken=<token> — jamais committé, injecté uniquement en CI via le secret REGISTRY_TOKEN.
• Limite connue : impossible de republier un nom+version déjà existant sur le registre (Changesets gère ça nativement en forçant un bump à chaque publication).

Secret REGISTRY_TOKEN

1. Forgejo → Settings → Applications → générer un token avec les scopes write:package + read:package.
2. L'ajouter comme secret de repo nommé REGISTRY_TOKEN sur ce repo (lightweight-sdk) — les secrets de repo ne sont pas partagés entre repos sur cette instance ; celui de watchparty ne peut pas être réutilisé tel quel.

Troubleshooting : pnpm-lock.yaml sans entrée pour un nouveau package

Si pnpm install --frozen-lockfile échoue en CI avec pnpm-lock.yaml has no importers["packages/<catégorie>/<nom>"] entry alors que pnpm install (sans --frozen-lockfile) fonctionne en local sans se plaindre : un package workspace sans aucune dependencies/devDependencies propre peut ne pas obtenir d'entrée dans le lockfile généré par pnpm 12.4.2, même après suppression complète du lockfile et réinstallation. Constaté en ajoutant @lightweight-sdk/service-registry (package.json sans champ de dépendances du tout). Remède : déclarer explicitement quelques devDependencies (ex. typescript, vitest via catalog:) même si elles seraient de toute façon hoistées depuis la racine — create-package.mjs le fait automatiquement pour tout nouveau package. Vérifier avant de pousser : pnpm install --frozen-lockfile en local doit passer, pas seulement pnpm install.

Troubleshooting : 404 sur un package scopé

Si pnpm changeset:publish échoue avec une 404 sur un nom de package scopé (@lightweight-sdk/...), la cause probable est le reverse proxy devant l'instance : npm encode le / d'un nom scopé en %2F, ce qu'Apache refuse par défaut. Vérifier AllowEncodedSlashes NoDecode dans le VirtualHost et nocanon sur la directive ProxyPass. Ce point n'a pas pu être vérifié depuis l'agent (config réseau propre à l'instance).

Pistes futures

• git push --follow-tags après changeset publish pour taguer les releases (pas fait par défaut aujourd'hui).
• Automatiser l'étape 2 du flux Changesets (PR "Version Packages" ouverte automatiquement) via un workflow workflow_dispatch ou planifié.
• Protection de branche réelle sur main côté Forgejo (l'interdiction de push direct n'est aujourd'hui que conventionnelle, via CLAUDE.md).