ci: add docs-release-* tag workflow to publish docs at release (#3969)

ericallam · web-flow · commit 2936382e3e26 · 2026-06-16T15:33:49.000+01:00
## Summary

Docs deploy from the `docs-live` branch via Mintlify, so merging to
`main` no longer publishes docs on its own. To publish, push a
`docs-release-*` tag at the commit you want live. The workflow runs the
Mintlify broken-links check against that commit, then fast-forwards
`docs-live` to it, which is what Mintlify deploys from.

## Design

The ref move uses the GitHub API with `force=false`, making it
fast-forward only: a tag that is not ahead of `docs-live` fails the job
rather than rewinding production. Mintlify's GitHub app reacts to the
resulting push and deploys, so no extra deploy credentials are needed.

Usage:

```bash
git tag docs-release-2026.06.16   # tag the main commit you want live
git push origin docs-release-2026.06.16
```
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -0,0 +1,36 @@
+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: 🔗 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
