From cb602ea8e019bbb54b2548e663edd6956bd8f8a5 Mon Sep 17 00:00:00 2001
From: Dexter Ajoku <dex@dexcompiler.com>
Date: Sat, 16 May 2026 18:23:11 +0200
Subject: [PATCH] Dispatch docs deploy after releases

---
 .github/workflows/docs.yml    | 17 +++++++++----
 .github/workflows/release.yml | 45 +++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 4b4c327..4ebbc6b 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -8,6 +8,11 @@ on:
   release:
     types: [published]
   workflow_dispatch:
+    inputs:
+      version:
+        description: "Docs version label to deploy, such as v1.4.0. Leave empty for a non-deploying dev build."
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -39,24 +44,27 @@ jobs:
         working-directory: docs
         run: npm ci
 
-      - name: Resolve latest release version
+      - name: Resolve docs version
         id: resolve_version
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           # For deployment builds:
           # - On release events, use the event's tag name (source of truth for that deployment).
+          # - On workflow_dispatch with an explicit version, use that exact version.
           # - On main pushes, resolve the latest release tag from GitHub.
-          # For pull requests and workflow_dispatch, fall back to "dev" so preview builds still succeed.
+          # For pull requests and workflow_dispatch without a version, fall back to "dev" so preview builds still succeed.
           if [[ "${{ github.event_name }}" == "release" ]]; then
             VERSION="${{ github.event.release.tag_name }}"
+          elif [[ "${{ github.event_name }}" == "workflow_dispatch" && -n "${{ github.event.inputs.version }}" ]]; then
+            VERSION="${{ github.event.inputs.version }}"
           elif [[ "${{ github.event_name }}" == "push" ]]; then
             VERSION=$(gh release view --repo "${{ github.repository }}" --json tagName -q '.tagName' 2>/dev/null || true)
           else
             VERSION="dev"
           fi
 
-          if [[ "${{ github.event_name }}" == "push" || "${{ github.event_name }}" == "release" ]]; then
+          if [[ "$VERSION" != "dev" ]]; then
             if [[ -z "$VERSION" ]]; then
               echo "ERROR: Could not resolve docs version." >&2
               exit 1
@@ -85,7 +93,7 @@ jobs:
 
   deploy:
     needs: build
-    if: github.ref == 'refs/heads/main' || github.event_name == 'release'
+    if: github.event_name == 'push' || github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.version != '')
     runs-on: ubuntu-latest
     environment:
       name: github-pages
@@ -94,4 +102,3 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
-
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2cc2b2d..5fe27dd 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -12,6 +12,7 @@ on:
         type: string
 
 permissions:
+  actions: write
   contents: write
 
 concurrency:
@@ -110,3 +111,47 @@ jobs:
           files: |
             artifacts/packages/*.nupkg
             artifacts/packages/*.snupkg
+
+      - name: Deploy docs for released version
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          existing_runs="$(gh run list \
+            --workflow Docs \
+            --event workflow_dispatch \
+            --branch main \
+            --json databaseId \
+            --jq '.[].databaseId' \
+            --limit 10)"
+
+          gh workflow run docs.yml --ref main -f version="${{ steps.vars.outputs.tag }}"
+
+          docs_run_id=""
+          for _ in {1..12}; do
+            candidate_runs="$(gh run list \
+              --workflow Docs \
+              --event workflow_dispatch \
+              --branch main \
+              --json databaseId \
+              --jq '.[].databaseId' \
+              --limit 10)"
+
+            while IFS= read -r candidate_run_id; do
+              if [[ -n "$candidate_run_id" ]] && ! grep -qx "$candidate_run_id" <<< "$existing_runs"; then
+                docs_run_id="$candidate_run_id"
+                break
+              fi
+            done <<< "$candidate_runs"
+
+            [[ -n "$docs_run_id" ]] && break
+
+            sleep 5
+          done
+
+          if [[ -z "$docs_run_id" ]]; then
+            echo "Timed out waiting for dispatched docs workflow run."
+            exit 1
+          fi
+
+          gh run watch "$docs_run_id" --interval 10