@ferrflow/doc 7.17.0

package/docs-fr/ci/github-actions.md

@@ -0,0 +1,109 @@
+---
+title: GitHub Actions
+description: Lancer les releases FerrFlow automatiquement avec GitHub Actions.
+---
+
+## Utiliser l'action officielle
+
+La manière la plus simple d'utiliser FerrFlow dans GitHub Actions est l'action `FerrLabs/ferrflow@v5`. Elle installe le binaire et exécute `ferrflow release` automatiquement.
+
+```yaml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # requis pour pousser les tags et créer les releases
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # historique complet nécessaire pour le scan des commits
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+<aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p><code>fetch-depth: 0</code> est requis. Sans cela, FerrFlow ne peut pas trouver les tags précédents et traitera chaque commit comme nouveau.</p>
+</div></aside>
+
+## Permissions
+
+FerrFlow a besoin de `contents: write` pour :
+
+- Pousser les commits de bump de version
+- Créer et pousser les tags git
+- Créer les GitHub Releases
+
+Si votre repository a des règles de protection de branche, créez un token dédié avec les permissions nécessaires et passez-le via `FERRFLOW_TOKEN` ou configurez l'input `token` de l'action.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Vous préférez ne pas gérer de token ? Mettez <code>bot: true</code> pour attribuer les releases à <code>ferrflow[bot]</code> sans aucun secret : voir le guide <a href="/fr/docs/ci/hosted-bot">Bot hébergé</a>.</p>
+</div></aside>
+
+## Accéder à la sortie de la release
+
+L'action expose la nouvelle version en output que vous pouvez utiliser dans les étapes suivantes :
+
+```yaml
+- uses: FerrLabs/ferrflow@v5
+  id: ferrflow
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+- name: Build Docker image
+  if: steps.ferrflow.outputs.version != ''
+  run: |
+    docker build -t myimage:${{ steps.ferrflow.outputs.version }} .
+    docker push myimage:${{ steps.ferrflow.outputs.version }}
+```
+
+## Skip CI sur les commits de release
+
+FerrFlow ajoute `[skip ci]` dans le message des commits de version par défaut pour éviter les boucles infinies. Aucune configuration supplémentaire nécessaire.
+
+## Commentaires de preview sur les PR
+
+FerrFlow peut poster un commentaire sur chaque pull request montrant quelles versions seront bump\u00e9es au merge. Le commentaire est mis \u00e0 jour automatiquement \u00e0 chaque push.
+
+```yaml title=".github/workflows/preview.yml"
+name: FerrFlow Preview
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: FerrLabs/ferrflow@v5
+        with:
+          mode: preview
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Si aucun changement publiable n'est d\u00e9tect\u00e9, le commentaire l'indique.
+
+## Exemple monorepo
+
+Dans un monorepo, FerrFlow publie chaque package modifi\u00e9 en une seule ex\u00e9cution :
+
+```yaml
+- uses: FerrLabs/ferrflow@v5
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+# Cr\u00e9e api@v1.3.0 et site@v0.5.1 en une seule \u00e9tape si les deux ont chang\u00e9
+```

package/docs-fr/ci/gitlab-ci.md

@@ -0,0 +1,77 @@
+---
+title: GitLab CI
+description: Lancer les releases FerrFlow automatiquement avec GitLab CI.
+---
+
+## Utiliser l'image Docker
+
+L'image Docker officielle FerrFlow embarque le binaire et peut être utilisée directement comme image de job GitLab CI.
+
+```yaml
+release:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  stage: release
+  script:
+    - ferrflow release
+  variables:
+    GITLAB_TOKEN: $CI_JOB_TOKEN
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+      when: on_success
+```
+
+<aside class="ferr-aside ferr-aside--warning"><div class="ferr-aside__body"><p>Assurez-vous que votre runner CI clone avec l&#39;historique complet. Ajoutez <code>GIT_DEPTH: 0</code> aux variables du job pour désactiver le clonage superficiel.</p>
+</div></aside>
+
+## Historique complet
+
+```yaml
+release:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  variables:
+    GIT_DEPTH: 0 # historique complet : requis pour le scan des tags
+    GITLAB_TOKEN: $CI_JOB_TOKEN
+  script:
+    - ferrflow release
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+## Utiliser un deploy token
+
+Si `CI_JOB_TOKEN` n'a pas les permissions pour pousser des tags, créez un deploy token de projet avec l'accès `write_repository` et stockez-le comme variable CI :
+
+```yaml
+release:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  variables:
+    GIT_DEPTH: 0
+    GITLAB_TOKEN: $FERRFLOW_DEPLOY_TOKEN # variable CI avec accès write_repository
+  script:
+    - ferrflow release
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"
+```
+
+## Commentaires de preview sur les MR
+
+FerrFlow peut poster un commentaire sur chaque merge request montrant quelles versions seront bump\u00e9es au merge. Le commentaire est mis \u00e0 jour automatiquement \u00e0 chaque push.
+
+```yaml title=".gitlab-ci.yml"
+ferrflow-preview:
+  image: ghcr.io/ferrlabs/ferrflow:latest
+  stage: test
+  variables:
+    GIT_DEPTH: 0
+    GITLAB_TOKEN: $CI_JOB_TOKEN
+  script:
+    - ferrflow check --comment
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+```
+
+Si aucun changement publiable n'est d\u00e9tect\u00e9, le commentaire l'indique.
+
+## GitLab Releases
+
+Lorsque `GITLAB_TOKEN` est d\u00e9fini, FerrFlow cr\u00e9e une GitLab Release avec le changelog g\u00e9n\u00e9r\u00e9 comme notes de release, de la m\u00eame mani\u00e8re que l'int\u00e9gration GitHub.

package/docs-fr/ci/hosted-bot.md

@@ -0,0 +1,82 @@
+---
+title: Bot hébergé (ferrflow[bot])
+description: Publier des releases sous l'identité ferrflow[bot] sans aucun secret, grâce à la GitHub App hébergée de FerrFlow et à l'échange de token OIDC.
+---
+
+Par défaut, les releases et les tags que FerrFlow pousse sont attribués au propriétaire du token présent dans votre workflow : généralement un personal access token, si bien que les releases apparaissent sous _votre_ compte. Le bot hébergé permet à la place d'attribuer les releases à **`ferrflow[bot]`**, avec une identité propre et cohérente sur tous vos repos.
+
+Le principe est celui de Renovate ou Dependabot :
+
+- **Zéro secret** dans votre workflow : aucun PAT à créer, stocker ou faire tourner.
+- Releases attribuées à **`ferrflow[bot]`**.
+- **Tokens courts et scopés** : chaque run reçoit un token neuf qui expire au bout d'une heure et est limité à un seul repository.
+
+## 1. Installer l'app
+
+Rendez-vous sur **[github.com/apps/ferrflow](https://github.com/apps/ferrflow)**, cliquez sur **Install**, puis choisissez l'organisation et les repositories que FerrFlow doit pouvoir publier. C'est tout : aucun secret à créer.
+
+L'app ne demande que **Contents** (lecture et écriture, pour pousser les tags et créer les releases) et **Metadata** (lecture). Vous pouvez la revoir ou la désinstaller à tout moment depuis les réglages de votre organisation.
+
+## 2. L'activer dans votre workflow
+
+Ajoutez `bot: true` à l'action et accordez au workflow la permission d'émettre un token OIDC :
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # permet au runner de prouver l'identité du repo à FerrFlow
+      contents: read # pour le checkout ; le push de la release utilise le token du bot
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # l'historique complet est nécessaire à l'analyse des commits
+
+      - uses: FerrLabs/FerrFlow@v5
+        with:
+          bot: true
+```
+
+`permissions.id-token: write` est obligatoire. C'est ce qui permet au runner de demander le token OIDC prouvant quel repository appelle. Sans cette permission, FerrFlow s'arrête avec une erreur claire plutôt que de se rabattre silencieusement sur autre chose.
+
+## Comment ça marche
+
+Aucun secret ne quitte jamais votre repository. Chaque run échange une preuve d'identité contre un token :
+
+1. Le runner GitHub Actions émet un **token OIDC** court décrivant votre repository (audience `ferrflow.ferrlabs.com`).
+2. FerrFlow envoie ce token à **`api.ferrflow.com`**, qui le vérifie contre les clés publiques de GitHub.
+3. Le service signe un **token d'installation scopé** pour l'app FerrFlow sur votre repo (avec une clé privée qui ne quitte jamais le KMS de FerrLabs) et le renvoie. Le token vit une heure.
+4. FerrFlow utilise ce token pour pousser tags, commits et releases : attribués à `ferrflow[bot]`.
+
+## Modèle de sécurité
+
+- **La clé privée de l'app ne quitte jamais les serveurs de FerrLabs** : elle réside dans un KMS et ne sert qu'à signer des tokens d'installation côté serveur.
+- **Votre identité est prouvée par OIDC, pas par un secret partagé** : rien de sensible n'est stocké dans votre repo ni transmis depuis celui-ci.
+- **Les tokens sont minimaux et éphémères** : limités à un seul repository, expirant au bout d'une heure.
+- **Vous gardez le contrôle** : désinstallez l'app à tout moment pour révoquer immédiatement tout accès.
+
+## Dépannage
+
+FerrFlow ne se rabat jamais en silence : si le mode bot ne peut pas obtenir de token, il échoue avec un message nommant la cause exacte.
+
+| Message                                                           | Cause et correctif                                                                                                   |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `bot mode requires permissions: id-token: write in your workflow` | Le job n'a pas `permissions.id-token: write`. Ajoutez-le (voir ci-dessus).                                           |
+| `FerrFlow App not installed on this repository's owner`           | Installez l'app sur [github.com/apps/ferrflow](https://github.com/apps/ferrflow) pour cette org / ce repo.           |
+| `FerrFlow hosted bot rate limit hit (429)`                        | Les demandes de token sont limitées par repository. Réessayez sous peu, ou utilisez un PAT via `token:` pour ce run. |
+| `FerrFlow hosted bot service unavailable`                         | Incident temporaire du service. Consultez [status.ferrlabs.com](https://status.ferrlabs.com) ou réessayez.           |
+
+## Alternatives
+
+Le bot hébergé est la voie recommandée, mais ce n'est pas la seule :
+
+- **`token:` avec un PAT** : fournissez votre propre [personal access token](/fr/docs/ci/github-actions). Les releases sont attribuées au propriétaire de ce token. Fonctionne partout, y compris hors GitHub Actions.
+- **`token:` avec votre propre GitHub App** : si vous préférez faire tourner votre propre identité de bot, passez un token émis par votre app.
+- **`GITHUB_TOKEN` par défaut** : l'option la plus simple, mais notez que les push effectués avec `GITHUB_TOKEN` **ne déclenchent pas les workflows en aval** (un push de tag ne lancera donc pas un job de publish séparé). Le bot hébergé et les PAT n'ont pas cette limite.

package/docs-fr/ci/pipeline-triggers.md

@@ -0,0 +1,238 @@
+---
+title: Triggers de pipeline
+description: Choisir la bonne strategie de declenchement CI pour vos releases FerrFlow.
+---
+
+FerrFlow fonctionne avec n'importe quelle strategie de declenchement CI. Cette page couvre les patterns les plus courants, quand les utiliser, et comment ils interagissent avec `releaseCommitMode`.
+
+## Push sur main
+
+La configuration la plus simple : executer `ferrflow release` a chaque push sur la branche par defaut. FerrFlow determine si une release est necessaire en se basant sur les commits depuis le dernier tag.
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FERRFLOW_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.FERRFLOW_TOKEN }}
+```
+
+**Quand l'utiliser :** La plupart des projets. Simple, previsible, entierement automatise.
+
+**Compromis :** Chaque push sur main declenche un workflow, meme si aucune release n'est necessaire. FerrFlow se termine rapidement quand il n'y a pas de commits a releaser.
+
+**Compatible avec :** `releaseCommitMode: commit` (par defaut) ou `none`.
+
+## Declenchement par tag
+
+Executez votre pipeline de build/deploiement quand FerrFlow cree un nouveau tag. Cela separe l'etape de release (tagging) des etapes en aval (build, publication, deploiement).
+
+```yaml title=".github/workflows/build.yml"
+name: Build & Publish
+
+on:
+  push:
+    tags:
+      - 'v*' # single-repo: v1.2.0
+      - '*@v*' # monorepo: api@v1.2.0, site@v0.5.1
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Extraire la version du tag
+        id: version
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG##*v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Build
+        run: echo "Building version ${{ steps.version.outputs.version }}"
+```
+
+**Quand l'utiliser :** Quand vous voulez decoupler le versioning du build/deploiement. Courant pour les builds Docker, la publication npm ou les releases binaires.
+
+**Compromis :** Necessite deux workflows : un pour la release (push-to-main) et un pour le build en aval (tag-triggered). Ajoute quelques secondes de latence.
+
+### Monorepo : builds par package
+
+Dans un monorepo, utilisez les patterns de tags pour ne builder que le package concerne :
+
+```yaml title=".github/workflows/build.yml"
+name: Build Package
+
+on:
+  push:
+    tags:
+      - 'api@v*'
+      - 'site@v*'
+
+jobs:
+  build-api:
+    if: startsWith(github.ref_name, 'api@v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: echo "Building API ${{ github.ref_name }}"
+
+  build-site:
+    if: startsWith(github.ref_name, 'site@v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: echo "Building site ${{ github.ref_name }}"
+```
+
+<aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p>Si FerrFlow release plusieurs packages en une seule execution (ex: <code>api@v1.3.0</code> et <code>site@v0.5.1</code>), chaque tag declenche son propre workflow. Les builds s&#39;executent en parallele automatiquement.</p>
+</div></aside>
+
+## Declenchement par release
+
+Executez un pipeline quand une GitHub Release est publiee. Fonctionne bien avec le flag `--draft` de FerrFlow : FerrFlow cree une release brouillon, vous la reviewez, puis la publication declenche le build.
+
+```yaml title=".github/workflows/deploy.yml"
+name: Deploy
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Deploy
+        run: echo "Deploying ${{ github.event.release.tag_name }}"
+```
+
+**Quand l'utiliser :** Quand vous voulez une etape de revue manuelle avant le deploiement. Creez des releases brouillon avec `ferrflow release --draft`, reviewez le changelog, puis publiez.
+
+**Compromis :** Ajoute une etape manuelle. La release brouillon doit etre publiee avant que le deploy ne se lance.
+
+## Manuel (workflow_dispatch)
+
+Declenchez une release a la demande avec un flag dry-run optionnel.
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: 'Dry run (pas de tags, pas de commits, pas de releases)'
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FERRFLOW_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v5
+        with:
+          args: ${{ inputs.dry_run == true && '--dry-run' || '' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.FERRFLOW_TOKEN }}
+```
+
+**Quand l'utiliser :** Equipes qui preferent des decisions de release explicites. Aussi utile comme workflow secondaire pour des releases ad-hoc.
+
+## Base sur une PR
+
+Utilisez `releaseCommitMode: pr` pour que FerrFlow ouvre une pull request avec le bump de version au lieu de committer directement.
+
+```yaml title="ferrflow.json"
+{ 'workspace': { 'releaseCommitMode': 'pr' } }
+```
+
+```yaml title=".github/workflows/release.yml"
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    if: "!startsWith(github.event.head_commit.message, 'chore(release):')"
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.FERRFLOW_TOKEN }}
+
+      - uses: FerrLabs/ferrflow@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.FERRFLOW_TOKEN }}
+```
+
+**Quand l'utiliser :** Quand vous voulez reviewer les bumps de version, ou quand la protection de branche empeche les push directs sur main.
+
+## Securite de concurrence
+
+Depuis la v5.2, `ferrflow release` acquiert `.git/ferrflow.lock` de maniere atomique (`O_CREAT|O_EXCL`) au debut de chaque execution mutante. Une seconde invocation concurrente sur le meme depot echoue immediatement avec une erreur claire au lieu de courir contre les refs git. Le scenario classique est une release declenchee manuellement qui demarre en meme temps qu'un `auto-release` planifie en cron, ce qui produit des jeux de tags poussés à moitié, des refus non fast-forward ou des draft releases dupliquees.
+
+Rien à brancher. Le verrou est automatique sur chaque invocation `release`. Les commandes en lecture seule (`check`, `status`, `version`, `tag`) ne le prennent pas.
+
+Si une execution précédente a planté sans relacher le verrou, l'invocation suivante le reprend automatiquement apres 30 minutes (l'hote + le PID inscrits dans le lockfile permettent à FerrFlow de detecter les verrous orphelins). Pour le reprendre plus tot, supprimez `.git/ferrflow.lock` à la main.
+
+<aside class="ferr-aside ferr-aside--note"><div class="ferr-aside__body"><p>Le verrou est par-depot, scope a <code>.git/</code>. Il ne protege pas entre des clones separes du meme depot : si vous lancez des releases simultanees depuis deux runners differents contre deux checkouts du meme remote, le verrou ne voit pas l&#39;autre cote. Utilisez un seul runner de release, ou serialisez au niveau CI (<code>concurrency:</code> dans GitHub Actions, <code>interruptible: false</code> dans GitLab).</p>
+</div></aside>
+
+## Reprise apres crash
+
+Une release enchaine plusieurs etapes a effet de bord : ecriture des fichiers de version → commit → tag → push du commit → push des tags → creation des GitHub Releases → execution des hooks `post_publish`. Si le process meurt entre l'une d'elles (coupure reseau, arret du runner, SIGKILL), le depot reste dans un etat de release partiel.
+
+Depuis la v5.3, FerrFlow ecrit `.git/ferrflow.checkpoint.json` apres chaque phase reussie. La prochaine invocation `ferrflow release` sur le meme commit reprend a la phase enregistree et saute le travail deja fait : utile a l'echelle CI ou les pannes transitoires sont la norme. Le checkpoint est efface automatiquement quand la release se termine sans erreur.
+
+Deux garde-fous :
+
+- Verrouillage HEAD : le checkpoint enregistre le SHA du commit sur lequel la release tournait. Si vous avancez HEAD entre deux runs, FerrFlow refuse de reprendre et vous demande soit de revenir au commit enregistre, soit de supprimer le checkpoint manuellement. Ca evite de rejouer d'anciens tags sur un graphe de commits different.
+- Idempotence : les operations git et forge sous-jacentes sont deja idempotentes (pousser un tag deja pousse est un no-op, creer une release qui existe deja la reutilise), donc un crash en milieu de phase recupere proprement au run suivant.
+
+Pour repartir de zero apres un crash dont vous ne voulez pas reprendre l'etat, supprimez `.git/ferrflow.checkpoint.json` a la main.
+
+## Resume
+
+| Trigger           | Automatique | Gate de revue | Ideal pour                    |
+| ----------------- | ----------- | ------------- | ----------------------------- |
+| Push sur main     | Oui         | Non           | La plupart des projets        |
+| Tag-triggered     | Oui         | Non           | Build/deploy decouples        |
+| Release-triggered | Non         | Oui           | Brouillon, revue, publication |
+| Manuel            | Non         | Oui           | Cadence de release controlee  |
+| Base sur PR       | Partiel     | Oui           | Protection de branche / revue |