feat(ci): trigger publish on release tags, auto-register and prune versions (#1292)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pdmack

.github/workflows/publish-fern-docs.yml

@@ -1,15 +1,15 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
-# Publishes the Fern documentation site when a docs tag is pushed or manually triggered.
+# Publishes the Fern documentation site on release tag push or manual dispatch.
 #
-# On a docs/vX.Y.Z tag push the workflow also:
+# On a vX.Y.Z release tag push the workflow also:
 #   1. Generates fern/versions/vX.Y.Z.yml from the tag's docs/index.yml
 #   2. Adds a version entry to fern/docs.yml
-#   3. Commits both back to main so future publishes include the new version
+#   3. Prunes older versions to keep only the 3 most recent (plus Latest)
+#   4. Commits changes back to main so future publishes include the new version
 #
-# To publish:  git tag docs/v1.2.0 && git push origin docs/v1.2.0
-# Or use the "Run workflow" button in the Actions tab.
+# Pre-release tags (e.g. v1.6.0-rc1) trigger publish but skip version registration.
 #
 # Required configuration:
 # - Repository secret: DOCS_FERN_TOKEN (provisioned by the docs infrastructure team)
@@ -19,7 +19,7 @@ name: Publish Fern Docs
 on:
   push:
     tags:
-      - "docs/v*"
+      - "v[0-9]*.[0-9]*.[0-9]*"
   workflow_dispatch: {}
 
 permissions:
@@ -29,6 +29,9 @@ concurrency:
   group: fern-publish
   cancel-in-progress: true
 
+env:
+  MAX_VERSIONS: 3
+
 jobs:
   publish:
     name: Publish Fern Docs
@@ -41,47 +44,66 @@ jobs:
           ref: main
 
       - name: Register new version from tag
-        if: startsWith(github.ref, 'refs/tags/docs/v')
+        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-')
         run: |
           set -eo pipefail
-          TAG_VERSION="${GITHUB_REF#refs/tags/docs/}"  # e.g. v1.5.0
+          TAG_VERSION="${GITHUB_REF#refs/tags/}"  # e.g. v1.5.0
 
           # Skip if version file already exists
           if [ -f "fern/versions/${TAG_VERSION}.yml" ]; then
             echo "Version file fern/versions/${TAG_VERSION}.yml already exists — skipping"
             exit 0
           fi
 
-          # Extract index.yml from the matching release tag
-          if ! git rev-parse "$TAG_VERSION" >/dev/null 2>&1; then
-            echo "::warning::Release tag $TAG_VERSION not found — cannot create version entry"
-            exit 0
-          fi
-
           # Generate version nav from the tag's docs/index.yml
           echo "Generating fern/versions/${TAG_VERSION}.yml from tag $TAG_VERSION"
-          git archive "$TAG_VERSION" -- docs/index.yml | tar -xO docs/index.yml | \
+          git archive "${TAG_VERSION}" -- docs/index.yml | tar -xO docs/index.yml | \
             sed "s|path: |path: ${TAG_VERSION}-content/|g" > "fern/versions/${TAG_VERSION}.yml"
 
           # Add version entry to docs.yml (insert after Latest, before older versions)
           export TAG_VERSION
           yq -i '.products[0].versions |= [.[0]] + [{"display-name": env(TAG_VERSION), "path": "versions/" + env(TAG_VERSION) + ".yml", "slug": env(TAG_VERSION), "availability": "stable"}] + .[1:]' fern/docs.yml
 
-          echo "--- docs.yml versions ---"
-          grep "display-name:" fern/docs.yml
+          echo "--- docs.yml versions after insert ---"
+          yq '.products[0].versions[].display-name' fern/docs.yml
+
+      - name: Prune old versions
+        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-')
+        run: |
+          set -eo pipefail
+          KEEP=$((MAX_VERSIONS + 1))  # +1 for the Latest entry at index 0
+
+          # Count current versioned entries (including Latest)
+          TOTAL=$(yq '.products[0].versions | length' fern/docs.yml)
+          if [ "$TOTAL" -le "$KEEP" ]; then
+            echo "Only $TOTAL version entries — nothing to prune"
+            exit 0
+          fi
+
+          # Remove excess entries from the end (oldest) and their version files
+          PRUNED=$(yq ".products[0].versions[$KEEP:].[].slug" fern/docs.yml)
+          yq -i ".products[0].versions |= .[:$KEEP]" fern/docs.yml
+
+          for slug in $PRUNED; do
+            rm -f "fern/versions/${slug}.yml"
+            echo "Pruned version $slug"
+          done
+
+          echo "--- docs.yml versions after prune ---"
+          yq '.products[0].versions[].display-name' fern/docs.yml
 
-      - name: Commit new version entry
-        if: startsWith(github.ref, 'refs/tags/docs/v')
+      - name: Commit version changes
+        if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-')
         run: |
-          TAG_VERSION="${GITHUB_REF#refs/tags/docs/}"
-          if git diff --quiet fern/; then
+          TAG_VERSION="${GITHUB_REF#refs/tags/}"
+          if git diff --quiet fern/ && [ -z "$(git ls-files --deleted fern/)" ]; then
             echo "No version changes to commit"
             exit 0
           fi
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add fern/versions/ fern/docs.yml
-          git commit -m "chore(fern): add ${TAG_VERSION} version entry [automated]"
+          git commit -m "chore(fern): register ${TAG_VERSION}, keep latest ${MAX_VERSIONS} versions [automated]"
           git push origin main
 
       - name: Checkout frozen version content