Add comments to workflow files detailing the CI workflow and enable these workflows

Author: maxstack

.github/workflows/extra.yml

@@ -1,4 +1,9 @@
 ---
+
+# Test building extra images on OpenStack.
+# This workflow can run standalone or as part of the main CI workflow.
+# See the workflow file 'main.yml' for how this is CI triggered.
+
 name: Test extra build
 on:
   workflow_dispatch:

.github/workflows/main.yml

@@ -1,4 +1,15 @@
 ---
+
+# This file governs the main CI workflow.
+# It's the only workflow triggered on push and pull requests,
+# it manages the CI workflow as follows:
+# 1. Lint the code aborting the workflow if there are linting errors.
+# 2. Determine which files have changed and set job outputs accordingly.
+# 3. Conditionally run the other workflows based on the changed files:
+#    * stackhpc.yml
+#    * extra.yml
+#    * trivyscan.yml
+
 name: Test on push and pull request
 
 permissions:
@@ -30,10 +41,10 @@ jobs:
     runs-on: ubuntu-latest
     # Map a step output to a job output, this allows other jobs to be gated on the filter results
     outputs:
-        extra_on_push: ${{ steps.filter_on_some.outputs.extra_on_push }}
-        extra_on_pull_request: ${{ steps.filter_on_some.outputs.extra_on_pull_request }}
         # The 'stackhpc' output will be 'true' if either of the two stackhpc filters below matched
         stackhpc: ${{ toJson(fromJson(steps.filter_on_every.outputs.stackhpc) || fromJson(steps.filter_on_some.outputs.stackhpc)) }}
+        extra_on_push: ${{ steps.filter_on_some.outputs.extra_on_push }}
+        extra_on_pull_request: ${{ steps.filter_on_some.outputs.extra_on_pull_request }}
         trivvyscan: ${{ steps.filter_on_some.outputs.trivvyscan }}
     steps:
       - name: Checkout
@@ -82,6 +93,9 @@ jobs:
           predicate-quantifier: 'some'
           list-files: 'json'
           filters: |
+            stackhpc:
+              - 'dev/setup-env.sh'
+              - '.github/workflows/stackhpc.yml'
             extra_on_push:
               - 'environments/.stackhpc/tofu/cluster_image.auto.tfvars.json'
               - 'ansible/roles/doca/**'
@@ -95,65 +109,41 @@ jobs:
               - 'ansible/roles/cuda/**'
               - 'ansible/roles/lustre/**'
               - '.github/workflows/extra.yml'
-            stackhpc:
-              - 'dev/setup-env.sh'
-              - '.github/workflows/stackhpc.yml'
             trivvyscan:
               - 'environments/.stackhpc/tofu/cluster_image.auto.tfvars.json'
 
       - name: Paths matched output
         # NOTE: This is a debug step, it shows what files were matched by the filters.
         #       It's useful because dorny/paths-filter doesn't work like the conventional 'paths' and 'paths_exclude'
         run: >
-          echo '{ "extra_on_push_files": ${{ steps.filter_on_some.outputs.extra_on_push_files }} }' | jq -r '.';
-          echo '{ "extra_on_pull_request_files": ${{ steps.filter_on_some.outputs.extra_on_pull_request_files }} }' | jq -r '.';
           echo '{ "stackhpc_every_files": ${{ steps.filter_on_every.outputs.stackhpc_files }} }' | jq -r '.';
           echo '{ "stackhpc_some_files": ${{ steps.filter_on_some.outputs.stackhpc_files }} }' | jq -r '.';
+          echo '{ "extra_on_push_files": ${{ steps.filter_on_some.outputs.extra_on_push_files }} }' | jq -r '.';
+          echo '{ "extra_on_pull_request_files": ${{ steps.filter_on_some.outputs.extra_on_pull_request_files }} }' | jq -r '.';
           echo '{ "trivvyscan_files": ${{ steps.filter_on_some.outputs.trivvyscan_files }} }' | jq -r '.'
 
+  stackhpc:
+    name: Test deployment and reimage on OpenStack
+    needs: files_changed
+    if: |
+      needs.files_changed.outputs.stackhpc == 'true'
+    uses: ./.github/workflows/stackhpc.yml
+    secrets: inherit
+
   extra:
     name: Test extra build
     needs: files_changed
     if: |
       github.event_name != 'pull_request' && needs.files_changed.outputs.extra_on_push == 'true' ||
       github.event_name == 'pull_request' && needs.files_changed.outputs.extra_on_pull_request == 'true'
-    #uses: ./.github/workflows/extra.yml
-    #secrets: inherit
-    # TEST - remove from here and uncomment the above two lines
-    steps:
-      - name: Test extra build...
-        uses: jakejarvis/wait-action@master
-        with:
-          time: '120s'
-    runs-on: ubuntu-latest
-
-  stackhpc:
-    name: Test deployment and reimage on OpenStack
-    needs: files_changed
-    if: |
-      needs.files_changed.outputs.stackhpc == 'true'
-    #uses: ./.github/workflows/stackhpc.yml
-    #secrets: inherit
-    # TEST - remove from here and uncomment the above two lines
-    steps:
-      - name: Test deployment and reimage on OpenStack...
-        uses: jakejarvis/wait-action@master
-        with:
-          time: '120s'
-    runs-on: ubuntu-latest
+    uses: ./.github/workflows/extra.yml
+    secrets: inherit
 
   trivvyscan:
     name: Trivy scan image for vulnerabilities
     needs: files_changed
     if: |
       github.event_name == 'pull_request' &&
       needs.files_changed.outputs.trivvyscan == 'true'
-    #uses: ./.github/workflows/trivvyscan.yml
-    #secrets: inherit
-    # TEST - remove from here and uncomment the above two lines
-    steps:
-      - name: Trivy scan image for vulnerabilities...
-        uses: jakejarvis/wait-action@master
-        with:
-          time: '120s'
-    runs-on: ubuntu-latest
+    uses: ./.github/workflows/trivvyscan.yml
+    secrets: inherit

.github/workflows/stackhpc.yml

@@ -1,4 +1,9 @@
 ---
+
+# Test deployment and reimage on OpenStack.
+# This workflow can run standalone or as part of the main CI workflow.
+# See the workflow file 'main.yml' for how this is CI triggered.
+
 name: Test deployment and reimage on OpenStack
 on:
   workflow_dispatch:

.github/workflows/trivyscan.yml

@@ -1,4 +1,9 @@
 ---
+
+# Scan the built image for vulnerabilities using Trivy.
+# This workflow can run standalone or as part of the main CI workflow.
+# See the workflow file 'main.yml' for how this is CI triggered.
+
 name: Trivy scan image for vulnerabilities
 on:
   workflow_dispatch: