feat: Add support for when within matrix.include

docs/pipeline-api.md

@@ -1684,6 +1684,20 @@ Params
 The names of the <code>params</code> must match the names of the <code>params</code> in the underlying <code>Task</code></p>
 </td>
 </tr>
+<tr>
+<td>
+<code>when</code><br/>
+<em>
+<a href="#tekton.dev/v1.WhenExpressions">
+WhenExpressions
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>When is a list of when expressions that need to be true for the matrix task to run</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="tekton.dev/v1.Matrix">Matrix
@@ -6323,7 +6337,7 @@ More info about CEL syntax: <a href="https://github.com/google/cel-spec/blob/mas
 <h3 id="tekton.dev/v1.WhenExpressions">WhenExpressions
 (<code>[]github.com/tektoncd/pipeline/pkg/apis/pipeline/v1.WhenExpression</code> alias)</h3>
 <p>
-(<em>Appears on:</em><a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1.Step">Step</a>)
+(<em>Appears on:</em><a href="#tekton.dev/v1.IncludeParams">IncludeParams</a>, <a href="#tekton.dev/v1.PipelineTask">PipelineTask</a>, <a href="#tekton.dev/v1.Step">Step</a>)
 </p>
 <div>
 <p>WhenExpressions are used to specify whether a Task should be executed or skipped

examples/v1/pipelineruns/beta/pipelinerun-with-matrix-when-include.yaml

@@ -0,0 +1,92 @@
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: mytask
+  annotations:
+    description: |
+      A task that does something cool with GOARCH and version
+spec:
+  params:
+    - name: IMAGE
+      default: ''
+    - name: PLATFORM
+      default: ''
+  steps:
+    - name: echo
+      image: mirror.gcr.io/alpine
+      script: |
+        echo image: $(params.IMAGE) and platform: $(params.PLATFORM)
+---
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  generateName: matrixed-include-when-pr
+spec:
+  taskRunTemplate:
+    serviceAccountName: default
+  params:
+    - name: enabled-platforms
+      value:
+        - arm64
+        - amd64
+    - name: platform-amd64
+      value: linux/amd64
+    - name: platform-arm64
+      value: linux/arm64
+    - name: platform-ppc64le
+      value: linux-m4.xl/ppc64le
+    - name: platform-s390x
+      value: linux/s390x
+    - name: output-image
+      value: my-image
+  pipelineSpec:
+    tasks:
+      - name: build-containers-multi-platform
+        matrix:
+          include:
+            - name: amd64
+              params:
+                - name: IMAGE
+                  value: $(params.output-image)-amd64
+                - name: PLATFORM
+                  value: $(params.platform-amd64)
+              when:
+                - input: "amd64"
+                  operator: in
+                  values:
+                    - "$(params.enabled-platforms[*])"
+            - name: arm64
+              params:
+                - name: IMAGE
+                  value: $(params.output-image)-arm64
+                - name: PLATFORM
+                  value: $(params.platform-arm64)
+              when:
+                - input: "arm64"
+                  operator: in
+                  values:
+                    - "$(params.enabled-platforms[*])"
+            - name: ppc64le
+              params:
+                - name: IMAGE
+                  value: $(params.output-image)-ppc64le
+                - name: PLATFORM
+                  value: $(params.platform-ppc64le)
+              when:
+                - input: "ppc64le"
+                  operator: in
+                  values:
+                    - "$(params.enabled-platforms[*])"
+            - name: s390x
+              params:
+                - name: IMAGE
+                  value: $(params.output-image)-s390x
+                - name: PLATFORM
+                  value: $(params.platform-s390x)
+              when:
+                - input: "s390x"
+                  operator: in
+                  values:
+                    - "$(params.enabled-platforms[*])"
+        taskRef:
+          name: mytask

pkg/apis/pipeline/v1/matrix_types.go

@@ -52,6 +52,20 @@ type IncludeParams struct {
 	// The names of the `params` must match the names of the `params` in the underlying `Task`
 	// +listType=atomic
 	Params Params `json:"params,omitempty"`
+
+	// When is a list of when expressions that need to be true for the matrix task to run
+	// +optional
+	When WhenExpressions `json:"when,omitempty"`
+}
+
+func (i IncludeParamsList) validIncludeNum() int {
+	count := 0
+	for _, include := range i {
+		if include.When.AllowsExecution(nil) {
+			count++
+		}
+	}
+	return count
 }
 
 // Combination is a map, mainly defined to hold a single combination from a Matrix with key as param.Name and value as param.Value
@@ -167,6 +181,9 @@ func (cs Combinations) fanOutMatrixParams(param Param) Combinations {
 func (m *Matrix) getIncludeCombinations() Combinations {
 	var combinations Combinations
 	for i := range m.Include {
+		if !m.Include[i].When.AllowsExecution(nil) {
+			continue
+		}
 		includeParams := m.Include[i].Params
 		newCombination := make(Combination)
 		for _, param := range includeParams {
@@ -248,11 +265,14 @@ func (m *Matrix) countNewCombinationsFromInclude() int {
 		return 0
 	}
 	if !m.HasParams() {
-		return len(m.Include)
+		return m.Include.validIncludeNum()
 	}
 	count := 0
 	matrixParamMap := m.Params.extractParamMapArrVals()
 	for _, include := range m.Include {
+		if !include.When.AllowsExecution(nil) {
+			continue
+		}
 		for _, param := range include.Params {
 			if val, exist := matrixParamMap[param.Name]; exist {
 				// If the Matrix Include param values does not exist, a new Combination will be generated

pkg/apis/pipeline/v1/pipeline_validation.go

@@ -224,6 +224,20 @@ func (pt *PipelineTask) validateMatrix(ctx context.Context) (errs *apis.FieldErr
 		errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "matrix", config.BetaAPIFields))
 		errs = errs.Also(pt.Matrix.validateCombinationsCount(ctx))
 		errs = errs.Also(pt.Matrix.validateUniqueParams())
+		if pt.Matrix.HasInclude() {
+			for i := range pt.Matrix.Include {
+				if pt.Matrix.Include[i].When != nil {
+					for _, we := range pt.Matrix.Include[i].When {
+						if we.CEL != "" {
+							// CEL is not allowed in matrix.include.when
+							errs = errs.Also(apis.ErrDisallowedFields("matrix.include.when.cel"))
+							return errs
+						}
+					}
+					errs = errs.Also(pt.Matrix.Include[i].When.validateWhenExpressionsFields(ctx).ViaFieldIndex("matrix.include", i))
+				}
+			}
+		}
 	}
 	errs = errs.Also(pt.Matrix.validateParameterInOneOfMatrixOrParams(pt.Params))
 	return errs

pkg/apis/pipeline/v1/pipeline_validation_test.go

@@ -4671,6 +4671,24 @@ func Test_validateMatrix(t *testing.T) {
 			}},
 		}},
 		wantErrs: apis.ErrInvalidValue("Matrixed PipelineTasks emitting results must have an underlying type string, but result array-result has type array in pipelineTask", ""),
+	}, {
+		name: "cel in matrix include when expression",
+		tasks: PipelineTaskList{{
+			Name:    "a-task",
+			TaskRef: &TaskRef{Name: "a-task"},
+			Matrix: &Matrix{
+				Include: IncludeParamsList{
+					{
+						When: WhenExpressions{
+							{
+								CEL: "platform == 'linux'",
+							},
+						},
+					},
+				},
+			},
+		}},
+		wantErrs: apis.ErrDisallowedFields("[0].matrix.include.when.cel"),
 	}}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

pkg/apis/pipeline/v1/swagger.json

@@ -345,6 +345,14 @@
             "$ref": "#/definitions/v1.Param"
           },
           "x-kubernetes-list-type": "atomic"
+        },
+        "when": {
+          "description": "When is a list of when expressions that need to be true for the matrix task to run",
+          "type": "array",
+          "items": {
+            "default": {},
+            "$ref": "#/definitions/v1.WhenExpression"
+          }
         }
       }
     },

pkg/apis/pipeline/v1beta1/matrix_types.go

@@ -52,6 +52,20 @@ type IncludeParams struct {
 	// The names of the `params` must match the names of the `params` in the underlying `Task`
 	// +listType=atomic
 	Params Params `json:"params,omitempty"`
+
+	// When is a list of when expressions that need to be true for the matrix task to run
+	// +optional
+	When WhenExpressions `json:"when,omitempty"`
+}
+
+func (i IncludeParamsList) validIncludeNum() int {
+	count := 0
+	for _, include := range i {
+		if include.When.AllowsExecution(nil) {
+			count++
+		}
+	}
+	return count
 }
 
 // Combination is a map, mainly defined to hold a single combination from a Matrix with key as param.Name and value as param.Value
@@ -167,6 +181,9 @@ func (cs Combinations) fanOutMatrixParams(param Param) Combinations {
 func (m *Matrix) getIncludeCombinations() Combinations {
 	var combinations Combinations
 	for i := range m.Include {
+		if !m.Include[i].When.AllowsExecution(nil) {
+			continue
+		}
 		includeParams := m.Include[i].Params
 		newCombination := make(Combination)
 		for _, param := range includeParams {
@@ -248,11 +265,14 @@ func (m *Matrix) countNewCombinationsFromInclude() int {
 		return 0
 	}
 	if !m.HasParams() {
-		return len(m.Include)
+		return m.Include.validIncludeNum()
 	}
 	count := 0
 	matrixParamMap := m.Params.extractParamMapArrVals()
 	for _, include := range m.Include {
+		if !include.When.AllowsExecution(nil) {
+			continue
+		}
 		for _, param := range include.Params {
 			if val, exist := matrixParamMap[param.Name]; exist {
 				// If the Matrix Include param values does not exist, a new Combination will be generated

pkg/apis/pipeline/v1beta1/pipeline_conversion.go

@@ -19,7 +19,6 @@ package v1beta1
 import (
 	"context"
 	"fmt"
-
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
 	v1 "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1"
@@ -280,6 +279,14 @@ func (m *Matrix) convertTo(ctx context.Context, sink *v1.Matrix) {
 	}
 	for i, include := range m.Include {
 		sink.Include = append(sink.Include, v1.IncludeParams{Name: include.Name})
+		if m.Include[i].When != nil {
+			sink.Include[i].When = v1.WhenExpressions{}
+			for _, we := range m.Include[i].When {
+				newWe := v1.WhenExpression{}
+				we.convertTo(ctx, &newWe)
+				sink.Include[i].When = append(sink.Include[i].When, newWe)
+			}
+		}
 		for _, param := range include.Params {
 			newIncludeParam := v1.Param{}
 			param.convertTo(ctx, &newIncludeParam)
@@ -297,6 +304,14 @@ func (m *Matrix) convertFrom(ctx context.Context, source v1.Matrix) {
 
 	for i, include := range source.Include {
 		m.Include = append(m.Include, IncludeParams{Name: include.Name})
+		if source.Include[i].When != nil {
+			m.Include[i].When = WhenExpressions{}
+			for _, we := range source.Include[i].When {
+				newWe := WhenExpression{}
+				newWe.convertFrom(ctx, we)
+				m.Include[i].When = append(m.Include[i].When, newWe)
+			}
+		}
 		for _, p := range include.Params {
 			new := Param{}
 			new.ConvertFrom(ctx, p)

pkg/apis/pipeline/v1beta1/pipeline_validation.go

@@ -247,6 +247,20 @@ func (pt *PipelineTask) validateMatrix(ctx context.Context) (errs *apis.FieldErr
 		errs = errs.Also(config.ValidateEnabledAPIFields(ctx, "matrix", config.BetaAPIFields))
 		errs = errs.Also(pt.Matrix.validateCombinationsCount(ctx))
 		errs = errs.Also(pt.Matrix.validateUniqueParams())
+		if pt.Matrix.HasInclude() {
+			for i := range pt.Matrix.Include {
+				if pt.Matrix.Include[i].When != nil {
+					for _, we := range pt.Matrix.Include[i].When {
+						if we.CEL != "" {
+							// CEL is not allowed in matrix.include.when
+							errs = errs.Also(apis.ErrDisallowedFields("matrix.include.when.cel"))
+							return errs
+						}
+					}
+					errs = errs.Also(pt.Matrix.Include[i].When.validateWhenExpressionsFields(ctx).ViaFieldIndex("matrix.include", i))
+				}
+			}
+		}
 	}
 	errs = errs.Also(pt.Matrix.validateParameterInOneOfMatrixOrParams(pt.Params))
 	return errs