Skip to content

docs: correct the pinning contract to digest pins #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
github-actions merged 2 commits into from
Aug 17, 2026
Merged

docs: correct the pinning contract to digest pins #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
891149c
docs: correct the pinning contract to digest pins
nolte Aug 17, 2026
7737dcf
docs: point at the workflow files instead of duplicating the digest
nolte Aug 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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).
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
7 changes: 5 additions & 2 deletions docs/de/guides/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,11 @@ 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 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
Checks grün sind. Renovate-getriebene Dependency-Bumps gehen denselben
Weg.
Expand Down
18 changes: 12 additions & 6 deletions docs/de/references/governance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,10 +41,13 @@ 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; 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.

| Workflow | Wiederverwendbares Ziel |
|----------|-------------------------|
Expand All @@ -63,8 +66,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
Expand Down
6 changes: 4 additions & 2 deletions docs/en/guides/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,10 @@
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 the `v2.0.0` line; read the digest itself from

Check warning on line 80 in docs/en/guides/contributing.md

View workflow job for this annotation

GitHub Actions / spelling / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Semicolon] Try to simplify this sentence.

Raw Output:
{"message": "[Microsoft.Semicolon] Try to simplify this sentence.", "location": {"path": "docs/en/guides/contributing.md", "range": {"start": {"line": 80, "column": 45}}}, "severity": "INFO"}
`.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.

Check warning on line 83 in docs/en/guides/contributing.md

View workflow job for this annotation

GitHub Actions / spelling / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Passive] 'be moved' looks like passive voice.

Raw Output:
{"message": "[Microsoft.Passive] 'be moved' looks like passive voice.", "location": {"path": "docs/en/guides/contributing.md", "range": {"start": {"line": 83, "column": 31}}}, "severity": "INFO"}

Check warning on line 83 in docs/en/guides/contributing.md

View workflow job for this annotation

GitHub Actions / spelling / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Semicolon] Try to simplify this sentence.

Raw Output:
{"message": "[Microsoft.Semicolon] Try to simplify this sentence.", "location": {"path": "docs/en/guides/contributing.md", "range": {"start": {"line": 83, "column": 14}}}, "severity": "INFO"}
- 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
Expand Down
16 changes: 11 additions & 5 deletions docs/en/references/governance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,13 @@
## 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

Check warning on line 40 in docs/en/references/governance.md

View workflow job for this annotation

GitHub Actions / spelling / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Passive] 'is pinned' looks like passive voice.

Raw Output:
{"message": "[Microsoft.Passive] 'is pinned' looks like passive voice.", "location": {"path": "docs/en/references/governance.md", "range": {"start": {"line": 40, "column": 1}}}, "severity": "INFO"}
trailing comment; the current version is **`v2.0.0`**. Read the digest from the

Check warning on line 41 in docs/en/references/governance.md

View workflow job for this annotation

GitHub Actions / spelling / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Semicolon] Try to simplify this sentence.

Raw Output:
{"message": "[Microsoft.Semicolon] Try to simplify this sentence.", "location": {"path": "docs/en/references/governance.md", "range": {"start": {"line": 41, "column": 17}}}, "severity": "INFO"}
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 |
|----------|-----------------|
Expand All @@ -57,8 +61,10 @@
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,

Check warning on line 66 in docs/en/references/governance.md

View workflow job for this annotation

GitHub Actions / spelling / runner / vale 

[vale] reported by reviewdog 🐶
[Microsoft.Passive] 'be moved' looks like passive voice.

Raw Output:
{"message": "[Microsoft.Passive] 'be moved' looks like passive voice.", "location": {"path": "docs/en/references/governance.md", "range": {"start": {"line": 66, "column": 50}}}, "severity": "INFO"}
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.
Expand Down
Loading