Add workflow to refresh jsonschema_for_docs.json after each release

.github/workflows/update-schema-docs.yml

@@ -0,0 +1,121 @@
+name: update-schema-docs
+
+# Regenerate bundle/schema/jsonschema_for_docs.json after every release and
+# publish it to the `docgen` branch.
+#
+# bundle/internal/schema/since_version.go derives `x-since-version` annotations
+# from the list of `v*` git tags that exist when the schema is generated. The
+# `docgen` branch is therefore stale by one release as soon as the next tag is
+# pushed; this workflow keeps it current.
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  # Required by setup-jfrog (GOPROXY exchange).
+  id-token: write
+
+jobs:
+  update-schema-docs:
+    runs-on:
+      group: databricks-protected-runner-group-large
+      labels: linux-ubuntu-latest-large
+
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # Regen runs against `main`. fetch-depth: 0 + fetch-tags: true ensure
+          # since_version.go can resolve `git show <tag>:bundle/schema/jsonschema.json`
+          # for every historical release.
+          ref: main
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Setup JFrog
+        uses: ./.github/actions/setup-jfrog
+
+      - name: Setup Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version-file: go.mod
+          cache-dependency-path: |
+            go.sum
+            bundle/internal/schema/*.*
+
+      - name: Determine release tag
+        id: tag
+        env:
+          REF_TYPE: ${{ github.ref_type }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          if [ "$REF_TYPE" = "tag" ]; then
+            tag="$REF_NAME"
+          else
+            # git tag --list uses fnmatch (no `+`), so post-filter with grep
+            # to match the same shape as the trigger above.
+            tag=$(git tag --list 'v*' --sort=-version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' | head -n 1)
+          fi
+          if [ -z "$tag" ]; then
+            echo "Could not determine a release tag to publish for." >&2
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "Publishing for tag $tag"
+
+      - name: Regenerate jsonschema_for_docs.json
+        run: go tool -modfile=tools/task/go.mod task --force generate-schema-docs
+
+      # Fail loudly if regeneration touches anything other than the docs schema.
+      # Anything else (annotations.yml, untracked files, ...) is a bug in the
+      # generator, not something we want to silently publish.
+      - name: Assert only jsonschema_for_docs.json changed on main
+        run: |
+          changed=$(git status --porcelain)
+          expected=" M bundle/schema/jsonschema_for_docs.json"
+          if [ -z "$changed" ]; then
+            echo "Regeneration produced no diff against main."
+            exit 0
+          fi
+          if [ "$changed" != "$expected" ]; then
+            echo "Expected only bundle/schema/jsonschema_for_docs.json to be modified."
+            echo "Actual git status --porcelain:"
+            echo "$changed"
+            exit 1
+          fi
+
+      - name: Capture regenerated file
+        run: |
+          mkdir -p "$RUNNER_TEMP/regen"
+          cp bundle/schema/jsonschema_for_docs.json "$RUNNER_TEMP/regen/jsonschema_for_docs.json"
+
+      - name: Check out docgen worktree
+        run: |
+          git fetch origin docgen
+          git worktree add "$RUNNER_TEMP/docgen" origin/docgen
+
+      - name: Stage regenerated file on docgen
+        working-directory: ${{ runner.temp }}/docgen
+        run: |
+          mkdir -p bundle/schema
+          cp "$RUNNER_TEMP/regen/jsonschema_for_docs.json" bundle/schema/jsonschema_for_docs.json
+          git add bundle/schema/jsonschema_for_docs.json
+
+      - name: Commit and push to docgen
+        working-directory: ${{ runner.temp }}/docgen
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+        run: |-
+          if git diff --cached --quiet; then
+            echo "docgen already up to date for ${TAG}; nothing 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 commit -m "Update jsonschema_for_docs.json for ${TAG}"
+          git push origin HEAD:docgen