Publish GitHub Pages via gh-pages branch (no Pages actions)

.github/workflows/pages.yml

@@ -1,27 +1,27 @@
 name: Publish GitHub Pages
 
-# https://github.com/ocaml/setup-ocaml/blob/master/EXAMPLES.md
+# Builds the odoc documentation and publishes it to the `gh-pages` branch
+# with a plain `git push`. This deliberately avoids the actions/*-pages
+# actions: under this repository's curated Actions allowlist, those pull in
+# transitively-pinned actions (e.g. upload-pages-artifact -> a SHA-pinned
+# upload-artifact) that would each need allowlisting. A git push needs only
+# actions/checkout and ocaml/setup-ocaml, both already allowlisted.
+#
+# GitHub Pages must be configured to deploy from the `gh-pages` branch
+# (Settings > Pages > Build and deployment > Deploy from a branch).
 
 on:
   push:
     branches:
       - 'main'
+  workflow_dispatch:
 
-permissions: read-all
+permissions:
+  contents: write
 
 jobs:
   deploy-odoc:
     name: Deploy odoc to GitHub Pages
-
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-
-    permissions:
-      contents: read
-      id-token: write
-      pages: write
-
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
@@ -38,14 +38,20 @@ jobs:
       - name: Build documentation
         run: opam exec -- dune build @doc
 
-      - name: Set-up Pages
-        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
-        with:
-          path: _build/default/_doc/_html
-
-      - name: Deploy odoc to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+      - name: Publish odoc to the gh-pages branch
+        run: |
+          set -eux
+          html=_build/default/_doc/_html
+          test -d "$html"
+          # .nojekyll keeps GitHub Pages from dropping odoc's _-prefixed dirs.
+          touch "$html/.nojekyll"
+          cd "$html"
+          git init -q
+          git checkout -q -b gh-pages
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -q -m "Deploy odoc for ${GITHUB_SHA}"
+          git push -f "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" gh-pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}