feat: enhance workflow for versioning documentation with optional inputs and improved commit handling

.github/workflows/docs-version-on-tag.yml

@@ -4,10 +4,19 @@ on:
   push:
     tags:
       - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label to snapshot (e.g. v1.2.3)'
+        required: true
+        type: string
+      source_ref:
+        description: 'Optional git ref to build from (tag, branch, or SHA)'
+        required: false
+        type: string
 
 permissions:
   contents: write
-  pull-requests: write
 
 jobs:
   version-docs:
@@ -17,7 +26,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.sha }}
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.source_ref || github.sha }}
           fetch-depth: 0
 
       - name: Setup pnpm
@@ -37,7 +46,7 @@ jobs:
 
       - name: Snapshot docs version
         env:
-          VERSION: ${{ github.ref_name }}
+          VERSION: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.version || github.ref_name }}
         run: |
           set -euo pipefail
           if [ -f docs-site/versions.json ] && grep -q "\"${VERSION}\"" docs-site/versions.json; then
@@ -49,21 +58,29 @@ jobs:
       - name: Build docs
         run: pnpm --dir docs-site build
 
-      - name: Create docs version PR
+      - name: Commit docs snapshot
-        uses: peter-evans/create-pull-request@v6
+        id: commit_snapshot
-        with:
+        env:
-          commit-message: "docs: snapshot ${{ github.ref_name }}"
+          VERSION: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.version || github.ref_name }}
-          title: "docs: snapshot ${{ github.ref_name }}"
+        run: |
-          body: |
+          set -euo pipefail
-            Automated docs version snapshot for `${{ github.ref_name }}`.
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add docs-site/versions.json docs-site/versioned_docs docs-site/versioned_sidebars
+          if git diff --cached --quiet; then
+            echo "No docs snapshot changes to commit"
+            echo "committed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git commit -m "docs: snapshot ${VERSION}"
+          echo "committed=true" >> "$GITHUB_OUTPUT"
 
-            - Ran `docusaurus docs:version`
+      - name: Push docs snapshot to main
-            - Added versioned docs/sidebar snapshot files
+        if: steps.commit_snapshot.outputs.committed == 'true'
-          branch: docs/version-${{ github.ref_name }}
+        run: |
-          base: main
+          set -euo pipefail
-          delete-branch: true
+          SNAPSHOT_COMMIT="$(git rev-parse HEAD)"
-          labels: docs,automation
+          git fetch origin main
-          add-paths: |
+          git checkout -B docs-version-publish origin/main
-            docs-site/versions.json
+          git cherry-pick "${SNAPSHOT_COMMIT}"
-            docs-site/versioned_docs/**
+          git push origin HEAD:main
-            docs-site/versioned_sidebars/**