ci: fix docs publishing by removing tag indirection

.github/workflows/docs.yml

@@ -8,8 +8,6 @@ on:
       - 'docs/**'
       - 'antora-playbook.yml'
   push:
-    tags:
-      - docs
     branches:
       - 'release-*'
 
@@ -23,9 +21,11 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  tag:
+  check:
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/heads/release-')
     runs-on: ubuntu-latest
+    outputs:
+      is-latest: ${{ steps.check.outputs.match }}
     steps:
       - name: Check if this is the latest release branch
         id: check
@@ -35,7 +35,7 @@ jobs:
             | sed 's|.*refs/heads/release-||' \
             | sort -t. -k1,1n -k2,2n \
             | tail -1)"
-       
+
           if [ "$CURRENT_BRANCH" = "$LATEST_BRANCH" ]; then
             echo "Branch $CURRENT_BRANCH is the latest release branch."
             echo "match=true" >> "$GITHUB_OUTPUT"
@@ -44,18 +44,27 @@ jobs:
             echo "match=false" >> "$GITHUB_OUTPUT"
           fi
 
+  validate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
       - name: Checkout
-        if: steps.check.outputs.match == 'true'
         uses: actions/checkout@v4
 
-      - name: Force-tag current commit as docs
-        if: steps.check.outputs.match == 'true'
-        run: |
-          git tag -f docs
-          git push origin docs --force
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Antora and extensions
+        run: npm i -g @antora/cli@3.1 @antora/site-generator@3.1 @antora/lunr-extension@1.0.0-alpha.13
+
+      - name: Build site
+        run: SITE_SEARCH_PROVIDER=lunr antora --fetch antora-playbook.yml
 
   build:
-    if: github.event_name == 'pull_request' || (github.event_name == 'push' && github.ref == 'refs/tags/docs')
+    if: needs.check.outputs.is-latest == 'true'
+    needs: check
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -73,17 +82,14 @@ jobs:
         run: SITE_SEARCH_PROVIDER=lunr antora --fetch antora-playbook.yml
 
       - name: Disable Jekyll
-        if: github.ref == 'refs/tags/docs'
         run: touch build/site/.nojekyll
 
       - name: Upload artifact
-        if: github.ref == 'refs/tags/docs'
         uses: actions/upload-pages-artifact@v3
         with:
           path: build/site
 
   deploy:
-    if: github.event_name == 'push' && github.ref == 'refs/tags/docs'
     needs: build
     runs-on: ubuntu-latest
     environment:

docs/README.md

@@ -11,8 +11,6 @@ This directory contains the [Antora](https://antora.org/)-based documentation fo
 | `main` | Development branch. All new doc work starts here. |
 | `release-X.Y` | Release branches (e.g., `release-0.1`). The **latest** release branch is the source for the published site. |
 
-The `docs` **tag** (not a branch) is managed automatically by CI. Do not create or move it manually.
-
 ## Contributing documentation changes
 
 ### Day-to-day workflow
@@ -53,34 +51,36 @@ When a new release branch is created (e.g., `release-0.2`):
 
 ## How publishing works
 
-Publishing is fully automated via GitHub Actions (`.github/workflows/docs.yml`). There are three jobs:
+Publishing is fully automated via GitHub Actions (`.github/workflows/docs.yml`). The workflow has four jobs:
 
-### 1. `tag` job (runs on push to any `release-*` branch)
+### 1. `check` job (runs on push to any `release-*` branch)
 
-- Queries all remote `release-*` branches.
+- Queries all remote `release-*` branches using `git ls-remote`.
 - Sorts them by semver to find the latest (e.g., `release-0.2` > `release-0.1`).
-- If the pushed branch **is** the latest: force-tags the commit as `docs` and pushes the tag.
-- If the pushed branch is **not** the latest: skips silently.
+- Outputs `is-latest=true` if the pushed branch is the latest, `false` otherwise.
+
+### 2. `validate` job (runs on PRs to `main`)
 
-### 2. `build` job (runs on `docs` tag push or PR to `main`)
+- Builds the site with Antora to verify the docs compile without errors.
+- Does **not** deploy. This is a build-only check.
 
-- Checks out the tagged commit.
+### 3. `build` job (runs after `check`, only if `is-latest` is `true`)
+
+- Checks out the release branch.
 - Installs Antora 3.1 and the Lunr search extension.
 - Runs `antora --fetch antora-playbook.yml` to build the site.
+- Creates a `.nojekyll` file (required for GitHub Pages to serve Antora assets).
 - Uploads the build output as a GitHub Pages artifact.
-- On PRs to `main`, it only validates the build (no artifact upload, no deploy).
 
-### 3. `deploy` job (runs on `docs` tag push, after `build` succeeds)
+### 4. `deploy` job (runs after `build` succeeds)
 
 - Deploys the artifact to GitHub Pages.
 
 ```
-PR to main ──> build (validate only, no deploy)
-
-Push to release-* ──> tag job ──> is this the latest? ──yes──> force-tag as `docs`
-                                                        ──no──> skip
+PR to main ──> validate (build-only check, no deploy)
 
-docs tag push ──> build ──> deploy to GitHub Pages
+Push to release-* ──> check ──> is this the latest? ──yes──> build ──> deploy
+                                                      ──no──> skip (all remaining jobs skipped)
 ```
 
 ## Local build