From 59ceded4313f51ecbc747fe52d61d66d54d712d8 Mon Sep 17 00:00:00 2001
From: DigiLive <github@digilive.nl>
Date: Mon, 23 Mar 2026 15:57:56 +0100
Subject: [PATCH] Refactor deployment workflow for documentation

Improve the GitHub Actions workflow for deploying documentation by
adding concurrency control, adjusting permissions, and enhancing
error handling for branch fetching. This ensures a more robust
and efficient deployment process.
---
 .github/workflows/deploy-docs.yml | 46 +++++++++++++++++--------------
 maintainer-notes.md               |  2 +-
 requirements.txt                  |  4 +++
 3 files changed, 31 insertions(+), 21 deletions(-)
 create mode 100644 requirements.txt

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index a2942722..ae1addf5 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -20,13 +20,17 @@
 
 name: Deploy Documentation
 
+concurrency:
+  group: deploy-docs-${{ github.ref }}
+  cancel-in-progress: false
+
 on:
   release:
     types: [published]
   push:
     branches:
       - main
-  # checkov:skip=CKV_GHA_7: Inputs are sanitized via regex in the run block to prevent injection
+  # checkov:skip=CKV_GHA_7: Inputs are sanitized via regex in the run block to prevent injection.
   workflow_dispatch:
     inputs:
       version:
@@ -39,7 +43,7 @@ on:
         default: ''
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
   check-for-changes:
@@ -63,6 +67,8 @@ jobs:
 
   deploy:
     name: Deploy MkDocs Site
+    permissions:
+      contents: write
     runs-on: ubuntu-latest
     timeout-minutes: 10
     needs: check-for-changes
@@ -93,9 +99,10 @@ jobs:
         uses: actions/setup-python@v6
         with:
           python-version: '3.x'
+          cache: 'pip'
 
       - name: Install MkDocs and dependencies
-        run: pip install mkdocs mkdocs-material pymdown-extensions mike
+        run: pip install -r requirements.txt
 
       - name: Deploy Docs to GitHub Pages
         env:
@@ -103,35 +110,34 @@ jobs:
           MY_ALIAS: ${{ github.event.inputs.alias }}
           RELEASE_TAG: ${{ github.event.release.tag_name }}
         run: |
-          # Validate Version
-          if [[ ! "$MY_VERSION" =~ ^[a-zA-Z0-9._-]+$ ]]; then
-            echo "::error::Invalid version name: $MY_VERSION. Only alphanumeric, dots, and hyphens allowed."
-            exit 1
-          fi
-
-          # Validate Alias
-          if [[ -n "$MY_ALIAS" && ! "$MY_ALIAS" =~ ^[a-zA-Z0-9._-]+$ ]]; then
-            echo "::error::Invalid alias name: $MY_ALIAS. Only alphanumeric, dots, and hyphens allowed."
-            exit 1
-          fi
-
           git config --global user.name "${{ env.CI_COMMIT_AUTHOR }}"
           git config --global user.email "${{ env.CI_COMMIT_EMAIL }}"
           git remote set-url origin https://x-access-token:${{ steps.generate_token.outputs.token }}@github.com/DigiLive/mushroom-strategy.git
 
-          git fetch origin gh-pages --depth=1
+          if ! git fetch origin gh-pages --depth=1 2>/dev/null; then
+          echo "::notice::gh-pages branch does not exist yet. Mike will create it."
+          fi
 
           if [ "${{ github.event_name }}" == "release" ]; then
             # Release: Create a permanent version folder and update latest alias.
-            mike deploy --push --update-aliases "$RELEASE_TAG" latest
+            mike deploy --push --rebase --update-aliases "$RELEASE_TAG" latest
           elif [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
             # Manual: Use UI inputs for version and optional alias.
+            if [[ ! "$MY_VERSION" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+              echo "::error::Invalid version name: $MY_VERSION. Only alphanumeric, dots, and hyphens allowed."
+              exit 1
+            fi
+            if [[ -n "$MY_ALIAS" && ! "$MY_ALIAS" =~ ^[a-zA-Z0-9._-]+$ ]]; then
+              echo "::error::Invalid alias name: $MY_ALIAS. Only alphanumeric, dots, and hyphens allowed."
+              exit 1
+            fi
+
             if [ -n "$MY_ALIAS" ]; then
-              mike deploy --push --update-aliases "$MY_VERSION" "$MY_ALIAS"
+              mike deploy --push --rebase --update-aliases "$MY_VERSION" "$MY_ALIAS"
             else
-              mike deploy --push "$MY_VERSION"
+              mike deploy --push --rebase "$MY_VERSION"
             fi
           else
             # Push: Update the /main/ folder
-            mike deploy --push main
+            mike deploy --push --rebase main
           fi
diff --git a/maintainer-notes.md b/maintainer-notes.md
index 2cc51def..522c3517 100644
--- a/maintainer-notes.md
+++ b/maintainer-notes.md
@@ -10,7 +10,7 @@ Ensure you have Python 3 installed. It is recommended to use a virtual environme
 
 ```bash
 # Install core documentation stack
-pip install mkdocs mkdocs-material mike pymdown-extensions
+pip install -r requirements.txt
 ```
 
 ## 2. One-Time Project Initialization
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 00000000..2e6b568f
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,4 @@
+mkdocs>=1.5.0
+mkdocs-material>=9.0.0
+pymdown-extensions>=10.0.0
+mike>=2.0.0