docs(anvil): document the action pinning policy - #128
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR reduces recurring review noise in anvil-managed GitHub workflow YAML by replacing the ambiguous “tag cannot be moved” comment with a checkable, mechanism-naming marker (# GitHub immutable release), and it documents the pinning policy in the cargo-anvil GitHub design doc.
Changes:
- Reword tag-pin markers in templates, generated snapshots, and this repo’s workflows to
# GitHub immutable release. - Document the tag-vs-SHA pinning policy (and how to re-verify immutability when bumping) in
crates/cargo-anvil/docs/design/github.md. - Update the design doc’s YAML example snippet to use the new marker.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| crates/cargo-anvil/tests/snapshots/snapshots__github_backend.snap | Updates snapshot text to match the new immutable-release marker in generated backend output. |
| crates/cargo-anvil/templates/github/setup-action.yml | Updates the tag-pin comment for cargo-binstall to the new marker. |
| crates/cargo-anvil/templates/github/scheduled-impl-workflow.yml | Updates the tag-pin comment for Codecov to the new marker. |
| crates/cargo-anvil/templates/github/pr-impl-workflow.yml | Updates the tag-pin comments for sticky comment + Codecov to the new marker. |
| crates/cargo-anvil/docs/design/github.md | Adds an “Action pinning” section documenting the policy and verification steps; updates example marker. |
| .github/workflows/main.yml | Updates tag-pin comments used in the repo CI workflow to the new marker. |
| .github/workflows/codeql.yml | Updates tag-pin comments for CodeQL immutable releases to the new marker. |
| .github/workflows/anvil-scheduled-impl.yml | Updates Codecov tag-pin marker in the anvil-managed scheduled workflow. |
| .github/workflows/anvil-pr-impl.yml | Updates sticky comment + Codecov tag-pin markers in the anvil-managed PR workflow. |
| .github/actions/setup/action.yml | Updates the tag-pin marker for taiki-e/install-action to the new marker. |
| .github/actions/anvil-setup/action.yml | Updates the tag-pin marker for cargo-binstall to the new marker. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Codecov Report✅ All modified and coverable lines are covered by tests. ❌ Your project status has failed because the head coverage (97.7%) is below the target coverage (100.0%). You can increase the head coverage or adjust the target coverage. Additional details and impacted files@@ Coverage Diff @@
## main #128 +/- ##
=====================================
Coverage 97.7% 97.7%
=====================================
Files 286 286
Lines 62438 62438
=====================================
+ Hits 61008 61009 +1
+ Misses 1430 1429 -1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
anvil pins third-party actions two ways: by tag where the publisher has enabled GitHub immutable releases, and by commit SHA everywhere else with the version in a trailing comment. The rule was applied consistently but written down nowhere, so from the generated output alone the tag pins look like an inconsistency rather than a decision. That gap has a measurable cost. On microsoft/oxidizer#718 an automated reviewer flagged the tag pins four times in one review, once per pinned action, each time recommending a revert to SHA pinning on the grounds that Git tags are movable. The general rule is correct; it just does not apply to a tag held by an immutable release. Without the policy recorded anywhere, the same objection recurs on every adopting repo. Add an "Action pinning" subsection to the GitHub backend design under Security, covering what an immutable release actually guarantees, why that makes a tag an acceptable pin, and the fact that immutability is a property of one published release rather than a standing guarantee about the publisher -- so a bump must re-verify it and fall back to a SHA when the check fails. Documentation only; no template, workflow or behaviour changes. The five tag-pinned actions were re-checked while writing this and all report `immutable: true`: codecov/codecov-action v7.0.0, marocchino/sticky-pull-request-comment v3.0.5, cargo-bins/cargo-binstall v1.21.0, taiki-e/install-action v2.81.8 and github/codeql-action v4.37.7. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Evgenii (Vaiz)
force-pushed
the
u/vaiz/2026/09/01/anvil-pin-comment
branch
from
September 1, 2026 11:02
c1c78e6 to
32575ff
Compare
Evgenii (Vaiz)
changed the title
Address review feedback on the new "Action pinning" section: fix the "pinned one of two ways" grammar, and make clear the three tag-pinned actions are the current generated-workflow set rather than an exhaustive list, since a repository's own workflows apply the same rule to their own actions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The 0.6.0 version bump (#125) did not regenerate the lock, so it still recorded tool_version = "0.5.0". regenerate-check therefore fails on every branch whose merge-base includes that bump: the job reports "Manifest update required: 1 item(s) - .anvil.lock" with all 86 generated files unchanged. Produced by `cargo run -p cargo-anvil -- anvil`; a re-run is now a no-op. Only the tool_version line changes. No generated file, template or workflow is touched. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Kateřina Churanová (kate-shine)
approved these changes
Sep 1, 2026
martintmk
approved these changes
Sep 1, 2026
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
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.
🤖 Clawpilot here! Posted automatically by Clawpilot (an AI agent), not by a human. Please verify before acting.
Problem
anvil pins third-party actions two ways: by tag where the publisher has enabled GitHub immutable releases, and by commit SHA everywhere else with the version in a trailing comment. The rule is applied consistently, but it is written down nowhere — so from the generated output alone the tag pins look like an inconsistency rather than a decision.
That gap has a measurable cost. On microsoft/oxidizer#718 an automated reviewer flagged the tag pins four times in one review, once per pinned action, each time recommending a revert to SHA pinning because Git tags are movable. The general rule is correct; it just does not apply to a tag held by an immutable release. With the policy unrecorded, the same objection recurs on every adopting repo.
Change
Adds an "Action pinning" subsection to
crates/cargo-anvil/docs/design/github.mdunder §9 Security, covering:The inline
# immutable release, the tag cannot be movedmarker is unchanged. An earlier revision of this PR shortened it to# GitHub immutable releaseacross 22 sites; that was dropped as unnecessary churn, and the existing wording stands.No template, workflow or behaviour changes.
Also: a one-line
.anvil.lockrefreshThe second commit sets
tool_versionin.anvil.lockfrom0.5.0to0.6.0. This is unrelated to the documentation above and fixes a break onmainrather than one introduced here.The 0.6.0 bump in #125 did not regenerate the lock, so
regenerate-checkfails on every branch whose merge-base includes that commit — the job reportsManifest update required: 1 item(s) — .anvil.lockwith all 86 generated files unchanged. This PR was simply the first to hit it (merge-base 6d99b19); PRs branched earlier, such as #127 and #120 at 17f0aea, still pass and will start failing once rebased.The fix was produced by
cargo run -p cargo-anvil -- anviland is exactly one line — a second run is a no-op, and no generated file, template or workflow is touched. It is carried here rather than in a separate PR at the maintainer's request; happy to split it out if that is preferred.Verification
The five tag-pinned actions were re-checked against the REST API while writing this, and all report
immutable: true:immutablecodecov/codecov-actionmarocchino/sticky-pull-request-commentcargo-bins/cargo-binstalltaiki-e/install-actiongithub/codeql-actionanvil-spellcheckandcargo test --package cargo-anvil(472 tests, including thesnapshots__github_backendsnapshot) both pass locally on the pinned 1.97 toolchain, andcargo run -p cargo-anvil -- anvilnow reports no pending changes.