From 9fe12039ff556658df968ea7eb06835454ba0833 Mon Sep 17 00:00:00 2001
From: Jay Ravani <jaykumar.ravani@th-deg.de>
Date: Thu, 8 Oct 2026 23:23:49 +0200
Subject: [PATCH] ci(docs): deploy the site through the shared mkdocs pages
 workflow

The repository's Pages source is "GitHub Actions", which ignores the
gh-pages branch that the deploy job pushed to with peaceiris. Docs
runs succeeded, but nothing they built reached the live site.

docs.yml now only calls the organisation's reusable workflow
THD-Spatial-AI/.github mkdocs-pages.yml@v1. It lints the OpenAPI spec
with Redocly, builds with mkdocs --strict and publishes through
actions/deploy-pages. It triggers on docs/** and mkdocs.yml, which
are the only inputs MkDocs reads, and can be run manually through
workflow_dispatch. The workflow needs contents: read only.

The arc42 PDF build moves unchanged into its own arc42.yml, triggered
on documentation/**. The PDF stays a run artifact and is not
published.

The strict build and the Redocly 2.51.2 lint both pass on the
current docs.
---
 .github/workflows/arc42.yml | 32 +++++++++++++++++++
 .github/workflows/docs.yml  | 63 ++++++-------------------------------
 2 files changed, 42 insertions(+), 53 deletions(-)
 create mode 100644 .github/workflows/arc42.yml

diff --git a/.github/workflows/arc42.yml b/.github/workflows/arc42.yml
new file mode 100644
index 0000000..cd4dd88
--- /dev/null
+++ b/.github/workflows/arc42.yml
@@ -0,0 +1,32 @@
+name: arc42
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - "documentation/**"
+permissions:
+  contents: read
+jobs:
+  # The PDF is uploaded as a run artifact only and stays off the site until
+  # the architecture documentation is ready to be public.
+  build-arc42:
+    runs-on: ubuntu-latest
+    container: texlive/texlive:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Pull LFS content (figures are stored via Git LFS)
+        run: |
+          apt-get update -qq && apt-get install -y -qq git-lfs
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          git lfs install
+          git lfs pull
+      - name: Build arc42 documentation
+        working-directory: documentation
+        run: make
+      - uses: actions/upload-artifact@v4
+        with:
+          name: arc42-pdf
+          path: documentation/documentation.pdf
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 683b4ad..72e894d 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -6,60 +6,17 @@ on:
       - master
       - main
     paths:
-      - "documentation/**"
       - "docs/**"
       - "mkdocs.yml"
+  workflow_dispatch:
 permissions:
-  contents: write
+  contents: read
 jobs:
-  build-arc42:
-    runs-on: ubuntu-latest
-    container: texlive/texlive:latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Pull LFS content (figures are stored via Git LFS)
-        run: |
-          apt-get update -qq && apt-get install -y -qq git-lfs
-          git config --global --add safe.directory "$GITHUB_WORKSPACE"
-          git lfs install
-          git lfs pull
-      - name: Build arc42 documentation
-        working-directory: documentation
-        run: make
-      - uses: actions/upload-artifact@v4
-        with:
-          name: arc42-pdf
-          path: documentation/documentation.pdf
-
-  deploy:
-    needs: build-arc42
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: ~/.cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install -r docs/requirements.txt
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - name: Lint OpenAPI specification
-        run: npx @redocly/cli lint docs/openapi/openapi.yaml --format=github-actions
-      - run: mkdocs build
-      # arc42 PDF is intentionally not copied into site/: the architecture
-      # documentation is still under development and not ready to be public.
-      - uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
+  docs:
+    uses: THD-Spatial-AI/.github/.github/workflows/mkdocs-pages.yml@v1
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      openapi-spec: docs/openapi/openapi.yaml