issue:INFINIPS-296: [CI] Add optional stage parameter to group steps in pipeline

* What: Added a new optional 'stage' property to step_conf that groups steps sharing the same stage name and runs them in parallel within sequential stage boundaries.
* How: Introduced getUniqueStages/getStepsForStage helpers, made getTasks/getMatrixTasks/run_parallel_in_chunks stage-aware, and rewired startPipeline to iterate stages sequentially while running each stage's tasks in parallel across all images.
* Why: Allow CI pipeline authors to define logical phases (build, test, deploy) so all steps in a phase complete before the next begins, improving pipeline structure and BlueOcean UI clarity.

Signed-off-by: Benny Itkin <bitkin@nvidia.com>

Author: BennyItkin

.ci/examples/job_matrix_stages.yaml

@@ -0,0 +1,39 @@
+---
+job: ci-demo-stages-example
+
+kubernetes:
+  cloud: swx-k8s-spray
+
+runs_on_dockers:
+  - {name: 'ubuntu2204', url: 'ubuntu:22.04', arch: 'x86_64'}
+  - {name: 'rhel9', url: 'redhat/ubi9', arch: 'x86_64'}
+
+# Steps with the same 'stage' value are grouped and run in parallel
+# under a single Jenkins stage block. Steps without 'stage' run
+# sequentially as usual.
+
+steps:
+  - name: Build lib
+    run: echo "building lib"
+    stage: build
+
+  - name: Build tools
+    run: echo "building tools"
+    stage: build
+
+  - name: Build docs
+    run: echo "building docs"
+    stage: build
+
+  - name: Unit tests
+    run: echo "running unit tests"
+    stage: test
+
+  - name: Integration tests
+    run: echo "running integration tests"
+    stage: test
+
+  - name: Publish
+    containerSelector: "{name:'ubuntu2204'}"
+    stage: publish
+    run: echo "publishing artifacts"

schema_validator/ci_demo_schema.yaml

@@ -139,3 +139,4 @@ step_conf:
   credentialsId: any(str(), list(str()), required=False)
   args: any(list(), map(), str(), required=False)
   env: map(required=False)
+  stage: str(required=False)

src/com/mellanox/cicd/Matrix.groovy

@@ -1038,10 +1038,10 @@ def runAgent(image, config, branchName=null, axis=null, Closure func, runInDocke
 }
 
 
-Map getTasks(axes, image, config, include, exclude) {
+Map getTasks(axes, image, config, include, exclude, stageName=null) {
 
 
-    config.logger.trace(3, "getTasks() --> image=" + image)
+    config.logger.trace(3, "getTasks() --> image=" + image + " stage=" + stageName)
 
     int serialNum = 1
     Map tasks = [:]
@@ -1067,7 +1067,8 @@ Map getTasks(axes, image, config, include, exclude) {
             continue
         }
 
-        if (!config.steps) {
+        def stepsToCheck = stageName ? getStepsForStage(config, stageName) : config.steps
+        if (!stepsToCheck) {
             continue
         }
 
@@ -1081,8 +1082,8 @@ Map getTasks(axes, image, config, include, exclude) {
         def branchName = resolveTemplate(axis, tmpl, config)
 
         def canSkip = true
-        for (int j = 0; j < config.steps.size(); j++) {
-            def oneStep = config.steps[j]
+        for (int j = 0; j < stepsToCheck.size(); j++) {
+            def oneStep = stepsToCheck[j]
             if (!check_skip_stage(image, config, branchName, oneStep, axis)) {
                 canSkip = false
                 break
@@ -1106,6 +1107,7 @@ Map getTasks(axes, image, config, include, exclude) {
         }
 
         config.logger.trace(5, "task name " + branchName)
+        def taskSteps = stageName ? getStepsForStage(config, stageName) : config.steps
         tasks[branchName] = { ->
             withEnv(axisEnv) {
                 if ((config.get("kubernetes") == null) &&
@@ -1120,11 +1122,11 @@ Map getTasks(axes, image, config, include, exclude) {
                         runBareMetal = false
                     }
                     def callback = {pimage, pconfig, pname, paxis, pruntime ->
-                        runSteps(pimage, pconfig, pname, paxis, pruntime)
+                        runSteps(pimage, pconfig, pname, paxis, taskSteps, pruntime)
                     }
                     runAgent(image, config, branchName, axis, callback, runBareMetal)
                 } else {
-                    runK8(image, branchName, config, axis)
+                    runK8(image, branchName, config, axis, taskSteps)
                 }
             }
         }
@@ -1154,10 +1156,31 @@ def resolveIncludeExcludeTemplates(filters, config) {
     return resolvedFilters
 }
 
-def getMatrixTasks(image, config) {
+@NonCPS
+def getUniqueStages(config) {
+    // generate a uniq list of stages from the steps, if no stage is defined, add a default stage
+    def stages = config.steps.collect { it.stage ?: "default" }.unique()
+    return stages
+}
+
+def getStepsForStage(config, stageName) {
+    // generate a list of steps for a given stage
+    def stageSteps = []
+    if (config.steps) {
+        for (step in config.steps) {
+            def stepStage = step.get("stage", "default")
+            if (stepStage == stageName) {
+                stageSteps.add(step)
+            }
+        }
+    }
+    return stageSteps
+}
+
+def getMatrixTasks(image, config, stageName=null) {
 
     def include = [], exclude = [], axes = []
-    config.logger.debug("getMatrixTasks() --> image=" + image)
+    config.logger.debug("getMatrixTasks() --> image=" + image + " stage=" + stageName)
 
     if (config.get("matrix")) {
         axes = getMatrixAxes(config.matrix.axes).findAll()
@@ -1177,7 +1200,7 @@ def getMatrixTasks(image, config) {
                             exclude.size() +
                             "] = " + exclude
                             )
-    return getTasks(axes, image, config, include, exclude)
+    return getTasks(axes, image, config, include, exclude, stageName)
 }
 
 def buildImage(img, filename, extra_args, config, image) {
@@ -1503,7 +1526,7 @@ spec:
     }
 }
 
-def run_parallel_in_chunks(config, myTasks, depth) {
+def run_parallel_in_chunks(config, myTasks, depth, stageName=null) {
 
     if (myTasks.size() == 0) {
         return
@@ -1518,11 +1541,22 @@ def run_parallel_in_chunks(config, myTasks, depth) {
     def val = getConfigVal(config, ['failFast'], false)
 
     config.logger.trace(3, "run_parallel_in_chunks: batch size is ${bSize}")
-    (myTasks.keySet() as List).collate(bSize).each {
-        def batchMap = myTasks.subMap(it)
-        batchMap['failFast'] = val
-        parallel batchMap
+    if (stageName) {
+        stage(stageName) {
+            (myTasks.keySet() as List).collate(bSize).each {
+                def batchMap = myTasks.subMap(it)
+                batchMap['failFast'] = val
+                parallel batchMap
+            }
+        }
+    } else {
+        (myTasks.keySet() as List).collate(bSize).each {
+                def batchMap = myTasks.subMap(it)
+                batchMap['failFast'] = val
+                parallel batchMap
+            }
     }
+
 }
 
 
@@ -1689,7 +1723,45 @@ def startPipeline(String label) {
                                 run_step(null, config, "pipeline start", config.pipeline_start, null)
                             }
                         }
-                        run_parallel_in_chunks(config, branches, bSize)
+
+                        def stage_arch_distro_map = gen_image_map(config)
+                         // Get unique stages and execute sequentially
+                        def stages = getUniqueStages(config)
+                        if (stages.size() > 1) {
+                            config.logger.debug("Unique stages identified: " + stages)
+                            for (stageName in stages) {
+                                config.logger.info("Starting stage: ${stageName}")
+                                
+                                def stageBranches = [:]
+                                                                
+                                for (def entry in entrySet(stage_arch_distro_map)) {
+                                    def images = entry.value
+                                    for (int j=0; j<images.size(); j++) {
+                                        def image = images[j]
+                                        stageBranches += getMatrixTasks(image, config, stageName)
+                                    }
+                                }
+                                
+                                if (config.runs_on_agents) {
+                                    for (int a=0; a<config.runs_on_agents.size();a++) {
+                                        def image = config.runs_on_agents[a]
+                                        image.name = image.nodeLabel
+                                        image.arch = 'x86_64'
+                                        stageBranches += getMatrixTasks(image, config, stageName)
+                                    }
+                                }
+                                
+                                // Run all tasks for this stage in parallel
+                                if (stageBranches.size() > 0) {
+                                    run_parallel_in_chunks(config, stageBranches, bSize,stageName)
+                                }
+                                
+                                config.logger.info("Completed stage: ${stageName}")
+                            }
+                        } else {
+                            // Fallback if no stages defined
+                            run_parallel_in_chunks(config, branches, bSize)
+                        }
                     }
                 }
                 config.env.pipeline_status = 'SUCCESS'