From 6e3cad1858655e45069a1914dec9eac7313d78dc Mon Sep 17 00:00:00 2001
From: Eric Allam <eallam@icloud.com>
Date: Tue, 16 Jun 2026 15:17:06 +0100
Subject: [PATCH 1/2] ci: add docs-release-* tag workflow to publish docs at
 release

Docs deploy from the docs-live branch via Mintlify, so a push to main no
longer publishes on its own. This workflow publishes at release: push a
docs-release-* tag at the commit you want live, and it runs the Mintlify
broken-links check against that commit, then fast-forwards docs-live to it.

The ref update uses force=false, so it is fast-forward only: a tag that is
not ahead of docs-live fails the job instead of rewinding production.
---
 .github/workflows/publish-docs.yml | 46 ++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 .github/workflows/publish-docs.yml

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
new file mode 100644
index 0000000000..efa4a26348
--- /dev/null
+++ b/.github/workflows/publish-docs.yml
@@ -0,0 +1,46 @@
+name: 📚 Publish docs
+
+on:
+  push:
+    tags:
+      - "docs-release-*"
+
+# Only needs to move the docs-live ref; Mintlify's GitHub app deploys from it.
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-docs
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout tagged commit
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: 📦 Cache npm
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.npm
+          key: |
+            ${{ runner.os }}-mintlify
+          restore-keys: |
+            ${{ runner.os }}-mintlify
+
+      - name: 🔗 Check for broken links
+        working-directory: ./docs
+        run: npx mintlify@4.0.393 broken-links
+
+      - name: 🚀 Fast-forward docs-live to the tagged commit
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh api -X PATCH \
+            "repos/${{ github.repository }}/git/refs/heads/docs-live" \
+            -f sha="${{ github.sha }}" \
+            -F force=false

From afee19806649cf8b31b577d84b94d24ad33d9c7f Mon Sep 17 00:00:00 2001
From: Eric Allam <eallam@icloud.com>
Date: Tue, 16 Jun 2026 15:22:02 +0100
Subject: [PATCH 2/2] ci: drop npm cache from the docs publish workflow

The publish job has contents: write and triggers a deploy, so restoring an
npm cache that a lower-privileged run could populate is a cache-poisoning
vector. The cache only saved re-downloading the mintlify CLI on a
tag-triggered workflow, so dropping it costs almost nothing.
---
 .github/workflows/publish-docs.yml | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index efa4a26348..09141772a8 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -22,16 +22,6 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: 📦 Cache npm
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: |
-            ~/.npm
-          key: |
-            ${{ runner.os }}-mintlify
-          restore-keys: |
-            ${{ runner.os }}-mintlify
-
       - name: 🔗 Check for broken links
         working-directory: ./docs
         run: npx mintlify@4.0.393 broken-links