@ferrflow/doc 7.17.0

package/docs-fr-v5/reference/errors.md

@@ -0,0 +1,378 @@
+---
+title: Codes d'erreur
+description: "R\u00e9f\u00e9rence des codes d'erreur FerrFlow avec causes et solutions."
+---
+
+Quand FerrFlow rencontre une erreur, il affiche un code comme `error[E2001]` avec un lien vers cette page. Utilisez le code pour trouver la cause et la solution.
+
+## Erreurs de configuration
+
+### E1001 : Fichier de config introuvable
+
+<span id="e1001"></span>
+
+Le fichier de config indiqu\u00e9 via `--config` n'existe pas.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Lancez <code>ferrflow init</code> pour cr\u00e9er un fichier de config, ou v\u00e9rifiez le chemin.</p>
+</div></aside>
+
+### E1002 : \u00c9chec du parsing ferrflow.json
+
+<span id="e1002"></span>
+
+Le fichier `ferrflow.json` contient du JSON invalide.
+
+### E1003 : \u00c9chec du parsing ferrflow.json5
+
+<span id="e1003"></span>
+
+Le fichier `ferrflow.json5` contient du JSON5 invalide.
+
+### E1004 : \u00c9chec du parsing ferrflow.toml
+
+<span id="e1004"></span>
+
+Le fichier `ferrflow.toml` contient du TOML invalide.
+
+### E1005 : Erreur de s\u00e9rialisation TOML
+
+<span id="e1005"></span>
+
+Erreur interne lors de l'\u00e9criture TOML.
+
+### E1006 : \u00c9chec du parsing .ferrflow
+
+<span id="e1006"></span>
+
+Le fichier `.ferrflow` contient du JSON invalide.
+
+### E1007 : Erreur de s\u00e9rialisation .ferrflow
+
+<span id="e1007"></span>
+
+Erreur interne lors de l'\u00e9criture du dotfile.
+
+### E1008 : R\u00e9solution de chemin impossible
+
+<span id="e1008"></span>
+
+Un chemin dans la config n'a pas pu \u00eatre r\u00e9solu en chemin absolu.
+
+### E1009 : \u00c9criture du loader temporaire impossible
+
+<span id="e1009"></span>
+
+Impossible d'\u00e9crire le loader JS/TS temporaire.
+
+### E1010 : Impossible d'ex\u00e9cuter tsx
+
+<span id="e1010"></span>
+
+Le runtime `tsx` est introuvable pour les configs `.ts`.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Installez tsx : <code>npm install -g tsx</code>, ou utilisez un format JSON/TOML.</p>
+</div></aside>
+
+### E1011 : Impossible d'ex\u00e9cuter node
+
+<span id="e1011"></span>
+
+Le runtime `node` est introuvable pour les configs `.js`.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Installez Node.js ou utilisez un format JSON/TOML.</p>
+</div></aside>
+
+### E1012 : \u00c9valuation de la config \u00e9chou\u00e9e
+
+<span id="e1012"></span>
+
+Le fichier JS/TS a lev\u00e9 une erreur lors de l'\u00e9valuation.
+
+### E1013 : Sortie de config invalide
+
+<span id="e1013"></span>
+
+Le fichier JS/TS a produit une sortie non UTF-8.
+
+### E1014 : JSON invalide depuis la config
+
+<span id="e1014"></span>
+
+Le fichier JS/TS n'a pas produit de JSON valide.
+
+### E1015 : Lecture du fichier impossible
+
+<span id="e1015"></span>
+
+Le fichier de config existe mais ne peut pas \u00eatre lu.
+
+### E1016 : Plusieurs fichiers de config
+
+<span id="e1016"></span>
+
+Plusieurs fichiers de config trouv\u00e9s dans le r\u00e9pertoire.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Gardez un seul fichier de config.</p>
+</div></aside>
+
+### E1017 : Fichier d\u00e9j\u00e0 existant
+
+<span id="e1017"></span>
+
+`ferrflow init` lanc\u00e9 alors qu'un fichier de config existe d\u00e9j\u00e0.
+
+## Erreurs de validation
+
+### E1100 : Spec de repo invalide
+
+<span id="e1100"></span>
+
+L'argument `--repo` ne correspond pas au format attendu `owner/repo`.
+
+### E1101 : Erreur API GitHub
+
+<span id="e1101"></span>
+
+L'API GitHub a retourn\u00e9 une erreur lors de la validation distante.
+
+### E1102 : Erreur API GitLab
+
+<span id="e1102"></span>
+
+L'API GitLab a retourn\u00e9 une erreur lors de la validation distante.
+
+### E1103 : UTF-8 invalide
+
+<span id="e1103"></span>
+
+Le fichier de config distant contient un encodage UTF-8 invalide.
+
+### E1104 : Parsing de la config distante \u00e9chou\u00e9
+
+<span id="e1104"></span>
+
+Le fichier de config distant n'a pas pu \u00eatre pars\u00e9.
+
+### E1105 : Fichier de config distant introuvable
+
+<span id="e1105"></span>
+
+Le chemin sp\u00e9cifi\u00e9 n'existe pas dans le d\u00e9p\u00f4t distant.
+
+### E1106 : Aucun fichier de config trouv\u00e9
+
+<span id="e1106"></span>
+
+Aucun fichier de config FerrFlow dans le d\u00e9p\u00f4t distant.
+
+### E1107 : --ref n\u00e9cessite --repo
+
+<span id="e1107"></span>
+
+Le flag `--ref` a \u00e9t\u00e9 utilis\u00e9 sans `--repo`.
+
+## Op\u00e9rations Git
+
+### E2001 : Pas un d\u00e9p\u00f4t git
+
+<span id="e2001"></span>
+
+Le r\u00e9pertoire courant n'est pas dans un d\u00e9p\u00f4t git.
+
+### E2002 : D\u00e9p\u00f4t bare non support\u00e9
+
+<span id="e2002"></span>
+
+FerrFlow ne supporte pas les d\u00e9p\u00f4ts git bare.
+
+### E2003 : Tag existant
+
+<span id="e2003"></span>
+
+Le tag que FerrFlow veut cr\u00e9er existe d\u00e9j\u00e0.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Supprimez le tag existant ou utilisez <code>--force</code>.</p>
+</div></aside>
+
+### E2004 : Push de branche \u00e9chou\u00e9
+
+<span id="e2004"></span>
+
+Impossible de push la branche de release.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>V\u00e9rifiez vos droits de push et les r\u00e8gles de protection.</p>
+</div></aside>
+
+### E2005 : Push rejet\u00e9
+
+<span id="e2005"></span>
+
+Le remote a rejet\u00e9 le push.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Pullez les derniers changements et r\u00e9essayez.</p>
+</div></aside>
+
+### E2006 : Push des tags \u00e9chou\u00e9
+
+<span id="e2006"></span>
+
+Impossible de push les tags vers le remote.
+
+### E2007 : Push des tags flottants \u00e9chou\u00e9
+
+<span id="e2007"></span>
+
+Impossible de force-push les tags flottants.
+
+### E2008 : Remote introuvable
+
+<span id="e2008"></span>
+
+Le remote git configur\u00e9 n'existe pas.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>V\u00e9rifiez <code>git remote -v</code> et le champ <code>remote</code> de votre config.</p>
+</div></aside>
+
+### E2009 : V\u00e9rification post-push \u00e9chou\u00e9e
+
+<span id="e2009"></span>
+
+Le commit de release n'a pas pu \u00eatre v\u00e9rifi\u00e9 sur la branche distante.
+
+### E2010 : Branche distante introuvable
+
+<span id="e2010"></span>
+
+La branche distante n'a pas \u00e9t\u00e9 trouv\u00e9e apr\u00e8s le push.
+
+## API GitHub
+
+### E3001 : Cr\u00e9ation de release \u00e9chou\u00e9e
+
+<span id="e3001"></span>
+
+L'API GitHub Releases a retourn\u00e9 une erreur.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>V\u00e9rifiez que <code>GITHUB_TOKEN</code> a la permission <code>contents: write</code>.</p>
+</div></aside>
+
+### E3002 to E3010 : Erreurs API GitHub
+
+<span id="e3002"></span>
+
+Erreurs lors d'op\u00e9rations sur l'API GitHub (releases, PR, auto-merge, GraphQL).
+
+## API GitLab
+
+### E3101 : Cr\u00e9ation de release \u00e9chou\u00e9e
+
+<span id="e3101"></span>
+
+L'API GitLab Releases a retourn\u00e9 une erreur.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>V\u00e9rifiez que le token CI a les acc\u00e8s API n\u00e9cessaires.</p>
+</div></aside>
+
+### E3102 to E3105 : Erreurs API GitLab
+
+<span id="e3102"></span>
+
+Erreurs lors d'op\u00e9rations sur l'API GitLab (releases, MR, merge).
+
+## Fichiers de version
+
+Les erreurs E4xxx concernent la lecture, l'\u00e9criture et le parsing des fichiers de version :
+
+| Plage          | Format                            |
+| -------------- | --------------------------------- |
+| E4101 to E4105 | TOML (Cargo.toml, pyproject.toml) |
+| E4201 to E4205 | JSON (package.json)               |
+| E4301 to E4304 | Helm / YAML (Chart.yaml)          |
+| E4401 to E4413 | XML / CSProj                      |
+| E4501 to E4504 | Gradle                            |
+| E4601 to E4603 | Go mod                            |
+| E4701 to E4704 | Texte (VERSION, VERSION.txt)      |
+
+Erreurs courantes : lecture impossible, syntaxe invalide, champ `version` manquant, \u00e9criture impossible, UTF-8 invalide.
+
+## Pr\u00e9-release
+
+### E5001 : Nom de channel vide
+
+<span id="e5001"></span>
+
+Le nom du channel de pr\u00e9-release est vide.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Sp\u00e9cifiez un nom : <code>--channel beta</code></p>
+</div></aside>
+
+### E5002 : Nom de channel invalide
+
+<span id="e5002"></span>
+
+Seuls les alphanum\u00e9riques et tirets sont accept\u00e9s.
+
+## Versioning
+
+### E5010 : Semver invalide
+
+<span id="e5010"></span>
+
+La version actuelle n'est pas un semver valide.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Format attendu : <code>MAJEUR.MINEUR.PATCH</code>.</p>
+</div></aside>
+
+## Hooks
+
+### E6001 : Hook \u00e9chou\u00e9
+
+<span id="e6001"></span>
+
+Un hook a \u00e9chou\u00e9 avec `on_failure: "abort"`.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>V\u00e9rifiez la commande du hook, ou mettez <code>on_failure: &quot;continue&quot;</code>.</p>
+</div></aside>
+
+## Query
+
+### E7001 : Aucun package configur\u00e9
+
+<span id="e7001"></span>
+
+Aucun package dans le fichier de config.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Lancez <code>ferrflow init</code> ou ajoutez des packages manuellement.</p>
+</div></aside>
+
+### E7002 : Package introuvable
+
+<span id="e7002"></span>
+
+Le nom de package sp\u00e9cifi\u00e9 n'existe pas dans la config.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Lancez <code>ferrflow version</code> pour lister les packages.</p>
+</div></aside>
+
+## Monorepo
+
+### E8001 : Package introuvable dans la config
+
+<span id="e8001"></span>
+
+Un package r\u00e9f\u00e9renc\u00e9 pendant la release n'a pas \u00e9t\u00e9 trouv\u00e9.
+
+### E8002 : Tag flottant r\u00e9gressif
+
+<span id="e8002"></span>
+
+Un tag flottant serait d\u00e9plac\u00e9 vers une version plus ancienne.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Utilisez <code>--force</code> pour ignorer la v\u00e9rification.</p>
+</div></aside>
+
+### E8003 : Cycle de dépendances
+
+<span id="e8003"></span>
+
+Deux packages ou plus dépendent l'un de l'autre via `dependsOn`, directement ou transitivement : il n'existe aucun ordre de release possible. Le message nomme la boucle, par exemple `cycle detected: api → web → api`. Supprimez l'une des arêtes `dependsOn` pour la casser. La vérification s'exécute avant toute écriture de version, donc une configuration cyclique ne laisse jamais de release partielle.

package/docs-fr-v5/verifying-releases.md

@@ -0,0 +1,97 @@
+---
+title: Vérifier les releases
+description: Chaque release FerrFlow embarque des signatures Sigstore, un SBOM CycloneDX et une attestation de provenance SLSA. Voici comment les vérifier.
+---
+
+Chaque tarball de release, l'image Docker, l'archive de complétions binaires et le SBOM qui les accompagne sont signés via [Sigstore](https://www.sigstore.dev/) en signature sans clé. Il n'y a aucune clé publique à suivre — l'identité de signature est celle du workload GitHub Actions qui tourne dans `FerrLabs/FerrFlow`, ancrée dans le journal public de transparence [Rekor](https://docs.sigstore.dev/logging/overview/).
+
+Disponible depuis la v5.2.
+
+## Ce qui est livré par release
+
+| Artefact                           | Sidecars                           |
+| ---------------------------------- | ---------------------------------- |
+| `ferrflow-linux-x64.tar.gz`        | `.sig`, `.crt`                     |
+| `ferrflow-linux-arm64.tar.gz`      | `.sig`, `.crt`                     |
+| `ferrflow-linux-armv7.tar.gz`      | `.sig`, `.crt`                     |
+| `ferrflow-darwin-x64.tar.gz`       | `.sig`, `.crt`                     |
+| `ferrflow-darwin-arm64.tar.gz`     | `.sig`, `.crt`                     |
+| `ferrflow-windows-x64.zip`         | `.sig`, `.crt`                     |
+| `ferrflow-windows-arm64.zip`       | `.sig`, `.crt`                     |
+| `ferrflow-completions.tar.gz`      | `.sig`, `.crt`                     |
+| `sbom.cdx.json`                    | `.sig`, `.crt`                     |
+| `ghcr.io/ferrlabs/ferrflow:vX.Y.Z` | Signature cosign dans GHCR + Rekor |
+
+Tous les sidecars sont téléchargeables depuis la page GitHub Release à côté du binaire.
+
+> Les releases jusqu'à **v5.47.4** embarquent une paire `.sig` + `.crt` au lieu d'un unique `.bundle`. Vérifiez-les avec `--certificate <fichier>.crt --signature <fichier>.sig` à la place de `--bundle`. Le changement vient de cosign v3, qui a remplacé les sorties signature et certificat séparées par un bundle unique.
+
+## Vérifier un tarball
+
+```bash
+# installer cosign (une seule fois)
+curl -L https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 \
+  -o /usr/local/bin/cosign && chmod +x /usr/local/bin/cosign
+
+# télécharger l'artefact + les sidecars depuis la page de release
+TAG=v5.2.3
+gh release download "$TAG" --repo FerrLabs/FerrFlow \
+  -p 'ferrflow-linux-x64.tar.gz*'
+
+# vérifier
+cosign verify-blob \
+  --bundle ferrflow-linux-x64.tar.gz.bundle \
+  --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  ferrflow-linux-x64.tar.gz
+# → Verified OK
+```
+
+Une vérification qui passe signifie :
+
+- Les octets du tarball n'ont pas été modifiés depuis que le workflow de release les a signés.
+- L'identité de signature était un workflow exécuté dans `FerrLabs/FerrFlow` déclenché par l'issuer OIDC de GitHub Actions.
+- La signature est inscrite dans le journal public Rekor — cherchez la valeur du `.sig` sur [search.sigstore.dev](https://search.sigstore.dev/).
+
+## Vérifier l'image Docker
+
+```bash
+cosign verify ghcr.io/ferrlabs/ferrflow:v5.2.3 \
+  --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+## Vérifier le SBOM
+
+Le SBOM (`sbom.cdx.json`) est un document [CycloneDX](https://cyclonedx.org/) listant toutes les dépendances transitives du binaire publié. Il est signé de la même façon que les tarballs :
+
+```bash
+cosign verify-blob \
+  --bundle sbom.cdx.json.bundle \
+  --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  sbom.cdx.json
+```
+
+Injectez le SBOM vérifié dans votre scanner — Grype, Trivy, Snyk, JFrog Xray, Anchore, n'importe quoi qui parle CycloneDX.
+
+## Attestation de provenance SLSA
+
+En plus des signatures Sigstore, chaque release embarque aussi une [attestation de provenance SLSA](https://slsa.dev/) générée via [`actions/attest-build-provenance`](https://github.com/actions/attest-build-provenance). Elle enregistre le run du workflow, le SHA du commit source et les inputs de build.
+
+```bash
+gh attestation verify ferrflow-linux-x64.tar.gz --repo FerrLabs/FerrFlow
+```
+
+## Ce qui n'est pas signé
+
+Les tarballs sources de `git archive` (les actifs « Source code (zip) » / « Source code (tar.gz) » générés automatiquement sur la page GitHub Release) viennent de GitHub, pas du workflow de release, et n'ont pas de sidecar de signature. Si vous avez besoin d'une attestation sur la source, utilisez plutôt `gh attestation verify` contre le bundle de provenance.
+
+## Pourquoi c'est important
+
+- **Attaques de chaîne d'approvisionnement.** Un attaquant qui compromet un CDN, un miroir ou pousse un package typosquat ne peut pas forger la signature — l'identité de signature est ancrée au flow OIDC de GitHub Actions.
+- **Conformité.** Les clients SOC 2 / ISO 27001 peuvent attester que le binaire qu'ils ont récupéré est celui que leur auditeur a approuvé.
+- **Aucune gestion de clé.** Personne chez FerrLabs n'a de clé privée de signature à perdre ou faire tourner. Le workflow prouve son identité au moment de la signature.
+
+<aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Si vous déployez FerrFlow dans un environnement régulé, pinnez à la fois la version <strong>et</strong> la paire <code>.sig</code>/<code>.crt</code> dans votre étape de provisioning. Une compromission future du workflow ne peut pas antidater une signature déjà présente dans Rekor.</p>
+</div></aside>

package/docs-fr-v6/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-v6/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.