Name the shared workflow as signer in the verify command

.github/workflows/go-release.yml

@@ -21,6 +21,10 @@
 # the release notes from the tag's CHANGELOG section (fail closed); push the module's subdirectory
 # alias tag (src/vX.Y.Z); run GoReleaser; read the published notes back; run the caller's optional
 # post-release command (extra assets); attest build provenance for everything checksummed.
+#
+# This workflow signs the attestation, so a downloaded asset verifies with it named as the signer:
+#   gh attestation verify <file> --repo OWNER/REPO --signer-workflow simtabi/.github/.github/workflows/go-release.yml
+# Without --signer-workflow, gh expects a workflow in the caller's repository and the check fails.
 name: Go release
 
 on:

go-release/README.md

@@ -39,6 +39,18 @@ Build provenance is attested for `checksums.txt` and any extra assets on a **pub
 only: GitHub Free refuses attestations on a private one, so both steps skip when
 `github.event.repository.private` is true. The release itself still publishes.
 
+This workflow is what signs, not the caller's `release.yml`, so a check of a downloaded asset names
+it as the signer:
+
+```bash
+gh attestation verify authama_linux_amd64 --repo simtabi/authama \
+  --signer-workflow simtabi/.github/.github/workflows/go-release.yml
+```
+
+Without `--signer-workflow`, `gh` expects a workflow in the caller's repository and fails with
+`Error: verifying with issuer "sigstore.dev"` (measured 2026-11-13 against simtabi/authama v0.1.6,
+which verified with the flag). A caller's docs should show the command with it.
+
 ## What it refuses
 
 - a tag that is not `vX.Y.Z[-pre]`, or is not on GitHub;

go-release/tests/test_go_release.py

@@ -11,6 +11,10 @@
 ROOT = Path(__file__).resolve().parents[2]
 WORKFLOW = ROOT / ".github" / "workflows" / "go-release.yml"
 TEMPLATE = ROOT / "templates" / "go" / "release.yml"
+README = ROOT / "go-release" / "README.md"
+
+# The shared workflow signs every caller's provenance, so a verify command has to name it.
+SIGNER = "--signer-workflow simtabi/.github/.github/workflows/go-release.yml"
 
 # Every GoReleaser block that publishes somewhere other than the GitHub release.
 CHANNELS = {
@@ -109,3 +113,19 @@ def test_it_calls_the_shared_workflow(self):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class VerifyCommands(unittest.TestCase):
+    """Every `gh attestation verify` shown names this workflow as the signer: without it, gh expects
+    a workflow in the caller's repository and the check fails (simtabi/authama v0.1.6, 2026-11-13)."""
+
+    def test_each_verify_command_names_the_shared_signer(self):
+        found = 0
+        for path in (WORKFLOW, TEMPLATE, README):
+            text = re.sub(r"\\\n\s*", " ", path.read_text())
+            for line in text.splitlines():
+                if "gh attestation verify" not in line:
+                    continue
+                found += 1
+                self.assertIn(SIGNER, " ".join(line.split()), f"{path.name}: {line.strip()}")
+        self.assertGreaterEqual(found, 3, "the workflow, template and README should each show the command")

templates/go/release.yml

@@ -5,6 +5,9 @@
 #   gh workflow run release.yml --repo OWNER/REPO -f tag=vX.Y.Z  the same, for a tag already pushed
 #
 # Push a version tag only for final code: tags are final, and a pushed tag publishes.
+#
+# The shared workflow signs the provenance, so a downloaded asset verifies with it as the signer:
+#   gh attestation verify <file> --repo OWNER/REPO --signer-workflow simtabi/.github/.github/workflows/go-release.yml
 name: Release
 
 on: