From fa0816c3da92073b172a09ae917b5d5943d85e7e Mon Sep 17 00:00:00 2001
From: Nils Lehnen <30603423+iderex@users.noreply.github.com>
Date: Fri, 21 Aug 2026 15:56:44 +0200
Subject: [PATCH] Restore the reason a pin comment names the exact version
 (#155)

This does not finish #155. Four more of the path groups that commit removed are
still missing.

What was wrong. `d3edfc95b8526033c79cb26afe48282c2c090e32` took its tree from an
older state of the default branch and landed on top of a newer one, under a
message describing a change to how one workflow pin is commented. Two of the
seven paths it replaced are the two workflow files that carry the reason for
that spelling, so the change kept the state and dropped the argument for it.

Sixteen comment lines come back in `.github/workflows/codeql.yml`, saying why
the version in a pin comment is the exact one the commit is tagged as rather
than the major: both spellings leave the same commit running, so the whole
difference is what the comment claims, and a comment reading a major stops being
true on the day upstream tags a release without anybody here touching a file.
The blob is the bytes that were there:

    git rev-parse 90656ba:.github/workflows/codeql.yml
    ea3a07e8b0c43135d70a446cedca1505cb745a8a
    git hash-object .github/workflows/codeql.yml
    ea3a07e8b0c43135d70a446cedca1505cb745a8a

In `.github/workflows/zizmor.yml` only the comment goes back and the pin stays
where it moved to. The header had returned to listing a pin comment that
disagrees with its commit as a pedantic hygiene finding the gate does not
collect, which is not what the tool does: the regular persona reports it at
medium and the gate runs at `--min-severity=low`, so the step below fails the
build on one.

What failure this prevents is the next edit spelling a pin comment as a major
because the two files no longer say why not, and a reader taking the pedantic
list for the complete set of what the gate lets through.

Both claims the restored text rests on were re-read rather than trusted:

    git grep -nE 'uses: .*@[0-9a-f]{40} # v[0-9]+$' -- .github/workflows/
    exit=1
    grep -n 'Fail on actionable findings' .github/workflows/zizmor.yml
    82:        # skip the "Fail on actionable findings" step below.
    90:      - name: Fail on actionable findings

No line outside a comment changed in either file, and every pin still names an
exact version.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
---
 .github/workflows/codeql.yml | 16 ++++++++++++++++
 .github/workflows/zizmor.yml | 17 ++++++++++++-----
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index 7d027bb..ea3a07e 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -23,6 +23,22 @@
 # top and granted per job, every action pinned to a commit with its version in a
 # comment, and checkout without persisted credentials. The one write scope here
 # is security-events, which is what uploading the results needs and nothing more.
+#
+# The version in that comment is the exact one the pinned commit is tagged as,
+# never the major. Both spellings leave the same commit running, so the whole
+# difference is in what the comment claims. A comment reading v4 is a claim about
+# a reference upstream moves, and it stops being true on the day upstream tags a
+# release without anybody here touching a file; an exact version is a claim about
+# the commit written next to it, which cannot go stale on its own. The two steps
+# below carried a major until this comment landed, and were the only two sites in
+# this tree that did. The command that says so prints nothing now, and printing
+# nothing is the state to keep it in:
+#
+#   git grep -nE 'uses: .*@[0-9a-f]{40} # v[0-9]+$' -- .github/workflows/
+#
+# The audit in zizmor.yml reads the comment against the tags the pinned commit
+# carries and fails the build on a mismatch, so the spelling is held by a check
+# rather than by memory.
 name: CodeQL
 
 on:
diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml
index 801653c..150f97a 100644
--- a/.github/workflows/zizmor.yml
+++ b/.github/workflows/zizmor.yml
@@ -11,13 +11,20 @@
 # regular persona is the one zizmor documents for CI ("high-signal, low-noise,
 # actionable"). The pedantic persona is deliberately NOT used to gate: it adds
 # low-severity hygiene findings (undocumented permissions, missing concurrency,
-# pin-comment mismatches, unnamed jobs) that are stylistic, not security-blocking,
-# and some are context-blind (it would demand run-cancelling concurrency on a
-# publishing workflow, which must never be cancelled mid-publish). Those findings
-# are not gated here, and no issue on this tracker collects them today.
+# unnamed jobs) that are stylistic, not security-blocking, and some are
+# context-blind (it would demand run-cancelling concurrency on a publishing
+# workflow, which must never be cancelled mid-publish). Those findings are not
+# gated here, and no issue on this tracker collects them today.
+#
+# A pin comment that disagrees with the commit beside it is NOT in that set. This
+# line listed it as a pedantic hygiene finding and that was wrong: the regular
+# persona reports ref-version-mismatch at medium, so the step below fails the
+# build on one. Two of them did exactly that on every pull request against this
+# board, which is what corrected this sentence.
 #
 # Rule for future workflow changes: every new or edited workflow must pass this
-# gate before merge. Keep actions SHA-pinned, keep checkout on
+# gate before merge. Keep actions SHA-pinned, comment each pin with the exact
+# version its commit is tagged as rather than the major, keep checkout on
 # persist-credentials:false, grant write permissions per job (never
 # workflow-level), and never restore a cache in a job that publishes a release.
 name: Workflow Security Analysis