From 8f69e713110258b75b13d0bfc6a1115ad9302035 Mon Sep 17 00:00:00 2001
From: steve <steve@stevedudenhoeffer.com>
Date: Sun, 28 Jun 2026 04:17:19 +0000
Subject: [PATCH] docs: recommend the @v1 release tag for reusable-workflow
 consumers (#12)

---
 .gitea/workflows/review-reusable.yml |  7 ++++---
 README.md                            |  6 ++++--
 examples/reusable.yml                | 13 +++++++------
 3 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/.gitea/workflows/review-reusable.yml b/.gitea/workflows/review-reusable.yml
index ae6625f..c97a1e0 100644
--- a/.gitea/workflows/review-reusable.yml
+++ b/.gitea/workflows/review-reusable.yml
@@ -6,7 +6,7 @@
 #   jobs:
 #     review:
 #       if: ...                      # actor gate for the comment trigger
-#       uses: steve/gadfly/.gitea/workflows/review-reusable.yml@<sha>
+#       uses: steve/gadfly/.gitea/workflows/review-reusable.yml@v1
 #       secrets:                     # forward ONLY what the reviewer needs
 #         OLLAMA_CLOUD_API_KEY:    ${{ secrets.OLLAMA_CLOUD_API_KEY }}
 #         CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
@@ -25,8 +25,9 @@
 #
 # Advisory only — never blocks a merge. The image is pinned to an immutable
 # :sha- tag here (act_runner caches :latest); bump it per Gadfly release.
-# Consumers should likewise pin `uses: ...@<sha>` (not @main) so a push to this
-# repo can't silently change the code that runs with their forwarded secrets.
+# Consumers should pin `uses: ...@v1` — a curated release tag moved on deliberate
+# releases, so central tuning here propagates without per-consumer edits — or a
+# full `@<sha>` for an immutable pin. Avoid `@main` (moves on every push).
 
 name: Gadfly review (reusable)
 
diff --git a/README.md b/README.md
index 577e574..fae53d6 100644
--- a/README.md
+++ b/README.md
@@ -312,8 +312,10 @@ examples/              the ~15-line stub a consuming repo drops in
 
 The image is published to `gitea.stevedudenhoeffer.com/steve/gadfly`. Every push to `main`
 rebuilds and republishes `:latest` (plus `:sha-<short>`); pushing a `v*` tag publishes that
-pinned version (plus `:latest`). Pin consumers to a `:vN` tag for stability, or track
-`:latest` to ride main.
+pinned version (plus `:latest`). Pin full-stub consumers to a `:vN` image tag for stability, or track
+`:latest` to ride main. Reusable-workflow consumers likewise pin the workflow ref —
+`review-reusable.yml@v1` (a curated tag moved on releases, so central swarm tuning propagates) or
+a full `@<sha>` for an immutable pin; avoid `@main`.
 
 ## Configuration (advanced)
 
diff --git a/examples/reusable.yml b/examples/reusable.yml
index a582053..751497a 100644
--- a/examples/reusable.yml
+++ b/examples/reusable.yml
@@ -14,9 +14,10 @@
 # Forward ONLY the secrets the reviewer uses (least privilege) — see the
 # `secrets:` block below. GITEA_TOKEN is automatic. `secrets: inherit` also works
 # but hands the reusable EVERY secret in your repo (registry/deploy/db creds the
-# review never touches), so prefer the explicit form. Pin @<sha> to an immutable
-# Gadfly commit (not @main) so a push there can't change what runs with your
-# secrets.
+# review never touches), so prefer the explicit form. Pin @<ref>: use the @v1
+# release tag (a curated pointer moved on deliberate releases) for auto-updating
+# stability, or a full @<sha> for an immutable pin. Avoid @main — it moves on
+# every push and would change what runs with your forwarded secrets.
 #
 # For custom named endpoints (GADFLY_ENDPOINT_<NAME>) or a provider the reusable
 # doesn't map, use the full stub in adversarial-review.yml instead.
@@ -48,9 +49,9 @@ jobs:
     if: >-
       github.event_name != 'issue_comment'
       || (github.event.issue.pull_request && github.actor == 'your-username')
-    # Pin @<sha> to an immutable Gadfly commit (replace @main below) so a push to
-    # gadfly can't silently change the code that runs with your forwarded secrets.
-    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@main
+    # @v1 = curated release tag (auto-updates on releases); swap for a full @<sha>
+    # if you want an immutable pin. Don't use @main (moves on every push).
+    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@v1
     # Forward ONLY what the reviewer needs. Add provider keys you use
     # (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, GADFLY_API_KEY) and/or
     # GADFLY_ENDPOINT_M1/M5; drop the findings ones if you don't run telemetry.