diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index a3dfd06..e580c98 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -106,6 +106,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+      pages: write
     steps:
       - uses: actions/checkout@v7
         with:
@@ -150,6 +151,7 @@ jobs:
           "${{ needs.build.outputs.version }}" site gh-pages
 
       - name: Push gh-pages
+        id: push
         working-directory: gh-pages
         run: |
           git config user.name  "github-actions[bot]"
@@ -161,3 +163,22 @@ jobs:
           fi
           git commit -q -m "Deployed ${GITHUB_SHA::7} to ${{ needs.build.outputs.version }} with Hugo ${HUGO_VERSION}"
           git push origin HEAD:gh-pages
+          echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      # ⛔ A GREEN PUSH IS NOT A PUBLISHED SITE. GitHub's legacy "pages build and
+      # deployment" for the gh-pages branch sometimes stalls in updating_pages and
+      # fails with "Timeout reached, aborting!" after 10 minutes (3 times on
+      # 2026-11-05/06, runs 42058763350 and 42252993462); re-running it does not
+      # help and re-running this workflow pushes nothing. pagesbuild waits for a
+      # build of the pushed commit to be "built", requests a new one when it is
+      # not, and fails this job if the site is still not built.
+      - name: Wait for the Pages build
+        if: steps.push.outputs.sha != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          umask 077
+          printf '%s' "${GH_TOKEN}" > "${RUNNER_TEMP}/pages-token"
+          go run github.com/go-fleettools/fleettools/cmd/pagesbuild@v0.80.0 \
+            --token-file "${RUNNER_TEMP}/pages-token" \
+            "${GITHUB_REPOSITORY}" "${{ steps.push.outputs.sha }}"