From b025a070a0e6c3d7dc97bf41d865e821ec22643d Mon Sep 17 00:00:00 2001
From: Lukas Wagner <appdev.lukaswagner@gmail.com>
Date: Mon, 11 May 2026 21:10:58 +0200
Subject: [PATCH 1/2] Use single deploy step to avoid gh-pages push conflict

Assemble all content (versioned docs + versions.json + root redirect)
into one directory and deploy in a single action call, avoiding the
double-invocation issue that caused the second push to be rejected.
---
 .github/workflows/deploy-docs.yml | 28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index ce049e1..9a859c7 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -66,33 +66,31 @@ jobs:
       - name: Build book
         run: mdbook build docs
 
-      - name: Deploy versioned docs
-        uses: JamesIves/github-pages-deploy-action@v4
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-          folder: ./docs/book
-          target-folder: ${{ steps.target.outputs.destination }}
-          clean: false
-
-      - name: Generate versions.json and root redirect
+      - name: Prepare deployment
         run: |
           git fetch origin gh-pages
           git worktree add /tmp/gh-pages origin/gh-pages
-          mkdir -p /tmp/meta
 
+          # 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 }}/
+
+          # Generate from assembled state so new versions are included
           chmod +x .github/scripts/generate-versions-json.sh
-          .github/scripts/generate-versions-json.sh /tmp/gh-pages /tmp/meta/versions.json
+          .github/scripts/generate-versions-json.sh /tmp/deploy /tmp/deploy/versions.json
 
-          LATEST=$(python3 -c "import json; print(json.load(open('/tmp/meta/versions.json'))['latest'])")
+          LATEST=$(python3 -c "import json; print(json.load(open('/tmp/deploy/versions.json'))['latest'])")
 
           chmod +x .github/scripts/generate-redirect.sh
-          .github/scripts/generate-redirect.sh "$LATEST" /tmp/meta/index.html
+          .github/scripts/generate-redirect.sh "$LATEST" /tmp/deploy/index.html
 
           git worktree remove /tmp/gh-pages
 
-      - name: Deploy versions.json and root redirect
+      - name: Deploy to gh-pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           token: ${{ steps.app-token.outputs.token }}
-          folder: /tmp/meta
+          folder: /tmp/deploy
           clean: false

From b5d07013ca2cb48dccec551034b2971bcc602b96 Mon Sep 17 00:00:00 2001
From: Lukas Wagner <appdev.lukaswagner@gmail.com>
Date: Mon, 11 May 2026 21:40:28 +0200
Subject: [PATCH 2/2] Disable force-push for gh-pages deployment

JamesIves/github-pages-deploy-action defaults to git push --force which
triggers the non_fast_forward ruleset rule. With force: false it does a
regular push, matching how peaceiris handled it successfully.
---
 .github/workflows/deploy-docs.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 9a859c7..9a2aba3 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -94,3 +94,4 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
           folder: /tmp/deploy
           clean: false
+          force: false