tektoncd · tekton-robot · Mar 15, 2024 · Jan 11, 2024
diff --git a/docs/matrix.md b/docs/matrix.md
@@ -155,6 +155,84 @@ Combinations generated
 { "IMAGE": "image-3", "DOCKERFILE": "path/to/Dockerfile3}
 ```
 
+## DisplayName
+
+Matrix creates multiple `taskRuns` with the same `pipelineTask`. Each `taskRun` has its unique combination `params` based
+on the `matrix` specifications. These `params` can now be surfaced and used to configure unique name of each `matrix`
+instance such that it is easier to distinguish all the instances based on their inputs.
+
+```yaml
+pipelineSpec:
+  tasks:
+    - name: platforms-and-browsers
+      displayName: "Platforms and Browsers: $(params.platform) and $(params.browser)"
+      matrix:
+        params:
+          - name: platform
+            value:
+              - linux
+              - mac
+              - windows
+          - name: browser
+            value:
+              - chrome
+              - safari
+              - firefox
+      taskRef:
+        name: platform-browsers
+```
+
+The `displayName` is available as part of `pipelineRun.status.childReferences` with each `taskRun`.
+This allows the clients to consume `displayName` wherever needed:
+
+```json
+[
+  {
+    "apiVersion": "tekton.dev/v1",
+    "displayName": "Platforms and Browsers: linux and chrome",
+    "kind": "TaskRun",
+    "name": "matrixed-pr-vcx79-platforms-and-browsers-0",
+    "pipelineTaskName": "platforms-and-browsers"
+  },
+  {
+    "apiVersion": "tekton.dev/v1",
+    "displayName": "Platforms and Browsers: mac and safari",
+    "kind": "TaskRun",
+    "name": "matrixed-pr-vcx79-platforms-and-browsers-1",
+    "pipelineTaskName": "platforms-and-browsers"
+  }
+]
+```
+
+### `matrix.include[].name`
+
+`matrix.include[]` section allows specifying a `name` along with a list of `params`. This `name` field is available as
+part of the `pipelineRun.status.childReferences[].displayName` if specified.
+
+`displayName` and `matrix.include[].name` can co-exist but `matrix.include[].name` takes higher precedence. It is also
+possible for the pipeline author to specify `params` in `matrix.include[].name` which are resolved in the `childReferences`.
+
+```yaml
+- name: platforms-and-browsers-with-include
+  matrix:
+    include:
+      - name: "Platform: $(params.platform)"
+        params:
+          - name: platform
+            value: linux111
+  params:
+    - name: browser
+      value: chrome
+```
+
+### Precedence Order
+
+| specification                                             | precedence                      | `childReferences[].displayName` |
+|-----------------------------------------------------------|---------------------------------|---------------------------------|
+| `tasks[].displayName`                                     | `tasks[].displayName`           | `tasks[].displayName`           |
+| `tasks[].matrix.include[].name`                           | `tasks[].matrix.include[].name` | `tasks[].matrix.include[].name` |
+| `tasks[].displayName` and `tasks[].matrix.include[].name` | `tasks[].matrix.include[].name` | `tasks[].matrix.include[].name` |
+
 ## Concurrency Control
 
 The default maximum count of `TaskRuns` or `Runs` from a given `Matrix` is **256**. To customize the maximum count of

diff --git a/docs/pipeline-api.md b/docs/pipeline-api.md
@@ -1419,6 +1419,18 @@ string
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>DisplayName is a user-facing name of the pipelineTask that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>pipelineTaskName</code><br/>
 <em>
 string
@@ -9709,6 +9721,18 @@ string
 </tr>
 <tr>
 <td>
+<code>displayName</code><br/>
+<em>
+string
+</em>
+</td>
+<td>
+<p>DisplayName is a user-facing name of the pipelineTask that may be
+used to populate a UI.</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>pipelineTaskName</code><br/>
 <em>
 string

diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -434,6 +434,10 @@ Specifying task results in the `displayName` does not introduce an inherent reso
 pipeline author is responsible for specifying dependency explicitly either using [runAfter](#using-the-runafter-field)
 or rely on [whenExpressions](#guard-task-execution-using-when-expressions) or [task results in params](#using-results).
 
+Fully resolved `displayName` is also available in the status as part of the `pipelineRun.status.childReferences`. The
+clients such as the dashboard, CLI, etc. can retrieve the `displayName` from the `childReferences`. The `displayName` mainly
+drives a better user experience and at the same time it is not validated for the content or length by the controller.
+
 ### Specifying Remote Tasks
 
 **([beta feature](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#beta-features))**
@@ -1542,6 +1546,10 @@ The `displayName` also allows you to parameterize the human-readable name of you
 [params](#specifying-parameters), [the task results](#consuming-task-execution-results-in-finally),
 and [the context variables](#context-variables).
 
+Fully resolved `displayName` is also available in the status as part of the `pipelineRun.status.childReferences`. The
+clients such as the dashboard, CLI, etc. can retrieve the `displayName` from the `childReferences`. The `displayName` mainly
+drives a better user experience and at the same time it is not validated for the content or length by the controller.
+
 ### Specifying `Workspaces` in `finally` tasks
 
 `finally` tasks can specify [workspaces](workspaces.md) which `PipelineTasks` might have utilized

diff --git a/examples/v1/pipelineruns/beta/pipelinerun-with-matrix.yaml b/examples/v1/pipelineruns/beta/pipelinerun-with-matrix.yaml
@@ -25,6 +25,7 @@ spec:
   pipelineSpec:
     tasks:
       - name: platforms-and-browsers
+        displayName: "Platform: $(params.platform) with Browser: $(params.browser)"
         matrix:
           params:
             - name: platform
@@ -52,6 +53,18 @@ spec:
             value: chrome
         taskRef:
           name: platform-browsers
+      - name: matrix-and-params-include
+        matrix:
+          include:
+            - name: "Platform: $(params.platform) with Browser: $(params.browser)"
+              params:
+                - name: platform
+                  value: linux
+        params:
+          - name: browser
+            value: chrome
+        taskRef:
+          name: platform-browsers
       - name: matrix-params-with-empty-array-skipped
         matrix:
           params:

diff --git a/pkg/apis/pipeline/v1/openapi_generated.go b/pkg/apis/pipeline/v1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1/pipelinerun_types.go b/pkg/apis/pipeline/v1/pipelinerun_types.go
@@ -484,6 +484,9 @@ type ChildStatusReference struct {
 	runtime.TypeMeta `json:",inline"`
 	// Name is the name of the TaskRun or Run this is referencing.
 	Name string `json:"name,omitempty"`
+	// DisplayName is a user-facing name of the pipelineTask that may be
+	// used to populate a UI.
+	DisplayName string `json:"displayName,omitempty"`
 	// PipelineTaskName is the name of the PipelineTask this is referencing.
 	PipelineTaskName string `json:"pipelineTaskName,omitempty"`
 

diff --git a/pkg/apis/pipeline/v1/swagger.json b/pkg/apis/pipeline/v1/swagger.json
@@ -192,6 +192,10 @@
         "apiVersion": {
           "type": "string"
         },
+        "displayName": {
+          "description": "DisplayName is a user-facing name of the pipelineTask that may be used to populate a UI.",
+          "type": "string"
+        },
         "kind": {
           "type": "string"
         },

diff --git a/pkg/apis/pipeline/v1beta1/openapi_generated.go b/pkg/apis/pipeline/v1beta1/openapi_generated.go
diff --git a/pkg/apis/pipeline/v1beta1/pipelinerun_conversion.go b/pkg/apis/pipeline/v1beta1/pipelinerun_conversion.go
@@ -332,6 +332,7 @@ func (st *SkippedTask) convertFrom(ctx context.Context, source v1.SkippedTask) {
 func (csr ChildStatusReference) convertTo(ctx context.Context, sink *v1.ChildStatusReference) {
 	sink.TypeMeta = csr.TypeMeta
 	sink.Name = csr.Name
+	sink.DisplayName = csr.DisplayName
 	sink.PipelineTaskName = csr.PipelineTaskName
 	sink.WhenExpressions = nil
 	for _, we := range csr.WhenExpressions {
@@ -344,6 +345,7 @@ func (csr ChildStatusReference) convertTo(ctx context.Context, sink *v1.ChildSta
 func (csr *ChildStatusReference) convertFrom(ctx context.Context, source v1.ChildStatusReference) {
 	csr.TypeMeta = source.TypeMeta
 	csr.Name = source.Name
+	csr.DisplayName = source.DisplayName
 	csr.PipelineTaskName = source.PipelineTaskName
 	csr.WhenExpressions = nil
 	for _, we := range source.WhenExpressions {

diff --git a/pkg/apis/pipeline/v1beta1/pipelinerun_conversion_test.go b/pkg/apis/pipeline/v1beta1/pipelinerun_conversion_test.go
@@ -43,12 +43,14 @@ var (
 	childRefTaskRuns = []v1beta1.ChildStatusReference{{
 		TypeMeta:         runtime.TypeMeta{Kind: "TaskRun", APIVersion: "tekton.dev/v1beta1"},
 		Name:             "tr-0",
+		DisplayName:      "TR 0",
 		PipelineTaskName: "ptn",
 		WhenExpressions:  []v1beta1.WhenExpression{{Input: "default-value", Operator: "in", Values: []string{"val"}}},
 	}}
 	childRefRuns = []v1beta1.ChildStatusReference{{
 		TypeMeta:         runtime.TypeMeta{Kind: "Run", APIVersion: "tekton.dev/v1alpha1"},
 		Name:             "r-0",
+		DisplayName:      "R 0",
 		PipelineTaskName: "ptn-0",
 		WhenExpressions:  []v1beta1.WhenExpression{{Input: "default-value-0", Operator: "in", Values: []string{"val-0", "val-1"}}},
 	}}

diff --git a/pkg/apis/pipeline/v1beta1/pipelinerun_types.go b/pkg/apis/pipeline/v1beta1/pipelinerun_types.go
@@ -432,6 +432,9 @@ type ChildStatusReference struct {
 	runtime.TypeMeta `json:",inline"`
 	// Name is the name of the TaskRun or Run this is referencing.
 	Name string `json:"name,omitempty"`
+	// DisplayName is a user-facing name of the pipelineTask that may be
+	// used to populate a UI.
+	DisplayName string `json:"displayName,omitempty"`
 	// PipelineTaskName is the name of the PipelineTask this is referencing.
 	PipelineTaskName string `json:"pipelineTaskName,omitempty"`
 

diff --git a/pkg/apis/pipeline/v1beta1/swagger.json b/pkg/apis/pipeline/v1beta1/swagger.json
@@ -192,6 +192,10 @@
         "apiVersion": {
           "type": "string"
         },
+        "displayName": {
+          "description": "DisplayName is a user-facing name of the pipelineTask that may be used to populate a UI.",
+          "type": "string"
+        },
         "kind": {
           "type": "string"
         },