ci(vv): aggregate Pages publish into one workflow to avoid concurrency cancellations

.github/workflows/publish-index.yml

@@ -1,10 +1,10 @@
 name: Publish V&V index page
 
 # Deploys docs/index.html to the root of the gh-pages branch whenever it
-# changes on development or main. Per-module workflows (vv-uds.yml,
-# vv-pid.yml, etc.) deploy their HTML reports to subdirectories of the
-# same gh-pages branch using keep_files: true, so this index page sits
-# at the root and links into them.
+# changes on development or main. The per-module HTML reports are
+# published by publish-vv-reports.yml into subdirectories of the same
+# gh-pages branch (vv_<module>/<branch>/), using keep_files: true so
+# this index page sits at the root and links into them.
 
 on:
   push:

.github/workflows/publish-vv-reports.yml

@@ -0,0 +1,179 @@
+name: Publish V&V reports
+
+# Aggregator that publishes the per-module HTML reports to GitHub Pages
+# in a single deploy after every triggered V&V workflow has completed
+# for the same commit. Prior design ran a publish-pages job inside each
+# of the V&V workflows; with five concurrent push triggers, GitHub
+# Actions' "1 running + 1 queued in concurrency group" rule cancelled
+# 3 of 5 publish jobs, leaving stale reports on Pages.
+#
+# This workflow listens for completion of any of the five V&V workflows
+# and fans them in here. Each V&V workflow has narrow `paths:` filters,
+# so a given push may trigger only a subset of them; the gate treats
+# workflows that did not run for the SHA as "not applicable" and
+# deploys once every workflow that DID run has completed successfully.
+# Modules that did not run keep their previous gh-pages content
+# untouched via `keep_files: true`.
+#
+# The publish-index.yml workflow continues to deploy the root
+# docs/index.html landing page; this aggregator deploys the per-module
+# subdirectories under it, branch-namespaced as vv_<module>/<branch>/
+# so dev and main snapshots remain isolated.
+
+on:
+  workflow_run:
+    # NOTE: the names below must stay in sync with each vv-*.yml's
+    # `name:` field, the bash arrays in the steps further down, and
+    # `art_prefix`. Renaming a workflow without updating all four
+    # places silently drops that module from the aggregator.
+    workflows:
+      - "CAN V&V"
+      - "Decision V&V"
+      - "Perception V&V"
+      - "PID + Alert V&V"
+      - "UDS V&V"
+    types: [completed]
+
+permissions:
+  contents: write
+  actions: read
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Aggregate and publish to gh-pages
+    runs-on: ubuntu-24.04
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      (github.event.workflow_run.head_branch == 'development' ||
+       github.event.workflow_run.head_branch == 'main')
+    steps:
+      - name: Gate — wait until every triggered V&V workflow has completed for this SHA
+        id: gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          set -e
+          workflows=("CAN V&V" "Decision V&V" "Perception V&V" "PID + Alert V&V" "UDS V&V")
+          all_done=true
+          all_success=true
+          ran_count=0
+          for wf in "${workflows[@]}"; do
+            row=$(gh run list \
+                --workflow "$wf" \
+                --commit "$SHA" \
+                --limit 1 \
+                --json status,conclusion,databaseId \
+                --jq '.[0] // {}')
+            status=$(echo "$row" | jq -r '.status     // "unknown"')
+            concl=$( echo "$row" | jq -r '.conclusion // ""')
+            id=$(    echo "$row" | jq -r '.databaseId // 0')
+            if [ "$id" = "0" ] || [ "$id" = "null" ] || [ -z "$id" ]; then
+              echo "  $wf: no run for this SHA (path filter did not match) — skipping"
+              continue
+            fi
+            echo "  $wf: status=$status, conclusion=$concl, run=$id"
+            ran_count=$((ran_count + 1))
+            if [ "$status" != "completed" ]; then
+              all_done=false
+            elif [ "$concl" != "success" ]; then
+              all_success=false
+            fi
+          done
+
+          if [ "$ran_count" -eq 0 ]; then
+            echo "No V&V workflow ran for SHA $SHA. Nothing to publish."
+            echo "go=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ "$all_done" != "true" ]; then
+            echo "Not all triggered V&V workflows have completed yet. Exiting silently."
+            echo "go=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ "$all_success" != "true" ]; then
+            echo "All triggered workflows completed but at least one failed. Skipping deploy so reports stay aligned."
+            echo "go=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "$ran_count triggered V&V workflow(s) complete & successful for SHA $SHA — proceeding with deploy."
+          echo "go=true" >> "$GITHUB_OUTPUT"
+
+      - name: Stage site directory
+        if: steps.gate.outputs.go == 'true'
+        run: mkdir -p site
+
+      - name: Download artefacts from each triggered V&V run
+        if: steps.gate.outputs.go == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+          BRANCH: ${{ github.event.workflow_run.head_branch }}
+        run: |
+          set -e
+          # Map: workflow name → site subdirectory + artefact-name prefix.
+          # Keep in sync with the `on.workflow_run.workflows` list above
+          # and each vv-*.yml's `Upload artefacts` step name.
+          declare -A site_dir=(
+            ["CAN V&V"]="vv_can"
+            ["Decision V&V"]="vv_decision"
+            ["Perception V&V"]="vv_perception"
+            ["PID + Alert V&V"]="vv_pid_alert"
+            ["UDS V&V"]="vv_uds"
+          )
+          declare -A art_prefix=(
+            ["CAN V&V"]="vv-can-reports-run"
+            ["Decision V&V"]="vv-decision-reports-run"
+            ["Perception V&V"]="vv-perception-reports-run"
+            ["PID + Alert V&V"]="vv-pid-alert-reports-run"
+            ["UDS V&V"]="vv-uds-reports-run"
+          )
+
+          for wf in "${!site_dir[@]}"; do
+            module="${site_dir[$wf]}"
+            prefix="${art_prefix[$wf]}"
+
+            row=$(gh run list \
+                --workflow "$wf" \
+                --commit "$SHA" \
+                --limit 1 \
+                --json databaseId,number \
+                --jq '.[0] // {}')
+            run_id=$(echo "$row"     | jq -r '.databaseId // 0')
+            run_number=$(echo "$row" | jq -r '.number     // 0')
+
+            if [ "$run_id" = "0" ] || [ "$run_id" = "null" ] || [ -z "$run_id" ]; then
+              echo "  $wf: no run for this SHA — leaving previous gh-pages content untouched"
+              continue
+            fi
+
+            artefact_name="${prefix}${run_number}"
+            # Branch-namespaced destination matches the step summary links
+            # (https://erycaaf.github.io/AEB-stellantis-project/vv_<module>/<branch>/)
+            # and keeps `main` and `development` deploys isolated.
+            target="site/${module}/${BRANCH}"
+            mkdir -p "$target"
+
+            echo "=== $wf (run #$run_number, id=$run_id) → ${target} ==="
+            if ! gh run download "$run_id" -n "$artefact_name" -D "$target"; then
+              echo "  ! gh run download failed for ${artefact_name}; report missing for this push."
+            fi
+          done
+
+          echo "--- Final site/ tree ---"
+          ls -lR site/ | head -60
+
+      - name: Deploy aggregated reports to gh-pages
+        if: steps.gate.outputs.go == 'true'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true
+          user_name: 'github-actions[bot]'
+          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
+          commit_message: 'docs(vv): publish V&V reports for ${{ github.event.workflow_run.head_branch }}@${{ github.event.workflow_run.head_sha }}'

.github/workflows/vv-can.yml

@@ -8,9 +8,9 @@ name: CAN V&V
 #
 # Reports are published in two layers:
 #   1. Workflow Artifacts on every run (PR or push), retention 30 days.
-#   2. GitHub Pages (gh-pages branch) on push to development/main —
-#      navigable HTML reports under
-#      https://erycaaf.github.io/AEB-stellantis-project/vv_can/<branch>/.
+#   2. GitHub Pages — published by publish-vv-reports.yml after every
+#      triggered V&V workflow on the SHA completes successfully.
+#      Live URL: https://erycaaf.github.io/AEB-stellantis-project/vv_can/<branch>/.
 
 on:
   pull_request:
@@ -190,30 +190,3 @@ jobs:
           name: vv-can-reports-run${{ github.run_number }}
           path: reports/vv_can/
           retention-days: 30
-
-  publish-pages:
-    needs: vv-can
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/development' || github.ref == 'refs/heads/main')
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: write
-    concurrency:
-      group: gh-pages-deploy
-      cancel-in-progress: false
-    steps:
-      - name: Download reports
-        uses: actions/download-artifact@v4
-        with:
-          name: vv-can-reports-run${{ github.run_number }}
-          path: site/
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          destination_dir: vv_can/${{ github.ref_name }}
-          keep_files: true
-          user_name: 'github-actions[bot]'
-          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
-          commit_message: 'docs(vv-can): publish reports from run #${{ github.run_number }} (${{ github.ref_name }})'

.github/workflows/vv-decision.yml

@@ -8,8 +8,9 @@ name: Decision V&V
 # (fix/decision-review-followup) closed all V&V findings; any new
 # regression is now treated as a CI failure, mirroring vv-uds.
 #
-# Reports are published as workflow artefacts on every run and to
-# GitHub Pages on push to development/main under
+# Reports are published as workflow artefacts on every run, and to
+# GitHub Pages by publish-vv-reports.yml after every triggered V&V
+# workflow on the SHA completes successfully. Live URL:
 # https://erycaaf.github.io/AEB-stellantis-project/vv_decision/<branch>/.
 
 on:
@@ -239,33 +240,3 @@ jobs:
           name: vv-decision-reports-run${{ github.run_number }}
           path: reports/vv_decision/
           retention-days: 30
-
-  # Per-module workflows publish their own subdirectory under vv_<module>/
-  # on gh-pages; keep_files: true preserves the others.
-  publish-pages:
-    needs: vv-decision
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/development' || github.ref == 'refs/heads/main')
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: write
-    # Shared group across all gh-pages deploys to avoid non-fast-forward races.
-    concurrency:
-      group: gh-pages-deploy
-      cancel-in-progress: false
-    steps:
-      - name: Download reports
-        uses: actions/download-artifact@v4
-        with:
-          name: vv-decision-reports-run${{ github.run_number }}
-          path: site/
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          destination_dir: vv_decision/${{ github.ref_name }}
-          keep_files: true
-          user_name: 'github-actions[bot]'
-          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
-          commit_message: 'docs(vv-decision): publish reports from run #${{ github.run_number }} (${{ github.ref_name }})'

.github/workflows/vv-perception.yml

@@ -12,9 +12,9 @@ name: Perception V&V
 #
 # Reports are published in two layers:
 #   1. Workflow Artifacts on every run (PR or push), retention 30 days.
-#   2. GitHub Pages (gh-pages branch) on push to development/main —
-#      navigable HTML reports under
-#      https://erycaaf.github.io/AEB-stellantis-project/vv_perception/<branch>/.
+#   2. GitHub Pages — published by publish-vv-reports.yml after every
+#      triggered V&V workflow on the SHA completes successfully.
+#      Live URL: https://erycaaf.github.io/AEB-stellantis-project/vv_perception/<branch>/.
 
 on:
   pull_request:
@@ -230,38 +230,3 @@ jobs:
           name: vv-perception-reports-run${{ github.run_number }}
           path: reports/vv_perception/
           retention-days: 30
-
-  # ───────────────────────────────────────────────────────────────────────
-  # Publish HTML reports to GitHub Pages on push to development/main only.
-  # Each module workflow publishes its own subdirectory under vv_<module>/
-  # on the gh-pages branch; keep_files: true preserves the others.
-  # ───────────────────────────────────────────────────────────────────────
-  publish-pages:
-    needs: vv-perception
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/development' || github.ref == 'refs/heads/main')
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: write
-    # Serialise every gh-pages push across ALL workflows in the repo
-    # (vv-uds, vv-perception, vv-<other>, publish-index, ...) to avoid
-    # non-fast-forward races. Shared string, no ref suffix.
-    concurrency:
-      group: gh-pages-deploy
-      cancel-in-progress: false
-    steps:
-      - name: Download reports
-        uses: actions/download-artifact@v4
-        with:
-          name: vv-perception-reports-run${{ github.run_number }}
-          path: site/
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          destination_dir: vv_perception/${{ github.ref_name }}
-          keep_files: true
-          user_name: 'github-actions[bot]'
-          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
-          commit_message: 'docs(vv-perception): publish reports from run #${{ github.run_number }} (${{ github.ref_name }})'

.github/workflows/vv-pid-alert.yml

@@ -6,8 +6,9 @@ name: PID + Alert V&V
 # bugs are patched on fix/pid-robustness — flip `continue-on-error`
 # to `false` after that PR lands.
 #
-# Reports are published as workflow artefacts on every run and to
-# GitHub Pages on push to development/main under
+# Reports are published as workflow artefacts on every run, and to
+# GitHub Pages by publish-vv-reports.yml after every triggered V&V
+# workflow on the SHA completes successfully. Live URL:
 # https://erycaaf.github.io/AEB-stellantis-project/vv_pid_alert/<branch>/.
 
 on:
@@ -268,33 +269,3 @@ jobs:
           name: vv-pid-alert-reports-run${{ github.run_number }}
           path: reports/vv_pid_alert/
           retention-days: 30
-
-  # Per-module workflows publish their own subdirectory under vv_<module>/
-  # on gh-pages; keep_files: true preserves the others.
-  publish-pages:
-    needs: vv-pid-alert
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/development' || github.ref == 'refs/heads/main')
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: write
-    # Shared group across all gh-pages deploys to avoid non-fast-forward races.
-    concurrency:
-      group: gh-pages-deploy
-      cancel-in-progress: false
-    steps:
-      - name: Download reports
-        uses: actions/download-artifact@v4
-        with:
-          name: vv-pid-alert-reports-run${{ github.run_number }}
-          path: site/
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./site
-          destination_dir: vv_pid_alert/${{ github.ref_name }}
-          keep_files: true
-          user_name: 'github-actions[bot]'
-          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
-          commit_message: 'docs(vv-pid-alert): publish reports from run #${{ github.run_number }} (${{ github.ref_name }})'