docsy(v2): record retired pins, and deploy their redirects from that (#1507)

Seeds `retired` with the four pins already retired plus v2.6.2.0, which the next
cut retires. Their redirect rows are removed from redirects.csv in
unionai-docs-infra#TBD and derived from this list instead, so a pin's retirement
and its redirect can no longer drift apart -- they are one edit now.

The workflow fires on versions.toml as well as the submodule pointer, because a
change to `retired` changes the deployed set exactly as a CSV edit does, and
fetches both branches because the deploy reads both lines.

Seeding v2.6.2.0 before its cut merges means it redirects while its tree is still
published, which is deliberate: the alternative ordering leaves 404s, and it
resolves when the cut lands. Same trade as the v2.6.1.0 row.

Verified by dry run: 8,760 redirect sources before, 8,761 after, the addition
being v2.6.2.0. Nothing lost, no duplicate sources.

DOC-1497.

Signed-off-by: Peeter Piegaze <1153481+ppiegaze@users.noreply.github.com>
Co-authored-by: docsy <docsy@union.ai>

Author: ppiegaze

.github/workflows/deploy-redirects.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
   push:
     branches: [main, v1]
-    paths: ['unionai-docs-infra']
+    paths: ['unionai-docs-infra', 'versions.toml']
 
 jobs:
   deploy-redirects:
@@ -18,7 +18,7 @@ jobs:
           submodules: 'true'
           fetch-depth: 2  # Need previous commit to detect submodule changes
 
-      - name: Check if redirects.csv changed
+      - name: Check if the deployed redirect set changed
         id: check-redirects
         run: |
           set -euo pipefail
@@ -30,6 +30,13 @@ jobs:
           fi
           # For push events, check if the unionai-docs-infra submodule ref changed and
           # whether that change includes redirects.csv
+          # Retired-pin redirects are derived from versions.toml `retired`, so a
+          # change there changes the deployed set just as much as a CSV edit does.
+          if ! git diff --quiet HEAD~1 HEAD -- versions.toml; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "versions.toml changed, proceeding with deploy."
+            exit 0
+          fi
           OLD_REF=$(git diff HEAD~1 HEAD -- unionai-docs-infra | grep "^-Subproject" | awk '{print $3}' || true)
           NEW_REF=$(git diff HEAD~1 HEAD -- unionai-docs-infra | grep "^+Subproject" | awk '{print $3}' || true)
           if [ -z "$OLD_REF" ] || [ -z "$NEW_REF" ]; then
@@ -57,6 +64,12 @@ jobs:
         with:
           python-version: '3.12'
 
+      # deploy_redirects.py reads BOTH lines' versions.toml. The checkout has only
+      # this branch, so make the sibling ref resolvable or the deploy fails closed.
+      - name: Fetch both documentation lines
+        if: steps.check-redirects.outputs.changed == 'true'
+        run: git fetch --depth=1 origin main v1
+
       - name: Deploy redirects to Cloudflare
         if: steps.check-redirects.outputs.changed == 'true'
         env:

versions.toml

@@ -9,9 +9,21 @@ stable = "v2.6.6.0"
 # Retention: Cloudflare Pages caps a deployment at 20,000 files, and every
 # entry here materializes another full site tree (~3,000 files). Seven trees
 # broke the deploy outright on 2026-08-21. Keep this list short; retiring a
-# pin needs a redirect row in unionai-docs-infra/redirects.csv.
+# pin is recorded in `retired` below, which is where its redirect comes from.
 enumerated = [
   "v2.6.2.0",
   "v2.6.3.0",
   "v2.6.5.0",
 ]
+# Pins that have been retired. A pin leaves `enumerated` and arrives here in the
+# same edit, made by `manifest.py --promote`, and its redirect is DERIVED from
+# this list at deploy time -- do NOT add a row to redirects.csv (DOC-1497; see
+# unionai-docs-infra/VERSIONING.md "Retired pins redirect themselves").
+retired = [
+  "v2.5.16.3",
+  "v2.5.18.3",
+  "v2.6.0.0",
+  "v2.6.1.0",
+  "v2.6.2.0",
+]
+