ci(docs): regenerate API references on main after a merge

.github/workflows/regenerate-api-references.yml

@@ -0,0 +1,126 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Keep main's generated API references current.
+#
+# The per-PR freshness gate is deliberately scoped: api_freshness.py blocks a
+# branch only when the branch itself touched something feeding a generator, so
+# a PR is never failed for drift main introduced. That scoping is right -- the
+# alternative fails whoever is unlucky at merge time. But it assumes the other
+# half of the sentence in api_freshness.py's own docstring:
+#
+#   "the next regeneration on main resolves it"
+#
+# Nothing regenerated main. Drift accumulated instead -- twice on 2026-08-11
+# alone (#12985, #13035) -- and the cost is not a red check: the strict check
+# runs BEFORE the sync/publish steps in fern-docs.yml, so stale output skips
+# the publish and docs.nvidia.com stops updating.
+#
+# This job is that missing half. It pushes a BRANCH, never main, because two
+# other routes are closed on this repo and both fail loudly if reintroduced:
+#
+#   * pushing to main         -> GH013 "Changes must be made through a pull
+#                                request" (community-events-refresh.yml has
+#                                failed this way on every run)
+#   * create-pull-request     -> "GitHub Actions is not permitted to create or
+#                                approve pull requests" (update-events.yml)
+#
+# So this mirrors auto-dep-upgrade-trigger.yml, the one automation here that
+# actually lands: push a branch with OPS_BOT_PAT and let a human open the PR.
+
+name: Regenerate API references
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Serialize: two merges landing close together would otherwise race two
+# regeneration branches.
+concurrency:
+  group: regenerate-api-references
+  cancel-in-progress: false
+
+jobs:
+  regenerate:
+    name: Regenerate API references
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          ref: main
+          token: ${{ secrets.OPS_BOT_PAT }}
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: '3.13'
+
+      - name: Install generator dependencies
+        run: python3 -m pip install 'griffe==2.1.0' pyyaml
+
+      - name: Regenerate
+        id: regen
+        run: |
+          set -euo pipefail
+          # gen_kubernetes_api.py re-renders a committed intermediate that
+          # `make generate-api-docs` produces from the operator Go types. That
+          # first hop needs Go and crd-ref-docs, so it stays a human's job;
+          # running the renderer here still catches renderer-side drift.
+          for g in gen_python_api gen_rust_api gen_kubernetes_api gen_llms_tables; do
+            python3 "docs/fern/scripts/${g}.py"
+          done
+          if [ -z "$(git status --porcelain -- docs/fern)" ]; then
+            echo "All generated references current; nothing to do."
+            echo "drifted=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Drift detected:"
+            git status --porcelain -- docs/fern
+            echo "drifted=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Compute branch name + idempotency check
+        if: steps.regen.outputs.drifted == 'true'
+        id: branch
+        run: |
+          # Keyed on the main SHA that drifted, so a re-run of the same merge
+          # reuses the branch instead of stacking near-identical ones.
+          BRANCH="docs/regen-api-references-${GITHUB_SHA::9}"
+          echo "name=$BRANCH" >> "$GITHUB_OUTPUT"
+          if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
+            echo "Branch $BRANCH already exists on origin; skipping."
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit + push regeneration branch
+        if: steps.regen.outputs.drifted == 'true' && steps.branch.outputs.exists == 'false'
+        run: |
+          set -euo pipefail
+          git config user.name  "dynamo-ops"
+          git config user.email "170655669+dynamo-ops@users.noreply.github.com"
+          git checkout -b "${{ steps.branch.outputs.name }}"
+          # Only ever stage generated docs: a bare `git add -A` would sweep up
+          # anything else the toolchain left in the workspace.
+          git add docs/fern
+          git commit -s \
+            -m "docs(api): regenerate API references" \
+            -m "Automated regeneration after ${GITHUB_SHA::9} moved a documented symbol." \
+            -m "Generated by .github/workflows/regenerate-api-references.yml."
+          git push origin "${{ steps.branch.outputs.name }}"
+
+      - name: Report
+        if: steps.regen.outputs.drifted == 'true' && steps.branch.outputs.exists == 'false'
+        run: |
+          {
+            echo "### API references drifted"
+            echo
+            echo "Pushed \`${{ steps.branch.outputs.name }}\`. Open a PR from it to"
+            echo "restore \`main\`; until it merges, \`fern-docs.yml\` skips the publish"
+            echo "and docs.nvidia.com will not update."
+          } >> "$GITHUB_STEP_SUMMARY"