From f2dbec0bda217d4eefa375a421a1122310fa4b01 Mon Sep 17 00:00:00 2001
From: Peter Feerick <5500713+pfeerick@users.noreply.github.com>
Date: Fri, 23 Oct 2026 19:03:26 +1000
Subject: [PATCH] ci: upload a Cloudflare preview for each docs PR

Builds the PR as the version its base branch publishes, on top of the
current gh-pages tree, and uploads it with `wrangler versions upload
--preview-alias pr-<n>`, so production is untouched. A bot comment on the
PR links the preview. Same-repo PRs only, since fork PRs don't get the
Cloudflare secrets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/preview-docs.yml | 114 +++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 .github/workflows/preview-docs.yml

diff --git a/.github/workflows/preview-docs.yml b/.github/workflows/preview-docs.yml
new file mode 100644
index 000000000..3f814367a
--- /dev/null
+++ b/.github/workflows/preview-docs.yml
@@ -0,0 +1,114 @@
+# Builds a preview of the docs for each pull request and uploads it to
+# Cloudflare as a Worker *version* with a preview alias. Production keeps
+# serving the deployed version; the preview is only reachable at
+#   https://pr-<number>-edgetx-lua-reference-guide.edgetx.workers.dev/
+#
+# The PR is built as the version its base branch publishes (main -> "dev",
+# edgetx_2.12 -> "2.12"/"latest") on top of the current gh-pages tree, so
+# the preview is the whole site with that one version replaced. Nothing is
+# pushed to gh-pages.
+#
+# Only runs for PRs from branches in this repo: fork PRs don't get the
+# Cloudflare secrets, and building untrusted code with them available
+# would be unsafe anyway.
+name: Preview Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+      - edgetx_2.12
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: preview-docs-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve version metadata
+        id: version
+        shell: bash
+        run: |
+          case "${GITHUB_BASE_REF}" in
+            main)
+              aliases="dev"
+              title="Dev"
+              ;;
+            edgetx_2.12)
+              aliases="2.12 latest"
+              title="2.12"
+              ;;
+            *)
+              echo "Unsupported base branch: ${GITHUB_BASE_REF}" >&2
+              exit 1
+              ;;
+          esac
+
+          version_id="${aliases%% *}"
+          {
+            echo "version_id=${version_id}"
+            echo "title=${title}"
+            echo "aliases=${aliases}"
+            echo "alias=pr-${{ github.event.pull_request.number }}"
+          } >> "${GITHUB_OUTPUT}"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Sync docs dependencies
+        run: uv sync
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Build preview into local gh-pages
+        env:
+          DOCS_EDIT_URI: edit/${{ github.head_ref }}/website/md-docs/
+        run: |
+          git branch -f gh-pages origin/gh-pages
+          uv run mike deploy --update-aliases --title "${{ steps.version.outputs.title }}" ${{ steps.version.outputs.aliases }}
+
+      - name: Export gh-pages tree for Cloudflare
+        run: |
+          rm -rf .site-publish
+          mkdir .site-publish
+          git archive gh-pages | tar -x -C .site-publish
+
+      - name: Upload preview version to Cloudflare Workers
+        uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: versions upload --preview-alias ${{ steps.version.outputs.alias }} --message "PR #${{ github.event.pull_request.number }} @ ${{ github.event.pull_request.head.sha }}"
+
+      - name: Comment preview link on the PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          url="https://${{ steps.version.outputs.alias }}-edgetx-lua-reference-guide.edgetx.workers.dev/${{ steps.version.outputs.version_id }}/"
+          body="📖 **Docs preview:** ${url}
+
+          Built from ${HEAD_SHA::7} as the \`${{ steps.version.outputs.version_id }}\` version, on top of the currently published site."
+          gh pr comment "${PR_NUMBER}" --edit-last --create-if-none --body "${body}"