@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.
- package/data/benchmarks.json +692 -692
- package/docs-en/reference/api.md +1 -1
- package/docs-en/reference/cli.md +20 -0
- package/docs-en/reference/errors.md +6 -0
- package/docs-en/verifying-releases.md +8 -7
- package/docs-fr/reference/api.md +1 -1
- package/docs-fr/reference/cli.md +20 -0
- package/docs-fr/reference/errors.md +6 -0
- package/docs-fr/verifying-releases.md +8 -7
- package/package.json +1 -1
package/docs-en/reference/api.md
CHANGED
|
@@ -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
|
|
package/docs-en/reference/cli.md
CHANGED
|
@@ -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:
|
|
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
|
|
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:
|
|
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
|
package/docs-fr/reference/api.md
CHANGED
|
@@ -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
|
|
package/docs-fr/reference/cli.md
CHANGED
|
@@ -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:
|
|
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
|
|
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:
|
|
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é
|