docs: correct the pinning contract to digest pins - #45
Merged
Conversation
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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4KA8swD1ZzDqknDV5TUxx
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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A4KA8swD1ZzDqknDV5TUxx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PR #40 moved every workflow
uses:reference to a full-length commit digest,but four prose locations still describe the old tag-based scheme.
CLAUDE.mdisthe binding instruction file for AI-assisted edits here, so its stale claim
actively invites an agent to replace the digest pins with tags and undo the
supply-chain protection.
Changes
CLAUDE.md§CI: state the digest form, name the current digest, and forbidreplacing it with a bare tag. Was
Pinning is by tag (currently v1.1.10).docs/{en,de}/references/governance.md§Reusable workflows: name the digestwith its version instead of
v1.1.18.docs/{en,de}/references/governance.md§Dependency governance: replace "Allpins use released tags" with the digest requirement, and give the reason.
docs/{en,de}/guides/contributing.md§Pull request flow: same correction forcontributors.
Linked issues
None
Testing
grep -rho 'gh-plumbing/.github/workflows/[^@]*@[a-f0-9]*' .github/workflows/ | sed 's/.*@//' | sort -u→ a single value,d51e51ec3ec17ceea09fe9eb40ac00857b6fa1be. Every workflow is on one digest,so naming one current pin is accurate.
task --yes lint— all pre-commit hooks pass.vale --minAlertLevel=erroron the five changed files:0 errors, 0 warnings and 0 suggestions in 5 files.vale --minAlertLevel=error docs/ CLAUDE.mdreports 11 errors both ondevelopand on this branch. Those 11are pre-existing and live in files this PR doesn't touch.
Risk / rollout notes
None. Documentation only; no workflow, module, or consumer-facing behaviour
changes.
Two adjacent observations, deliberately not fixed here to keep the change
reviewable:
v1.1.18occurrence ingovernance.md§Vale and prose is an illustrativeexample of a version-pin-shaped token for the disabled
Microsoft.Rangesrule,not a claim about the current pin. Correctly left as is.
docs/{en,de}/guides/contributing.md§Pull request flow opens with "Branch offmain". The integration branch isdevelop— PRs fix(ci): make the refresh-master manual dispatch usable #43 and feat(ci): mint an App token for the presentation-branch refresh #44 both target it.That is a second stale contributor instruction of the same class and deserves
its own PR.
Originating source:
/code-reviewof PR #43, which flagged the governance and CLAUDE.md staleness while reviewing an unrelated diffDispatched specialist: no matching specialist existed — generalist handled