From 092fc3ae0d0674cbfcc1a2b0527a11817935729c Mon Sep 17 00:00:00 2001
From: Richard R <me@richardr.dev>
Date: Thu, 19 Feb 2026 12:53:01 -0700
Subject: [PATCH] feat: enhance workflow for versioning documentation with
 optional inputs and improved commit handling

---
 .github/workflows/docs-version-on-tag.yml | 57 +++++++++++++++--------
 1 file changed, 37 insertions(+), 20 deletions(-)

diff --git a/.github/workflows/docs-version-on-tag.yml b/.github/workflows/docs-version-on-tag.yml
index 1e3098d..e2ba8ad 100644
--- a/.github/workflows/docs-version-on-tag.yml
+++ b/.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
-        uses: peter-evans/create-pull-request@v6
-        with:
-          commit-message: "docs: snapshot ${{ github.ref_name }}"
-          title: "docs: snapshot ${{ github.ref_name }}"
-          body: |
-            Automated docs version snapshot for `${{ github.ref_name }}`.
+      - name: Commit docs snapshot
+        id: commit_snapshot
+        env:
+          VERSION: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.version || github.ref_name }}
+        run: |
+          set -euo pipefail
+          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`
-            - Added versioned docs/sidebar snapshot files
-          branch: docs/version-${{ github.ref_name }}
-          base: main
-          delete-branch: true
-          labels: docs,automation
-          add-paths: |
-            docs-site/versions.json
-            docs-site/versioned_docs/**
-            docs-site/versioned_sidebars/**
+      - name: Push docs snapshot to main
+        if: steps.commit_snapshot.outputs.committed == 'true'
+        run: |
+          set -euo pipefail
+          SNAPSHOT_COMMIT="$(git rev-parse HEAD)"
+          git fetch origin main
+          git checkout -B docs-version-publish origin/main
+          git cherry-pick "${SNAPSHOT_COMMIT}"
+          git push origin HEAD:main