ci-cd: parallel tests, docs deployment preview and release

.github/actions/algokit-setup/action.yaml

@@ -8,7 +8,7 @@ runs:
       run: pipx install poetry
 
     - name: Set up Python 3.12
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: "3.12"
         cache: "poetry"

.github/actions/docs-ci/action.yaml

@@ -9,7 +9,8 @@ runs:
       with:
         globs: |
           README.md
-          docs/*.md
+          SECURITY.md
+          docs/**/*.md
 
     - name: Link Checker
       uses: lycheeverse/lychee-action@v2
@@ -19,7 +20,7 @@ runs:
     - name: Setup mdBook
       uses: peaceiris/actions-mdbook@v2
       with:
-        mdbook-version: '0.4.43'
+        mdbook-version: '0.4.52'
 
     - name: Test mdBook
       shell: bash

.github/workflows/check-deployments.yaml

@@ -7,6 +7,7 @@ on:
 
 jobs:
   check-deployments:
+    name: Check Deployments (release PRs only)
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/docs-cd.yaml

@@ -1,9 +1,9 @@
 name: Release xGov docs
 
 on:
-  push:
-    branches:
-      - main
+  workflow_run:
+    workflows: [ "Mainnet Stable Release xgov-beta-sc" ]
+    types: [ completed ]
 
 permissions:
   contents: read
@@ -16,12 +16,14 @@ concurrency:
 
 jobs:
   validate-docs:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     uses: ./.github/workflows/docs-ci.yaml
     secrets: inherit
 
   deploy-docs:
-    runs-on: "ubuntu-latest"
+    runs-on: ubuntu-latest
     needs: [ validate-docs ]
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
@@ -41,10 +43,9 @@ jobs:
       - name: Setup mdBook
         uses: peaceiris/actions-mdbook@v2
         with:
-          mdbook-version: '0.4.43'
+          mdbook-version: '0.4.52'
 
       - name: Install mdBook Mermaid plugin
-        shell: bash
         run: cargo install mdbook-mermaid && mdbook-mermaid install .
 
       - name: Build mdBook

.github/workflows/docs-ci.yaml

@@ -1,23 +1,66 @@
-name: Validate docs
+name: Validate & Preview docs
 
 on:
-  workflow_call:
   pull_request:
-    branches:
-      - main
+    branches: [ main ]
     types: [opened, reopened, synchronize, ready_for_review]
+  workflow_call:
 
 permissions:
   contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.event.pull_request.number && format('pages-pr-{0}', github.event.pull_request.number) || 'pages-release' }}
+  cancel-in-progress: true
 
 jobs:
   validate-docs:
-    runs-on: "ubuntu-latest"
-    if: github.head_ref != 'release' && (github.event.pull_request == null || !github.event.pull_request.draft)
+    name: Validate & Preview Docs (if changed)
+    runs-on: ubuntu-latest
+    if: ${{ (github.event.pull_request && !github.event.pull_request.draft) || github.event_name == 'workflow_call' }}
+    environment:
+      name: preview
+      url: ${{ steps.deploy.outputs.page_url }}
 
     steps:
       - name: Checkout source code
         uses: actions/checkout@v5
 
-      - name: Docs CI actions
+      - name: Detect docs changes
+        id: changes
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+              - 'README.md'
+              - 'SECURITY.md'
+
+      - name: No docs changes — mark check as passed
+        if: ${{ steps.changes.outputs.docs != 'true' }}
+        run: |
+          echo "No docs changes detected. Skipping validation and preview."
+          echo "This job still succeeds so required status is green."
+
+      - name: Docs CI actions (lint, links, mdBook build)
+        if: ${{ steps.changes.outputs.docs == 'true' || github.event_name == 'workflow_call' }}
         uses: ./.github/actions/docs-ci
+
+      - name: Configure Pages
+        if: ${{ steps.changes.outputs.docs == 'true' || github.event_name == 'workflow_call' }}
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        if: ${{ steps.changes.outputs.docs == 'true' || github.event_name == 'workflow_call' }}
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./book
+
+      - name: Deploy (PR Preview)
+        id: deploy
+        if: ${{ steps.changes.outputs.docs == 'true' || github.event_name == 'workflow_call' }}
+        uses: actions/deploy-pages@v4
+        with:
+          preview: true

.github/workflows/xgov-beta-sc-ci.yml

@@ -3,16 +3,16 @@ name: Validate xgov-beta-sc
 on:
   workflow_call:
   pull_request:
-    branches:
-      - main
+    branches: [ main ]
     types: [opened, reopened, synchronize, ready_for_review]
   schedule:
     # * is a special character in YAML so you have to quote this string
     - cron: "0 0 1 * *" # Run once a month at midnight on the 1st of the month
 
 jobs:
-  validate-xgov-beta-sc:
-    runs-on: "ubuntu-latest"
+  precheck:
+    name: Lint / Build / TEAL diff
+    runs-on: ubuntu-latest
     if: github.head_ref != 'release' && (github.event.pull_request == null || !github.event.pull_request.draft)
 
     steps:
@@ -22,30 +22,75 @@ jobs:
       - name: Set up AlgoKit
         uses: ./.github/actions/algokit-setup
 
-      - name: Start LocalNet
-        run: algokit localnet start
-
       - name: Audit python dependencies
         run: algokit project run audit
 
-      - name: Lint and format python dependencies
+      - name: Lint and format python
         run: algokit project run lint
 
-      - name: Run tests
-        shell: bash
-        run: |
-          set -o pipefail
-          algokit project run test
-
       - name: Build smart contracts
         run: algokit project run build
 
-      - name: Check output stability of the smart contracts
+      - name: Check output stability (TEAL diff)
         run: algokit project run ci-teal-diff
 
-      - if: ${{ github.actor != 'dependabot[bot]' }}
-        name: Run deployer against LocalNet
-        run: algokit project deploy localnet xgov_registry
-        env:
-          # Deploy command to run
-          XGOV_REG_DEPLOY_COMMAND: deploy
+  tests:
+    name: "SC tests (${{ matrix.component }})"
+    runs-on: ubuntu-latest
+    needs: precheck
+    if: github.head_ref != 'release' && (github.event.pull_request == null || !github.event.pull_request.draft)
+    strategy:
+      fail-fast: false
+      matrix:
+        # Smart Contracts folders and tests folders must have the same name
+        component: [xgov_registry, proposal, council]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up AlgoKit
+        uses: ./.github/actions/algokit-setup
+
+      - name: Start LocalNet
+        run: algokit localnet start
+
+      - name: Build smart contracts (per shard)
+        run: |
+          set -o pipefail
+          case "${{ matrix.component }}" in
+            xgov_registry)
+              algokit project run build xgov_registry
+              ;;
+            proposal)
+              algokit project run build proposal
+              ;;
+            council)
+              algokit project run build council
+              ;;
+            *)
+              echo "Unknown component: ${{ matrix.component }}"
+              exit 1
+              ;;
+          esac
+
+      - name: Run tests scoped by directory
+        # Common utils are tested with Council
+        run: |
+          set -o pipefail
+          case "${{ matrix.component }}" in
+            xgov_registry)
+              poetry run pytest -q tests/xgov_registry
+              ;;
+            proposal)
+              poetry run pytest -q tests/proposal
+              ;;
+            council)
+              # council shard also runs shared tests at tests/test_utils.py
+              poetry run pytest -q tests/council tests/test_utils.py
+              ;;
+            *)
+              echo "Unknown component: ${{ matrix.component }}"
+              exit 1
+              ;;
+          esac