diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 9a2aba3..540bb4d 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -66,32 +66,37 @@ jobs:
       - name: Build book
         run: mdbook build docs
 
-      - name: Prepare deployment
+      - name: Deploy to gh-pages
+        env:
+          APP_TOKEN: ${{ steps.app-token.outputs.token }}
         run: |
+          # Configure git to authenticate as the GitHub App via extraheader
+          REPO_URL="https://github.com/${{ github.repository }}"
+          ENCODED_TOKEN=$(printf '%s' "x-access-token:${APP_TOKEN}" | base64)
+          git config --global http.${REPO_URL}.extraheader "Authorization: basic ${ENCODED_TOKEN}"
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
           git fetch origin gh-pages
-          git worktree add /tmp/gh-pages origin/gh-pages
+          git worktree add /tmp/gh-pages gh-pages
 
-          # Start from existing gh-pages content, then overlay new docs
-          cp -r /tmp/gh-pages /tmp/deploy
-          rm -rf /tmp/deploy/.git
-          mkdir -p /tmp/deploy/${{ steps.target.outputs.destination }}
-          cp -r ./docs/book/* /tmp/deploy/${{ steps.target.outputs.destination }}/
+          # Copy new docs into the version subdirectory
+          mkdir -p /tmp/gh-pages/${{ steps.target.outputs.destination }}
+          cp -r ./docs/book/* /tmp/gh-pages/${{ steps.target.outputs.destination }}/
 
-          # Generate from assembled state so new versions are included
+          # Regenerate versions.json and root redirect
           chmod +x .github/scripts/generate-versions-json.sh
-          .github/scripts/generate-versions-json.sh /tmp/deploy /tmp/deploy/versions.json
+          .github/scripts/generate-versions-json.sh /tmp/gh-pages /tmp/gh-pages/versions.json
 
-          LATEST=$(python3 -c "import json; print(json.load(open('/tmp/deploy/versions.json'))['latest'])")
+          LATEST=$(python3 -c "import json; print(json.load(open('/tmp/gh-pages/versions.json'))['latest'])")
 
           chmod +x .github/scripts/generate-redirect.sh
-          .github/scripts/generate-redirect.sh "$LATEST" /tmp/deploy/index.html
+          .github/scripts/generate-redirect.sh "$LATEST" /tmp/gh-pages/index.html
 
-          git worktree remove /tmp/gh-pages
+          cd /tmp/gh-pages
+          git add -A
+          git commit -m "Deploy docs (${{ inputs.version }})" || echo "No changes to commit"
+          git push origin gh-pages
 
-      - name: Deploy to gh-pages
-        uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-          folder: /tmp/deploy
-          clean: false
-          force: false
+          cd -
+          git worktree remove /tmp/gh-pages