From 891149c09aa6e3535f51bf9b80bb343c02d17107 Mon Sep 17 00:00:00 2001 From: nolte Date: Mon, 17 Aug 2026 22:48:24 +0200 Subject: [PATCH 1/2] docs: correct the pinning contract to digest pins MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #40 moved every `uses:` reference in .github/workflows/ to a full-length commit digest (d51e51e, v2.0.0), but four prose locations still describe the old scheme: - docs/{en,de}/references/governance.md name `v1.1.18` as "the current pin" and require that "all pins use released tags" - docs/{en,de}/guides/contributing.md name the same stale tag - CLAUDE.md names `v1.1.10` and states "pinning is by tag" CLAUDE.md is the binding instruction file for AI-assisted edits, so the stale claim actively invites an agent to replace the digest pins with tags — undoing the supply-chain protection the digest form exists for. The governance page carries the same risk for a human reviewer judging a future Renovate digest PR. State the digest form, name the current digest with its version, and give the reason a bare tag is not acceptable (a tag can be moved onto different code, which is what the March 2025 tj-actions/changed-files compromise did). Left alone deliberately: the `v1.1.18` occurrence in governance.md's Vale section, which is an illustrative example of a version-pin-shaped token for the disabled Microsoft.Ranges rule, not a claim about the current pin. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01A4KA8swD1ZzDqknDV5TUxx --- CLAUDE.md | 2 +- docs/de/guides/contributing.md | 6 ++++-- docs/de/references/governance.md | 17 +++++++++++------ docs/en/guides/contributing.md | 5 +++-- docs/en/references/governance.md | 15 ++++++++++----- 5 files changed, 29 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 127e117..a241c67 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,6 +36,6 @@ pre-commit run --all-files ## CI -All workflows in `.github/workflows/` delegate to reusable workflows in `nolte/gh-plumbing` (pre-commit, trivy, chain-bench, mkdocs publish, release-drafter). Pinning is by tag (currently `v1.1.10`); bump all workflow references together. +All workflows in `.github/workflows/` delegate to reusable workflows in `nolte/gh-plumbing` (pre-commit, trivy, chain-bench, mkdocs publish, release-drafter). Every `uses:` reference is pinned to a full-length commit digest with the version as a trailing comment — currently `d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be # v2.0.0`. Never replace a digest pin with a bare tag; bump all workflow references together. Prose in Markdown is linted with Vale using the config in `.vale.ini` (Microsoft + RedHat + nolte custom styles). diff --git a/docs/de/guides/contributing.md b/docs/de/guides/contributing.md index cb3f86c..41a91f7 100644 --- a/docs/de/guides/contributing.md +++ b/docs/de/guides/contributing.md @@ -84,8 +84,10 @@ nicht genutzt wird. Branching-Modell aus `nolte/claude-shared`. - Pull Requests durchlaufen die wiederverwendbaren Workflows aus [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing) unter einem - gepinnten Tag (aktuell `v1.1.18`). Bei einem Pin-Bump alle - Workflow-Referenzen gemeinsam aktualisieren. + gepinnten Commit-Digest (aktuell `d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be`, + das ist `v2.0.0`). Bei einem Pin-Bump alle Workflow-Referenzen gemeinsam + aktualisieren und die Digest-Form beibehalten — ein blankes Tag lässt sich + auf anderen Code umbiegen. - Merges sind ausschließlich Squash und durchlaufen Automerge, sobald die Checks grün sind. Renovate-getriebene Dependency-Bumps gehen denselben Weg. diff --git a/docs/de/references/governance.md b/docs/de/references/governance.md index f518170..0b692b1 100644 --- a/docs/de/references/governance.md +++ b/docs/de/references/governance.md @@ -41,10 +41,12 @@ darauf zurückführen. Jeder Workflow unter `.github/workflows/` delegiert an einen wiederverwendbaren Workflow in -[`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing). Der aktuelle -Pin ist **`v1.1.18`**. Bei einem Bump alle Workflow-Referenzen gemeinsam -aktualisieren, da gemischte Tags zwischen Workflows eine bekannte -Drift-Quelle sind. +[`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing). Jede Referenz ist +auf einen vollständigen Commit-Digest gepinnt, mit der zugehörigen Version als +nachgestelltem Kommentar; der aktuelle Pin ist +**`d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be` (`v2.0.0`)**. Bei einem Bump alle +Workflow-Referenzen gemeinsam aktualisieren, da gemischte Versionen zwischen +Workflows eine bekannte Drift-Quelle sind. | Workflow | Wiederverwendbares Ziel | |----------|-------------------------| @@ -63,8 +65,11 @@ Renovate läuft gegen dieses Repository über das `nolte/gh-plumbing//renovate-configs/common` an einem gepinnten Tag erweitert. Konkrete Erwartungen: -- Alle Pins zeigen auf veröffentlichte Tags. Keine schwebenden - `@develop`- oder `@main`-Referenzen in `uses:`-Zeilen. +- Alle `uses:`-Referenzen in Workflows pinnen auf einen vollständigen + Commit-Digest, mit der veröffentlichten Version als nachgestelltem Kommentar. + Keine schwebenden `@develop`- oder `@main`-Referenzen und kein blankes Tag: + Ein Tag lässt sich auf anderen Code umbiegen — genau das tat die + Kompromittierung von `tj-actions/changed-files` im März 2025. - Renovate gruppiert Dependency-Bumps in einen einzigen Pull Request, sodass Reviewer pro Zyklus einen Batch sehen. - Pull Requests landen über den Standard-Automerge-Pfad, sobald die diff --git a/docs/en/guides/contributing.md b/docs/en/guides/contributing.md index 09af79a..92f28ab 100644 --- a/docs/en/guides/contributing.md +++ b/docs/en/guides/contributing.md @@ -77,8 +77,9 @@ the workstation playbook isn't in use. from `nolte/claude-shared`. - Pull requests run the reusable workflows from [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing) at a pinned - tag (currently `v1.1.18`). Bump every workflow reference together when - updating the pin. + commit digest (currently `d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be`, which is + `v2.0.0`). Bump every workflow reference together when updating the pin, and + keep the digest form; a bare tag can be moved onto different code. - Merges are squash-only and automerge once checks pass. Renovate-driven dependency bumps follow the same path. - Prose changes have to pass Vale (Microsoft + RedHat plus the diff --git a/docs/en/references/governance.md b/docs/en/references/governance.md index 0534abb..c92c683 100644 --- a/docs/en/references/governance.md +++ b/docs/en/references/governance.md @@ -36,9 +36,12 @@ consumes the repository. Every documentation refactor traces back to it. ## Reusable workflows Every workflow under `.github/workflows/` delegates to a reusable workflow -in [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing). The current -pin is **`v1.1.18`**. Bump every workflow reference together when updating, -because mixing tags between workflows is a known source of drift. +in [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing). Each reference +is pinned to a full-length commit digest with the corresponding version as a +trailing comment; the current pin is +**`d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be` (`v2.0.0`)**. Bump every workflow +reference together when updating, because mixing versions between workflows is +a known source of drift. | Workflow | Reusable target | |----------|-----------------| @@ -57,8 +60,10 @@ Renovate runs on this repository through which extends `nolte/gh-plumbing//renovate-configs/common` at a pinned tag. Concrete expectations: -- All pins use released tags. No floating `@develop` or `@main` references - in workflow `uses:` lines. +- All workflow `uses:` references pin to a full-length commit digest, with the + released version named in a trailing comment. No floating `@develop` or + `@main` references, and no bare tag: a tag can be moved onto different code, + which is what the March 2025 `tj-actions/changed-files` compromise did. - Renovate groups dependency bumps into a single pull request so reviewers see one batch per cycle. - Pull requests land through the standard automerge path once checks pass. From 7737dcf52575eb5556d020fa0fae38fce786e198 Mon Sep 17 00:00:00 2001 From: nolte Date: Mon, 17 Aug 2026 23:22:14 +0200 Subject: [PATCH 2/2] docs: point at the workflow files instead of duplicating the digest MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review of #45 found the first pass re-created the staleness it removes, at a shorter half-life: it hard-coded the 40-character digest in five prose locations, while upstream Renovate runs with `pinDigests: true` and bumps that digest in a PR that touches only .github/workflows/. The next bump would leave CLAUDE.md — the binding instruction file — naming a digest no workflow uses. Name the released version instead, and point at .github/workflows/ as the source of truth for the digest itself. Also fix README.md:115, a fifth stale location the first pass missed. It sits outside the intro/usage markers, so docs/index.md doesn't inherit the corrected text from anywhere else. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01A4KA8swD1ZzDqknDV5TUxx --- CLAUDE.md | 2 +- README.md | 2 +- docs/de/guides/contributing.md | 5 +++-- docs/de/references/governance.md | 5 +++-- docs/en/guides/contributing.md | 7 ++++--- docs/en/references/governance.md | 9 +++++---- 6 files changed, 17 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a241c67..2125447 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,6 +36,6 @@ pre-commit run --all-files ## CI -All workflows in `.github/workflows/` delegate to reusable workflows in `nolte/gh-plumbing` (pre-commit, trivy, chain-bench, mkdocs publish, release-drafter). Every `uses:` reference is pinned to a full-length commit digest with the version as a trailing comment — currently `d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be # v2.0.0`. Never replace a digest pin with a bare tag; bump all workflow references together. +All workflows in `.github/workflows/` delegate to reusable workflows in `nolte/gh-plumbing` (pre-commit, trivy, chain-bench, mkdocs publish, release-drafter). Every `uses:` reference is pinned to a full-length commit digest with the released version as a trailing comment — currently the `v2.0.0` line. Read the digest itself from `.github/workflows/`, never from prose: Renovate runs with `pinDigests: true` and bumps the digest without touching documentation. Never replace a digest pin with a bare tag; bump all workflow references together. Prose in Markdown is linted with Vale using the config in `.vale.ini` (Microsoft + RedHat + nolte custom styles). diff --git a/README.md b/README.md index 31028a6..fbe9d2b 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ Pull requests run through the reusable `nolte/gh-plumbing` workflows. Merges are ## Governance and specs -This repository follows the portfolio conventions shipped by [`nolte/claude-shared`](https://github.com/nolte/claude-shared) (project structure, branching model, release automation, audience identification) and consumes the reusable workflows from [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing) at a pinned tag. Dependency bumps land through Renovate, which extends `nolte/gh-plumbing//renovate-configs/common`. +This repository follows the portfolio conventions shipped by [`nolte/claude-shared`](https://github.com/nolte/claude-shared) (project structure, branching model, release automation, audience identification) and consumes the reusable workflows from [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing) at a pinned commit digest. Dependency bumps land through Renovate, which extends `nolte/gh-plumbing//renovate-configs/common`. For the recorded audience analysis that drives the documentation structure, see [`AUDIENCES.md`](./AUDIENCES.md). diff --git a/docs/de/guides/contributing.md b/docs/de/guides/contributing.md index 41a91f7..ee76e85 100644 --- a/docs/de/guides/contributing.md +++ b/docs/de/guides/contributing.md @@ -84,8 +84,9 @@ nicht genutzt wird. Branching-Modell aus `nolte/claude-shared`. - Pull Requests durchlaufen die wiederverwendbaren Workflows aus [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing) unter einem - gepinnten Commit-Digest (aktuell `d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be`, - das ist `v2.0.0`). Bei einem Pin-Bump alle Workflow-Referenzen gemeinsam + gepinnten Commit-Digest (aktuell die `v2.0.0`-Zeile; den Digest selbst bitte + aus `.github/workflows/` lesen, da Renovate ihn bumpt, ohne diese Seite + anzufassen). Bei einem Pin-Bump alle Workflow-Referenzen gemeinsam aktualisieren und die Digest-Form beibehalten — ein blankes Tag lässt sich auf anderen Code umbiegen. - Merges sind ausschließlich Squash und durchlaufen Automerge, sobald die diff --git a/docs/de/references/governance.md b/docs/de/references/governance.md index 0b692b1..2d70809 100644 --- a/docs/de/references/governance.md +++ b/docs/de/references/governance.md @@ -43,8 +43,9 @@ Jeder Workflow unter `.github/workflows/` delegiert an einen wiederverwendbaren Workflow in [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing). Jede Referenz ist auf einen vollständigen Commit-Digest gepinnt, mit der zugehörigen Version als -nachgestelltem Kommentar; der aktuelle Pin ist -**`d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be` (`v2.0.0`)**. Bei einem Bump alle +nachgestelltem Kommentar; die aktuelle Version ist **`v2.0.0`**. Den Digest +selbst bitte aus den Workflow-Dateien lesen, nicht von dieser Seite — Renovate +bumpt ihn automatisch und fasst Prosa nicht an. Bei einem Bump alle Workflow-Referenzen gemeinsam aktualisieren, da gemischte Versionen zwischen Workflows eine bekannte Drift-Quelle sind. diff --git a/docs/en/guides/contributing.md b/docs/en/guides/contributing.md index 92f28ab..d9f3264 100644 --- a/docs/en/guides/contributing.md +++ b/docs/en/guides/contributing.md @@ -77,9 +77,10 @@ the workstation playbook isn't in use. from `nolte/claude-shared`. - Pull requests run the reusable workflows from [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing) at a pinned - commit digest (currently `d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be`, which is - `v2.0.0`). Bump every workflow reference together when updating the pin, and - keep the digest form; a bare tag can be moved onto different code. + commit digest (currently the `v2.0.0` line; read the digest itself from + `.github/workflows/`, since Renovate bumps it without touching this page). + Bump every workflow reference together when updating the pin, and keep the + digest form; a bare tag can be moved onto different code. - Merges are squash-only and automerge once checks pass. Renovate-driven dependency bumps follow the same path. - Prose changes have to pass Vale (Microsoft + RedHat plus the diff --git a/docs/en/references/governance.md b/docs/en/references/governance.md index c92c683..8fc25c3 100644 --- a/docs/en/references/governance.md +++ b/docs/en/references/governance.md @@ -38,10 +38,11 @@ consumes the repository. Every documentation refactor traces back to it. Every workflow under `.github/workflows/` delegates to a reusable workflow in [`nolte/gh-plumbing`](https://github.com/nolte/gh-plumbing). Each reference is pinned to a full-length commit digest with the corresponding version as a -trailing comment; the current pin is -**`d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be` (`v2.0.0`)**. Bump every workflow -reference together when updating, because mixing versions between workflows is -a known source of drift. +trailing comment; the current version is **`v2.0.0`**. Read the digest from the +workflow files themselves rather than from this page, because Renovate bumps it +automatically and doesn't touch prose. Bump every workflow reference together +when updating, because mixing versions between workflows is a known source of +drift. | Workflow | Reusable target | |----------|-----------------|