add new manual CLI based job to build, configure and deploy pages

Uses the GH API and some more explicit interaction without relying on the magic
actions/upload-pages-artifact and actions/deploy-pages actions. Does require
v4 of the actions/upload-artifact action, though. Which is at this time not
compatible with GHES (in any version).

.github/workflows/pages-gh-cli.yml

@@ -0,0 +1,125 @@
+name: Deploy Pages via GH CLI
+
+on:
+  #  push:
+  #    branches:
+  #      - main
+
+  workflow_dispatch:
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages-gh-cli-deploy"
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read    # to read the repository itself
+    outputs: # make artifact-id available in deploy job
+      artifact-id: ${{ steps.artifact-upload.outputs.artifact-id }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Set up NodeJs
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.node-version'
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+      - name: Install Dependencies
+        run: npm ci
+      - name: Generate Site
+        run: npx antora antora-playbook.yml
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        id: artifact-upload
+        with:
+          name: page-artifact
+          path: build/site
+          if-no-files-found: error
+
+  configure:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read    # to read the repository itself
+      pages: write      # to configure to Pages
+    needs: build
+    steps:
+      - name: Check Page Exists
+        id: exists
+        run: |
+          if gh api --silent \
+            --header "Accept: application/vnd.github+json" \
+            --header "X-GitHub-Api-Version: 2022-11-28" \
+            "/repos/${GH_REPOSITORY}/pages" ; then
+            echo "page_configured=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "page_configured=false" >> "$GITHUB_OUTPUT"
+          fi
+        env:
+          GH_REPOSITORY: ${{ github.repository }}
+          GH_TOKEN: ${{ github.token }}
+      - name: Setup Page
+        run: |
+          jq --null-input --raw-output \
+            '{ "build_type": "workflow" }' \
+            > request.json
+
+          method=POST
+          if [[ ${PAGE_CONFIGURED} = true ]]; then
+            method=PUT
+          fi
+
+          curl -L \
+            -X ${method} \
+            -H "Accept: application/vnd.github+json" \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/${GH_REPOSITORY}/pages \
+            -d '{ "build_type": "workflow" }'
+
+# Causes a Resource not accessible by integration (HTTP 403) error
+# Probably related to https://github.com/orgs/community/discussions/35595
+#          gh api \
+#            --method ${method} \
+#            --header "Accept: application/vnd.github+json" \
+#            --header "X-GitHub-Api-Version: 2022-11-28" \
+#            "/repos/${GH_REPOSITORY}/pages" \
+#            --input request.json
+        env:
+          PAGE_CONFIGURED: ${{ steps.exists.outputs.page_configured }}
+          GH_REPOSITORY: ${{ github.repository }}
+          GH_TOKEN: ${{ github.token }}
+
+  deploy:
+    runs-on: ubuntu-latest
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      actions: read     # to access the artifact of the previous workflow
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    needs: [build, configure]
+    steps:
+      - name: Deploy to GitHub Pages
+        run: |
+          gh api \
+          --method POST \
+          --header "Accept: application/vnd.github+json" \
+          --header "X-GitHub-Api-Version: 2022-11-28" \
+          "/repos/${GH_REPOSITORY}/pages/deployment" \
+          -f artifact_id="${GH_ARTIFACT_ID}" \
+          -f environment='github-pages' \
+          -f pages_build_version="${GH_SHA}" \
+          -f oidc_token="${GH_TOKEN}"
+        env:
+          GH_REPOSITORY: ${{ github.repository }}
+          GH_SHA: ${{ github.sha }}
+          GH_TOKEN: ${{ github.token }}
+          GH_ARTIFACT_ID: ${{ needs.jobs.build.outputs.artifact-id }}