From d64e109dd278a00f9c5b2a6da3ffc0bdcfa43caf Mon Sep 17 00:00:00 2001
From: Michal Harakal <michal.harakal@googlemail.com>
Date: Tue, 21 Jul 2026 09:25:36 +0200
Subject: [PATCH] ci(docs): publish on release and stop fork PRs failing on
 comment

Two documentation-workflow fixes:

docs.yml: deploy the Antora site to GitHub Pages on `release: published`
instead of on every push to develop, so the live site tracks the last
released version. `build-docs` still runs on PRs/pushes for validation.
The release event is immune to the `paths:` filter and checks out the
released commit, where generateDocs/dokkaGenerate run live, so no
generated pages need to be committed.

documentation.yml: the "Create PR comment with preview link" step failed
on fork PRs because such PRs get a read-only GITHUB_TOKEN regardless of
the workflow's permissions block. Guard the step to same-repo PRs and
mark it continue-on-error so a missing comment never fails the run.
---
 .github/workflows/docs.yml          | 20 ++++++++++++++++----
 .github/workflows/documentation.yml |  5 +++++
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ff548bfe..e0089f21 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,9 +1,10 @@
 name: Docs
 
 # Build the Antora site (with generated operator pages and the
-# cross-backend coverage matrix) on every PR, and publish to GitHub
-# Pages on pushes to develop. Dokka API bundling is wired in
-# commit 6 of the docs-to-Antora migration (see issue #494).
+# cross-backend coverage matrix) on every PR and push, and publish to
+# GitHub Pages when a release is published, so the live site tracks the
+# last released version. Dokka API bundling is wired in commit 6 of the
+# docs-to-Antora migration (see issue #494).
 
 on:
   push:
@@ -21,6 +22,14 @@ on:
       - 'build.gradle.kts'
       - 'build-logic/**'
       - 'skainet-lang/skainet-lang-core/**'
+  # Publish on release: the live site tracks the last released version.
+  # `release: published` is immune to the `paths:` filter above (so every
+  # release rebuilds docs) and checks out the released commit, where
+  # `generateDocs`/`dokkaGenerate` run live against the working tree — no
+  # need to commit generated pages. Single-version for now; a dedicated
+  # multi-repo aggregation site can come later (see issue #494).
+  release:
+    types: [ published ]
   workflow_dispatch:
 
 concurrency:
@@ -117,7 +126,10 @@ jobs:
           path: docs/build/site
 
   deploy-docs:
-    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
+    # Canonical site = latest release. Deploy only on a published release;
+    # develop/main pushes still run build-docs above for validation but no
+    # longer publish to Pages.
+    if: github.event_name == 'release'
     needs: build-docs
     runs-on: ubuntu-latest
     environment:
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index ed6ddc86..6cfe8bf7 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -102,6 +102,11 @@ jobs:
           echo "Preview server started at http://localhost:3000"
           
       - name: Create PR comment with preview link
+        # Fork PRs get a read-only GITHUB_TOKEN, so commenting is impossible
+        # regardless of the workflow's `permissions:` block. Only attempt on
+        # same-repo PRs, and never let a failed comment fail the whole run.
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        continue-on-error: true
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |