@ferrflow/doc 7.26.12 → 7.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -46,7 +46,7 @@ curl "https://api.ferrflow.com/v1/ferrflow/latest?platform=linux-x64"
46
46
  }
47
47
  ```
48
48
 
49
- Releases are signed with [Sigstore](/verifying-releases/): verify the `.bundle` rather than a checksum (releases up to v5.47.4 carry a `.sig` + `.crt` pair instead). Without `platform`, the response lists `assets` for every platform. Valid platforms: `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
49
+ Releases are signed with [Sigstore](/docs/verifying-releases/): verify the `.bundle` rather than a checksum (releases up to v5.47.4 carry a `.sig` + `.crt` pair instead). Without `platform`, the response lists `assets` for every platform. Valid platforms: `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
50
50
 
51
51
  ## `POST /v1/ferrflow/validate`
52
52
 
@@ -62,6 +62,26 @@ From there the first `feat:` commit bumps to `0.1.0` / `1` / today's date / …
62
62
 
63
63
  ---
64
64
 
65
+ ## `ferrflow shadow-release`
66
+
67
+ Run the whole release in a throwaway clone of the repository, so you can see what a real release would do and whether it would get through.
68
+
69
+ ```bash
70
+ ferrflow shadow-release [--keep]
71
+ ```
72
+
73
+ | Flag | Description |
74
+ | -------- | ------------------------------------------------ |
75
+ | `--keep` | Keep the clone and print its path for inspection |
76
+
77
+ The clone gets everything `release` does locally: versioned files, changelogs, the release commit, tags and floating tags. Pre-commit, post-commit, pre-tag, post-tag and pre-publish hooks run for real, so a hook that would fail the release fails here too. Nothing leaves the machine: no push, no forge release, no draft promotion, no post-publish, `onSuccess` or `onError` hook, and no publisher. The repository you ran it from is not modified.
78
+
79
+ With `releaseCommitMode: "pr"`, the clone gets the commit and tags that land once the release PR is merged, not the PR itself.
80
+
81
+ At the end it lists the commits, the files written and the tags created, then deletes the clone unless `--keep` is set. It exits non-zero with the failing step's error code when any step fails, so a CI job can gate on it.
82
+
83
+ ---
84
+
65
85
  ## `ferrflow check`
66
86
 
67
87
  Preview what `ferrflow release` would do without making any changes.
@@ -268,6 +268,12 @@ After pushing, the release commit could not be verified on the remote branch.
268
268
 
269
269
  The remote branch was not found after a push operation.
270
270
 
271
+ ### E2016: Shadow clone failed
272
+
273
+ <span id="e2016"></span>
274
+
275
+ `ferrflow shadow-release` could not clone the repository into a temporary directory. Check that git is on the `PATH` and that the system temp directory is writable.
276
+
271
277
  ## GitHub API Errors
272
278
 
273
279
  ### E3001: Failed to create release
@@ -20,7 +20,7 @@ Available since v5.2.
20
20
  | `ferrflow-windows-arm64.zip` | `.sigstore.json` |
21
21
  | `ferrflow-completions.tar.gz` | `.sigstore.json` |
22
22
  | `sbom.cdx.json` | `.sigstore.json` |
23
- | `ghcr.io/ferrlabs/ferrflow:vX.Y.Z` | Cosign signature in GHCR + Rekor |
23
+ | `ghcr.io/ferrlabs/ferrflow:X.Y.Z` | Cosign signature in GHCR + Rekor |
24
24
 
25
25
  All sidecars are downloadable from the GitHub Release page next to the binary.
26
26
 
@@ -41,7 +41,7 @@ gh release download "$TAG" --repo FerrLabs/FerrFlow \
41
41
  # verify
42
42
  cosign verify-blob \
43
43
  --bundle ferrflow-linux-x64.tar.gz.sigstore.json \
44
- --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
44
+ --certificate-identity-regexp "^https://github.com/FerrLabs/FerrFlow/.github/workflows/publish.yml@refs/tags/" \
45
45
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
46
46
  ferrflow-linux-x64.tar.gz
47
47
  # → Verified OK
@@ -50,14 +50,14 @@ cosign verify-blob \
50
50
  A passing verification means:
51
51
 
52
52
  - The tarball bytes haven't been tampered with since the release workflow signed them.
53
- - The signing identity was a workflow running in `FerrLabs/FerrFlow` triggered by GitHub Actions' OIDC issuer.
53
+ - The signing identity was FerrFlow's release workflow, `.github/workflows/publish.yml` in `FerrLabs/FerrFlow` running on a release tag, authenticated by GitHub Actions' OIDC issuer. Another workflow in the repository cannot produce a signature that passes this check.
54
54
  - The signature is recorded in the public Rekor log: search [search.sigstore.dev](https://search.sigstore.dev/) for the `.sig` value.
55
55
 
56
56
  ## Verifying the Docker image
57
57
 
58
58
  ```bash
59
- cosign verify ghcr.io/ferrlabs/ferrflow:v5.2.3 \
60
- --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
59
+ cosign verify ghcr.io/ferrlabs/ferrflow:5.2.3 \
60
+ --certificate-identity-regexp "^https://github.com/FerrLabs/FerrFlow/.github/workflows/publish.yml@refs/tags/" \
61
61
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
62
62
  ```
63
63
 
@@ -68,7 +68,7 @@ The SBOM (`sbom.cdx.json`) is a [CycloneDX](https://cyclonedx.org/) document lis
68
68
  ```bash
69
69
  cosign verify-blob \
70
70
  --bundle sbom.cdx.json.sigstore.json \
71
- --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
71
+ --certificate-identity-regexp "^https://github.com/FerrLabs/FerrFlow/.github/workflows/publish.yml@refs/tags/" \
72
72
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
73
73
  sbom.cdx.json
74
74
  ```
@@ -80,7 +80,8 @@ Feed the verified SBOM into your scanner of choice: Grype, Trivy, Snyk, JFrog Xr
80
80
  In addition to Sigstore signatures, every release also ships a [SLSA build provenance attestation](https://slsa.dev/) generated via [`actions/attest-build-provenance`](https://github.com/actions/attest-build-provenance). It records the workflow run, the source commit SHA, and the build inputs.
81
81
 
82
82
  ```bash
83
- gh attestation verify ferrflow-linux-x64.tar.gz --repo FerrLabs/FerrFlow
83
+ gh attestation verify ferrflow-linux-x64.tar.gz --repo FerrLabs/FerrFlow \
84
+ --signer-workflow FerrLabs/FerrFlow/.github/workflows/publish.yml
84
85
  ```
85
86
 
86
87
  ## What's not signed
@@ -46,7 +46,7 @@ curl "https://api.ferrflow.com/v1/ferrflow/latest?platform=linux-x64"
46
46
  }
47
47
  ```
48
48
 
49
- Les releases sont signées avec [Sigstore](/fr/verifying-releases/) : vérifiez le `.bundle` plutôt qu'une somme de contrôle (les releases jusqu'à v5.47.4 embarquent une paire `.sig` + `.crt`). Sans `platform`, la réponse liste les `assets` de chaque plateforme. Plateformes valides : `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
49
+ Les releases sont signées avec [Sigstore](/fr/docs/verifying-releases/) : vérifiez le `.bundle` plutôt qu'une somme de contrôle (les releases jusqu'à v5.47.4 embarquent une paire `.sig` + `.crt`). Sans `platform`, la réponse liste les `assets` de chaque plateforme. Plateformes valides : `linux-x64`, `linux-arm64`, `linux-arm`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64`.
50
50
 
51
51
  ## `POST /v1/ferrflow/validate`
52
52
 
@@ -31,6 +31,26 @@ ferrflow release [OPTIONS]
31
31
 
32
32
  ---
33
33
 
34
+ ## `ferrflow shadow-release`
35
+
36
+ Exécuter toute la release dans un clone jetable du dépôt, pour voir ce qu'une vraie release ferait et si elle passerait.
37
+
38
+ ```bash
39
+ ferrflow shadow-release [--keep]
40
+ ```
41
+
42
+ | Option | Description |
43
+ | -------- | ---------------------------------------------------------- |
44
+ | `--keep` | Conserver le clone et afficher son chemin pour l'inspecter |
45
+
46
+ Le clone reçoit tout ce que `release` fait en local : fichiers versionnés, changelogs, commit de release, tags et tags flottants. Les hooks pre-commit, post-commit, pre-tag, post-tag et pre-publish s'exécutent réellement, donc un hook qui ferait échouer la release échoue ici aussi. Rien ne sort de la machine : pas de push, pas de release sur la forge, pas de publication des brouillons, pas de hook post-publish, `onSuccess` ou `onError`, ni de publisher. Le dépôt d'origine n'est pas modifié.
47
+
48
+ Avec `releaseCommitMode: "pr"`, le clone reçoit le commit et les tags qui arrivent une fois la PR de release mergée, pas la PR elle-même.
49
+
50
+ À la fin, la commande liste les commits, les fichiers écrits et les tags créés, puis supprime le clone sauf avec `--keep`. Elle sort avec un code non nul et le code d'erreur de l'étape fautive dès qu'une étape échoue, pour qu'un job de CI puisse s'en servir comme garde-fou.
51
+
52
+ ---
53
+
34
54
  ## `ferrflow check`
35
55
 
36
56
  Prévisualiser ce que `ferrflow release` ferait sans effectuer de changements.
@@ -265,6 +265,12 @@ Le commit de release n'a pas pu être vérifié sur la branche distante.
265
265
 
266
266
  La branche distante n'a pas été trouvée après le push.
267
267
 
268
+ ### E2016 : Clone de shadow-release échoué
269
+
270
+ <span id="e2016"></span>
271
+
272
+ `ferrflow shadow-release` n'a pas pu cloner le dépôt dans un répertoire temporaire. Vérifiez que git est dans le `PATH` et que le répertoire temporaire du système est accessible en écriture.
273
+
268
274
  ## API GitHub
269
275
 
270
276
  ### E3001 : Création de release échouée
@@ -20,7 +20,7 @@ Disponible depuis la v5.2.
20
20
  | `ferrflow-windows-arm64.zip` | `.sig`, `.crt` |
21
21
  | `ferrflow-completions.tar.gz` | `.sig`, `.crt` |
22
22
  | `sbom.cdx.json` | `.sig`, `.crt` |
23
- | `ghcr.io/ferrlabs/ferrflow:vX.Y.Z` | Signature cosign dans GHCR + Rekor |
23
+ | `ghcr.io/ferrlabs/ferrflow:X.Y.Z` | Signature cosign dans GHCR + Rekor |
24
24
 
25
25
  Tous les sidecars sont téléchargeables depuis la page GitHub Release à côté du binaire.
26
26
 
@@ -41,7 +41,7 @@ gh release download "$TAG" --repo FerrLabs/FerrFlow \
41
41
  # vérifier
42
42
  cosign verify-blob \
43
43
  --bundle ferrflow-linux-x64.tar.gz.sigstore.json \
44
- --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
44
+ --certificate-identity-regexp "^https://github.com/FerrLabs/FerrFlow/.github/workflows/publish.yml@refs/tags/" \
45
45
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
46
46
  ferrflow-linux-x64.tar.gz
47
47
  # → Verified OK
@@ -50,14 +50,14 @@ cosign verify-blob \
50
50
  Une vérification qui passe signifie :
51
51
 
52
52
  - Les octets du tarball n'ont pas été modifiés depuis que le workflow de release les a signés.
53
- - L'identité de signature était un workflow exécuté dans `FerrLabs/FerrFlow` déclenché par l'issuer OIDC de GitHub Actions.
53
+ - L'identité de signature était le workflow de release de FerrFlow, `.github/workflows/publish.yml` dans `FerrLabs/FerrFlow` exécuté sur un tag de release, authentifié par l'issuer OIDC de GitHub Actions. Un autre workflow du dépôt ne peut pas produire une signature qui passe cette vérification.
54
54
  - La signature est inscrite dans le journal public Rekor : cherchez la valeur du `.sig` sur [search.sigstore.dev](https://search.sigstore.dev/).
55
55
 
56
56
  ## Vérifier l'image Docker
57
57
 
58
58
  ```bash
59
- cosign verify ghcr.io/ferrlabs/ferrflow:v5.2.3 \
60
- --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
59
+ cosign verify ghcr.io/ferrlabs/ferrflow:5.2.3 \
60
+ --certificate-identity-regexp "^https://github.com/FerrLabs/FerrFlow/.github/workflows/publish.yml@refs/tags/" \
61
61
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
62
62
  ```
63
63
 
@@ -68,7 +68,7 @@ Le SBOM (`sbom.cdx.json`) est un document [CycloneDX](https://cyclonedx.org/) li
68
68
  ```bash
69
69
  cosign verify-blob \
70
70
  --bundle sbom.cdx.json.sigstore.json \
71
- --certificate-identity-regexp "https://github.com/FerrLabs/FerrFlow/.*" \
71
+ --certificate-identity-regexp "^https://github.com/FerrLabs/FerrFlow/.github/workflows/publish.yml@refs/tags/" \
72
72
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
73
73
  sbom.cdx.json
74
74
  ```
@@ -80,7 +80,8 @@ Injectez le SBOM vérifié dans votre scanner : Grype, Trivy, Snyk, JFrog Xray,
80
80
  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.
81
81
 
82
82
  ```bash
83
- gh attestation verify ferrflow-linux-x64.tar.gz --repo FerrLabs/FerrFlow
83
+ gh attestation verify ferrflow-linux-x64.tar.gz --repo FerrLabs/FerrFlow \
84
+ --signer-workflow FerrLabs/FerrFlow/.github/workflows/publish.yml
84
85
  ```
85
86
 
86
87
  ## Ce qui n'est pas signé
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ferrflow/doc",
3
- "version": "7.26.12",
3
+ "version": "7.27.0",
4
4
  "description": "Documentation for FerrFlow, the universal semantic versioning CLI. Rendered at ferrflow.com/docs.",
5
5
  "license": "MIT",
6
6
  "repository": {