From 78a03f2827755a07e5320b732d85ebcd3572d29c Mon Sep 17 00:00:00 2001
From: Julian Pawlowski <75446+jpawlowski@users.noreply.github.com>
Date: Sat, 6 Dec 2025 01:50:49 +0000
Subject: [PATCH] feat(workflows): enhance GitHub Actions workflows with
 concurrency control and deployment updates

---
 .github/workflows/docusaurus.yml | 33 +++++++++++++++++++++++++-------
 .github/workflows/lint.yml       |  6 ++++++
 .github/workflows/validate.yml   |  6 ++++++
 3 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/docusaurus.yml b/.github/workflows/docusaurus.yml
index ab1d6ee..d303415 100644
--- a/.github/workflows/docusaurus.yml
+++ b/.github/workflows/docusaurus.yml
@@ -10,13 +10,24 @@ on:
       - 'v*.*.*'
   workflow_dispatch:
 
+# Concurrency control: cancel in-progress deployments
+# Pattern from GitHub Actions best practices for deployment workflows
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 permissions:
   contents: write
+  pages: write
+  id-token: write
 
 jobs:
   deploy:
     name: Build and Deploy Documentation Sites
     runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -25,6 +36,10 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 24
+          cache: 'npm'
+          cache-dependency-path: |
+            docs/user/package-lock.json
+            docs/developer/package-lock.json
 
       # USER DOCS BUILD
       - name: Install user docs dependencies
@@ -123,11 +138,15 @@ jobs:
             echo "Version snapshots committed and pushed to main"
           fi
 
-      # DEPLOY
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
+      # DEPLOY TO GITHUB PAGES
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./deploy-root
-          user_name: github-actions[bot]
-          user_email: github-actions[bot]@users.noreply.github.com
+          path: ./deploy-root
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 8797c39..63aa105 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -4,9 +4,15 @@ on:
   push:
     branches:
       - "main"
+    paths-ignore:
+      - 'docs/**'
+      - '.github/workflows/docusaurus.yml'
   pull_request:
     branches:
       - "main"
+    paths-ignore:
+      - 'docs/**'
+      - '.github/workflows/docusaurus.yml'
 
 permissions: {}
 
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index a84aa66..ff6661f 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -7,9 +7,15 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - 'docs/**'
+      - '.github/workflows/docusaurus.yml'
   pull_request:
     branches:
       - main
+    paths-ignore:
+      - 'docs/**'
+      - '.github/workflows/docusaurus.yml'
 
 permissions: {}