colinhacks · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -195,22 +195,47 @@ jobs:
         with:
           persist-credentials: false
 
-      # the job token cannot create a tag, so it is pushed with the deploy key the ruleset exempts, and the key file is gone after the push; nothing is installed in this job, so no dependency's script ever runs while the key is on disk
-      - name: Tag the release
+      # the job token cannot create a tag or move `release`, so both are pushed with the deploy key the rulesets exempt, and the key file is gone when the step ends, however it ends; nothing is installed in this job, so no dependency's script ever runs while the key is on disk
+      # reylo.dev serves the `release` branch, so the docs describe what npm serves: it moves to the release's tagged commit, past any docs fix cherry-picked onto the previous release, which main holds too. It follows the tag, not this run's commit, since a dispatch that only rewrites a release's notes runs on a main that may hold unreleased changes. Where `release` already holds the tag (that dispatch, or a re-run of this job), it is left as it is, docs fixes cherry-picked onto it since included; the shallow checkout can't tell, so GitHub's compare does. The tag is a lightweight one, so `ls-remote` names its commit.
+      - name: Tag the release and move the docs to it
         env:
           VERSION: ${{ needs.stage.outputs.version }}
           RELEASE_TAG_KEY: ${{ secrets.RELEASE_TAG_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          if git ls-remote --exit-code --tags origin "refs/tags/v$VERSION" > /dev/null; then
-            echo "v$VERSION is already tagged"
-            exit 0
-          fi
+          trap 'rm -f "$RUNNER_TEMP/release-tag-key"' EXIT
           printf '%s\n' "$RELEASE_TAG_KEY" > "$RUNNER_TEMP/release-tag-key"
           chmod 600 "$RUNNER_TEMP/release-tag-key"
           echo "github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl" > "$RUNNER_TEMP/known_hosts"
-          git tag "v$VERSION" "$GITHUB_SHA"
-          GIT_SSH_COMMAND="ssh -i $RUNNER_TEMP/release-tag-key -o IdentitiesOnly=yes -o UserKnownHostsFile=$RUNNER_TEMP/known_hosts" git push "git@github.com:$GITHUB_REPOSITORY.git" "refs/tags/v$VERSION"
-          rm "$RUNNER_TEMP/release-tag-key"
+          export GIT_SSH_COMMAND="ssh -i $RUNNER_TEMP/release-tag-key -o IdentitiesOnly=yes -o UserKnownHostsFile=$RUNNER_TEMP/known_hosts"
+          remote="git@github.com:$GITHUB_REPOSITORY.git"
+          if git ls-remote --exit-code --tags origin "refs/tags/v$VERSION" > /dev/null; then
+            echo "v$VERSION is already tagged"
+          else
+            git tag "v$VERSION" "$GITHUB_SHA"
+            git push "$remote" "refs/tags/v$VERSION"
+          fi
+          tagged="$(git ls-remote origin "refs/tags/v$VERSION" | cut -f1)"
+          # `identical` or `ahead`: release is the tag, or the tag with docs fixes on it. Only a missing branch (ls-remote's exit 2) counts as missing; any other failure, of ls-remote or of the compare, fails the step rather than move release back, and a re-run is safe.
+          set +e
+          git ls-remote --exit-code --heads origin release > /dev/null
+          found=$?
+          set -e
+          case "$found" in
+            0) status="$(gh api "repos/$GITHUB_REPOSITORY/compare/$tagged...release" --jq .status)" ;;
+            2) status=missing ;;
+            *) echo "::error::could not read whether release exists (git ls-remote exited $found)"; exit 1 ;;
+          esac
+          case "$status" in
+            identical | ahead)
+              echo "release already holds v$VERSION ($status), and is left as it is"
+              ;;
+            *)
+              git cat-file -e "$tagged^{commit}" 2> /dev/null || git fetch --quiet --depth=1 origin "$tagged"
+              git push --force "$remote" "$tagged:refs/heads/release"
+              echo "release moved to v$VERSION ($tagged) from $status"
+              ;;
+          esac
 
       # the notes go through env and a file so their text can't break out of the command; a re-dispatch with corrected notes rewrites an existing release's body
       - name: Create release

diff --git a/AGENTS.md b/AGENTS.md
@@ -124,7 +124,7 @@ The run time, the mapper, the adapters and the CLI live in `src/` (the table abo
 
 ### A docs change
 
-The docs are `site/content/docs/`: the main page `index.mdx`, which continues in one numbered file per h2 section in `site/content/sections/` (`01-setup.mdx` to `09-faq.mdx`), and one reference page per dialect (`postgres.mdx`, `mysql.mdx`, `sqlite.mdx`) with every rule and edge case of its database. Every push to `main` deploys reylo.dev.
+The docs are `site/content/docs/`: the main page `index.mdx`, which continues in one numbered file per h2 section in `site/content/sections/` (`01-setup.mdx` to `09-faq.mdx`), and one reference page per dialect (`postgres.mdx`, `mysql.mdx`, `sqlite.mdx`) with every rule and edge case of its database. reylo.dev serves the `release` branch, which each release moves to its tagged commit, so the docs describe what npm serves; a push to `main` builds a preview. A docs change that holds for the released version (a typo, a clearer sentence, a missing example) can go live before the next release: after it lands on `main`, cherry-pick its commit onto `release` and push, which only ever moves forward.
 
 1. Every type and error shown on the page is captured, never typed by hand. After changing a `.sql` block or a page's schema, run `nub run capture` in `site/` with throwaway servers of both kinds: `REYLO_CAPTURE_POSTGRES=postgres://postgres@localhost:<pg port>/reylo_capture REYLO_CAPTURE_MYSQL=mysql://root@127.0.0.1:<mysql port>/reylo_capture` (the database is dropped and made again, so its name must start with `reylo_capture`). It rewrites `site/lib/sql-modules.json` and `site/lib/sql-errors.json`.
 2. `nub run build` in `site/` type-checks and builds the site to `site/build/client`, and fails on a stale capture. `nub run dev --port <port> --strictPort` in `site/` serves it (3311 by default).