@ferrflow/doc 7.24.6 → 7.25.0

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

@@ -48,6 +48,31 @@ Release commits and tags use the repository's git identity. If the job sets none
 <aside class="ferr-aside ferr-aside--tip"><div class="ferr-aside__body"><p>Prefer not to manage a token? Set <code>bot: true</code> to author releases as <code>ferrflow[bot]</code> with zero secrets: see the <a href="/docs/ci/hosted-bot">Hosted bot</a> guide.</p>
 </div></aside>
 
+## Signing the release tag
+
+GitHub signs the commits it creates through its API, which is why a release commit made with `bot: true` shows as verified. It never signs a tag object, and a GitHub App holds no key of its own, so the tag FerrFlow pushes is unsigned unless you give the action a signing key.
+
+```yaml
+- uses: FerrLabs/FerrFlow@v7
+  with:
+    bot: true
+    tag_signing_key: ${{ secrets.TAG_SIGNING_KEY }}
+    tag_signing_name: ${{ vars.TAG_SIGNING_NAME }}
+    tag_signing_email: ${{ vars.TAG_SIGNING_EMAIL }}
+```
+
+The key is an unencrypted OpenSSH private key, and the tagger it signs as has to be an account GitHub can check the signature against:
+
+```bash
+ssh-keygen -t ed25519 -C "releases" -N "" -f ferrflow-tag-signing
+```
+
+In PowerShell, leave `-N` out and press Enter twice at the prompt. A bare `-N ""` is dropped by Windows PowerShell 5.1, and `-N '""'` reaches ssh-keygen as a literal `""` passphrase on PowerShell 7.3 and later. The key must have no passphrase, since the runner cannot type one.
+
+Add `ferrflow-tag-signing.pub` to that account under **Settings > SSH and GPG keys > New SSH key** with the key type **Signing Key**, store the private half as the `TAG_SIGNING_KEY` secret, and set `tag_signing_email` to one of the account's verified emails. GitHub verifies a tag against the keys of the account whose verified email the tagger carries, so a mismatch there shows as unverified rather than failing the release.
+
+The action writes the key under `RUNNER_TEMP` for the job only, and it never reaches the repository or the tag itself. The tagger identity is exported to the job, so any `git commit` a later step of your workflow makes is recorded with that committer too. Only the tag is signed: the release commit already carries GitHub's own signature in bot mode, and the release archives are signed separately with cosign.
+
 ## Accessing the release output
 
 The action exposes the new version as an output you can use in downstream steps:

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

@@ -48,6 +48,31 @@ Les commits et tags de release utilisent l'identité git du dépôt. Si le job n
 <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>
 
+## Signer le tag de release
+
+GitHub signe les commits qu'il crée via son API : c'est pourquoi un commit de release fait avec `bot: true` apparaît vérifié. Il ne signe jamais un objet tag, et une GitHub App ne possède aucune clé, donc le tag poussé par FerrFlow reste non signé tant que vous ne donnez pas de clé de signature à l'action.
+
+```yaml
+- uses: FerrLabs/FerrFlow@v7
+  with:
+    bot: true
+    tag_signing_key: ${{ secrets.TAG_SIGNING_KEY }}
+    tag_signing_name: ${{ vars.TAG_SIGNING_NAME }}
+    tag_signing_email: ${{ vars.TAG_SIGNING_EMAIL }}
+```
+
+La clé est une clé privée OpenSSH non chiffrée, et le tagger avec lequel elle signe doit être un compte auquel GitHub peut rattacher la signature :
+
+```bash
+ssh-keygen -t ed25519 -C "releases" -N "" -f ferrflow-tag-signing
+```
+
+Sous PowerShell, omettez `-N` et appuyez deux fois sur Entrée. Un `-N ""` nu est supprimé par Windows PowerShell 5.1, et `-N '""'` arrive à ssh-keygen comme une passphrase littérale `""` sur PowerShell 7.3 et suivants. La clé doit être sans passphrase, le runner ne pouvant pas en saisir une.
+
+Ajoutez `ferrflow-tag-signing.pub` à ce compte via **Settings > SSH and GPG keys > New SSH key** en choisissant le type **Signing Key**, stockez la moitié privée dans le secret `TAG_SIGNING_KEY`, et mettez dans `tag_signing_email` une des adresses vérifiées du compte. GitHub vérifie un tag contre les clés du compte dont le tagger porte l'adresse vérifiée : en cas de décalage, le tag s'affiche comme non vérifié, la release n'échoue pas.
+
+L'action écrit la clé sous `RUNNER_TEMP`, le temps du job, et elle n'atteint ni le dépôt ni le tag lui-même. L'identité du tagger est exportée au job : un `git commit` fait par une étape ultérieure de votre workflow portera donc aussi ce committer. Seul le tag est signé : le commit de release porte déjà la signature de GitHub en mode bot, et les archives de release sont signées à part avec cosign.
+
 ## Accéder à la sortie de la release
 
 L'action expose la nouvelle version en output que vous pouvez utiliser dans les étapes suivantes :

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferrflow/doc",
-  "version": "7.24.6",
+  "version": "7.25.0",
   "description": "Documentation for FerrFlow, the universal semantic versioning CLI. Rendered at ferrflow.com/docs.",
   "license": "MIT",
   "repository": {