From 6237b71a54586211966d449da06d6cc9b868309d Mon Sep 17 00:00:00 2001
From: Jonah Beckford <9566106-jonahbeckford@users.noreply.gitlab.com>
Date: Wed, 5 Aug 2026 05:23:26 -0700
Subject: [PATCH] Publish GitHub Pages via a gh-pages branch push

The actions/*-pages actions pull in transitively SHA-pinned actions
(upload-pages-artifact -> upload-artifact@<sha>) that each need
allowlisting under this repository's curated Actions allowlist. Publish
the odoc docs with a plain `git push` to the gh-pages branch instead,
which needs only the already-allowlisted actions/checkout and
ocaml/setup-ocaml.

Requires the repository's Pages source to be set to the gh-pages branch.

Signed-off-by: Jonah Beckford <9566106-jonahbeckford@users.noreply.gitlab.com>
---
 .github/workflows/pages.yml | 52 +++++++++++++++++++++----------------
 1 file changed, 29 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 6f09c7d..011b5d8 100644
--- a/.github/workflows/pages.yml
+++ b/.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 }}