# 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 : 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).