Background
Convention used in this repo's workflow files:
- name: Set up Docker Buildx
# docker/setup-buildx-action pinned to full commit SHA — v3.12.0
uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd
Dependabot maintains the SHA on the uses: line and any inline trailing # v<version> comment on that same line. It does NOT update standalone comment lines above the uses: directive — those are opaque text to its parser.
Symptom
After a Dependabot bump, the SHA on line N moves to the new version but the # … pinned to full commit SHA — v<version> line on line N-1 still shows the old version. Surfaced empirically on PR #397 (round 1) — docker-smoke.yml lines 51 and 55 carried v3.12.0 / v6.19.2 markers after the SHAs had already moved to v4.0.0 / v7.1.0. Round 2 fix updated the comments by hand.
Options
-
Switch convention to inline trailing comments — uses: docker/setup-buildx-action@<sha> # v<version>. Dependabot DOES maintain inline trailing comments via its YAML parser, so the version stays in sync automatically. Trade-off: longer line, slightly less readable than the comment-above-line layout.
-
Remove the human-readable version comments entirely. The SHA is the source of truth; readers can resolve the version via gh api repos/<owner>/<repo>/git/refs/tags/v<X> or git show <sha>. Trade-off: loses the at-a-glance version visibility.
-
Keep the convention; document the drift expectation. Update CONTRIBUTING.md / dependabot-pr-hygiene-playbook awareness entry to note that # X pinned to full commit SHA — vY standalone comment lines are best-effort and contributors / QA must update them when reviewing Dependabot PRs.
-
Add a CI check that diffs the comment version against git ls-remote lookup for each pinned SHA in the workflows directory. Catches drift at PR-open time. Trade-off: extra workflow + more failure modes.
Recommendation
Option 1 (inline trailing comments) is the lowest-effort durable fix — Dependabot's grouped-update PR body now reliably reports prevVersion/newVersion (since the v3.1.0 fix in #400) and the inline comment travels with the SHA via Dependabot's YAML parser. One PR sweeps all workflow files in this repo. Option 3 is a fallback if 1 turns out to have edge cases (e.g., reusable-action declarations or composite steps where YAML comments behave unexpectedly).
Acceptance
Source
Surfaced during round-1 QA review of PR #397 (this repo) by claude-qa, 2026-04-27. Round-2 fix on the dependabot branch is a one-time correction; this issue addresses the structural drift class.
🤖 Generated with Claude Code
Background
Convention used in this repo's workflow files:
Dependabot maintains the SHA on the
uses:line and any inline trailing# v<version>comment on that same line. It does NOT update standalone comment lines above theuses:directive — those are opaque text to its parser.Symptom
After a Dependabot bump, the SHA on line N moves to the new version but the
# … pinned to full commit SHA — v<version>line on line N-1 still shows the old version. Surfaced empirically on PR #397 (round 1) —docker-smoke.ymllines 51 and 55 carried v3.12.0 / v6.19.2 markers after the SHAs had already moved to v4.0.0 / v7.1.0. Round 2 fix updated the comments by hand.Options
Switch convention to inline trailing comments —
uses: docker/setup-buildx-action@<sha> # v<version>. Dependabot DOES maintain inline trailing comments via its YAML parser, so the version stays in sync automatically. Trade-off: longer line, slightly less readable than the comment-above-line layout.Remove the human-readable version comments entirely. The SHA is the source of truth; readers can resolve the version via
gh api repos/<owner>/<repo>/git/refs/tags/v<X>orgit show <sha>. Trade-off: loses the at-a-glance version visibility.Keep the convention; document the drift expectation. Update CONTRIBUTING.md /
dependabot-pr-hygiene-playbookawareness entry to note that# X pinned to full commit SHA — vYstandalone comment lines are best-effort and contributors / QA must update them when reviewing Dependabot PRs.Add a CI check that diffs the comment version against
git ls-remotelookup for each pinned SHA in the workflows directory. Catches drift at PR-open time. Trade-off: extra workflow + more failure modes.Recommendation
Option 1 (inline trailing comments) is the lowest-effort durable fix — Dependabot's grouped-update PR body now reliably reports
prevVersion/newVersion(since the v3.1.0 fix in #400) and the inline comment travels with the SHA via Dependabot's YAML parser. One PR sweeps all workflow files in this repo. Option 3 is a fallback if 1 turns out to have edge cases (e.g., reusable-action declarations or composite steps where YAML comments behave unexpectedly).Acceptance
.github/workflows/*.ymlmigrating standalone version-pin comments to inline trailing form. Verify each migration manually so the# v<version>next to the SHA matches the upstream tag at the SHA. Smoke-test by waiting for the next routine Dependabot grouped bump and confirming the inline comment updates.dependabot-pr-hygiene-playbookawareness entry (logical_key=dependabot-pr-hygiene-playbook) so cascade targets pick up the right pattern from the start. Stack with chore(playbook): fold bracketed-Unreleased detection into dependabot-pr-hygiene-playbook #401 (bracketed-Unreleased detection) — both are playbook-level enrichments surfaced during PR chore(deps,ci): port dependabot-pr-hygiene playbook to mcp-awareness #400 and chore(deps): bump the github-actions group across 1 directory with 2 updates #397 rounds 1.Source
Surfaced during round-1 QA review of PR #397 (this repo) by claude-qa, 2026-04-27. Round-2 fix on the dependabot branch is a one-time correction; this issue addresses the structural drift class.
🤖 Generated with Claude Code