From 9df540e01c633d4638026e861d202cbf7fea405d Mon Sep 17 00:00:00 2001
From: Jakob Gamper <97gamjak@gmail.com>
Date: Sun, 13 Sep 2026 13:05:53 +0000
Subject: [PATCH] fix: explicitly dispatch docs deployment from create-tag.yml

GitHub blocks events triggered by GITHUB_TOKEN from starting other
workflows (anti-recursion protection), so the release tag pushed by
create-tag.yml never actually triggered docs.yml's tag-push trigger -
docs stopped deploying entirely after the previous fix. Dispatch the
Docs workflow explicitly via `gh workflow run docs.yml --ref <tag>`
instead, and allow workflow_dispatch to deploy regardless of ref so a
missed release can be redeployed manually.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0126spNDGtqDKMoYtuPT7JfW
---
 .github/workflows/create-tag.yml | 13 +++++++++++++
 .github/workflows/docs.yml       | 10 +++++++---
 CHANGELOG.md                     |  7 +++++++
 3 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/create-tag.yml b/.github/workflows/create-tag.yml
index 4f0a1c7..35f57dd 100644
--- a/.github/workflows/create-tag.yml
+++ b/.github/workflows/create-tag.yml
@@ -9,6 +9,7 @@ on:
 permissions:
   contents: write
   pull-requests: write
+  actions: write
 
 jobs:
   create-tag:
@@ -106,6 +107,18 @@ jobs:
           git tag "$version"
           git push origin "$version"
 
+      - name: Trigger docs deployment
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          version="${{ steps.extract_version.outputs.version }}"
+          # A tag pushed with GITHUB_TOKEN does not trigger other workflows
+          # (GitHub's anti-recursion protection), so the docs.yml "on.push.tags"
+          # trigger never fires for releases created here. Dispatch it
+          # explicitly instead, pinned to the release tag so the published
+          # docs resolve the clean release version via setuptools_scm.
+          gh workflow run docs.yml --ref "$version"
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 7f79bea..60433ec 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -65,9 +65,13 @@ jobs:
     # Only deploy from an actual release tag: setuptools_scm only produces a
     # clean version (e.g. "0.1.2") when building from the exact tagged
     # commit. Building from a branch push resolves to a dev version (e.g.
-    # "0.1.2.dev0+g...") because the release tag doesn't exist yet at
-    # merge time - it's created by a later step in create-tag.yml.
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    # "0.1.2.dev0+g...") because the release tag doesn't exist yet at merge
+    # time - it's created by a later step in create-tag.yml, which then
+    # dispatches this workflow with `--ref <tag>` (a tag *push* made with
+    # GITHUB_TOKEN wouldn't trigger this workflow at all - see create-tag.yml).
+    # workflow_dispatch is also allowed regardless of ref, so a missed/broken
+    # release can be redeployed manually without cutting a new version.
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch'
     needs: build
     runs-on: ubuntu-latest
     environment:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 73cc159..c0e7965 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## Next Release
 
+### Bug Fixes
+
+#### Documentation
+
+- Explicitly dispatch the `Docs` workflow from `create-tag.yml` instead of relying on the tag push to trigger it, since pushes made with `GITHUB_TOKEN` don't trigger other workflows (GitHub's anti-recursion protection) - the release tag push was silently never deploying the docs
+- Allow the `Docs` workflow to be redeployed manually via `workflow_dispatch` regardless of ref
+
 <!-- insertion marker -->
 ## [0.1.3](https://github.com/repo/owner/releases/tag/0.1.3) - 2026-09-13