From b1e516d38e3a1a8052909f46a60db8f38b292fbc Mon Sep 17 00:00:00 2001
From: Robin Gutzen <robin.gutzen@outlook.com>
Date: Thu, 2 Jul 2026 18:58:17 +0200
Subject: [PATCH 1/2] ci: switch docs deploy from branch-push to native Pages
 artifact

The peaceiris/actions-gh-pages branch-push approach was correctly pushing
MkDocs output to gh-pages, but the repo has a deployed actions/deploy-pages@v5
workflow running as well. This created a 'deployment_queued' loop in the
workflow-based model that never resolved.

Switch to the native GitHub Pages artifact model:
- actions/configure-pages@v5 sets up the Pages environment
- actions/upload-pages-artifact@v3 uploads the MkDocs site/ output
- actions/deploy-pages@v4 deploys the artifact

Also switched the Pages source from 'gh-pages/ legacy' to 'workflow' mode
via the Pages API.
---
 .github/workflows/docs.yml | 43 +++++++++++++++++---------------------
 1 file changed, 19 insertions(+), 24 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 99e60ca..ba44f8e 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -17,16 +17,22 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
 
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Fetch all history for git-revision-date-localized plugin
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -42,33 +48,22 @@ jobs:
       - name: Install Python dependencies
         run: |
           pip install --upgrade pip
-          # Install CPU-only PyTorch first to avoid ~2.5 GB CUDA download
           pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
           pip install -e ".[doc]"
 
       - name: Build documentation
-        # Note: not using --strict. The repo intentionally contains work-in-
-        # progress planning docs; link/nav resilience is handled by the
-        # `validation:` block in docs/mkdocs.yml. A real config/template error
-        # still fails the build.
         run: |
           python -m mkdocs build --config-file docs/mkdocs.yml
 
-      - name: Deploy to GitHub Pages
-        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          publish_branch: gh-pages
-          user_name: 'github-actions[bot]'
-          user_email: 'github-actions[bot]@users.noreply.github.com'
-          commit_message: 'docs: deploy documentation from ${{ github.sha }}'
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
 
-      - name: Upload build artifacts
-        if: github.event_name == 'pull_request'
-        uses: actions/upload-artifact@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          name: documentation
-          path: site/
-          retention-days: 7
+          path: ./site
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name != 'pull_request'
+        id: deployment
+        uses: actions/deploy-pages@v4

From 755f9192c9366f96905b81368ad29cda99a993e9 Mon Sep 17 00:00:00 2001
From: Robin Gutzen <robin.gutzen@outlook.com>
Date: Thu, 2 Jul 2026 19:15:09 +0200
Subject: [PATCH 2/2] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 .github/workflows/docs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index ba44f8e..212119d 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -22,7 +22,7 @@ permissions:
   id-token: write
 
 concurrency:
-  group: pages
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: false
 
 jobs: