parameterize displayName

Allow specifying parameters or task results in a displayName. Specifying task results in a displayName does not introduce a resource dependency. Pipeline authors have to specify resource dependency using runAfter or task params. Signed-off-by: Priti Desai <[email protected]>
tektoncd · Oct 26, 2023 · f78bcff · f78bcff
1 parent faf6044
commit f78bcff
Show file tree

Hide file tree

Showing 5 changed files with 221 additions and 78 deletions.
diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -13,6 +13,7 @@ weight: 203
   - [Specifying `Workspaces`](#specifying-workspaces)
   - [Specifying `Parameters`](#specifying-parameters)
   - [Adding `Tasks` to the `Pipeline`](#adding-tasks-to-the-pipeline)
+    - [Specifying Display Name](#specifying-displayname-in-pipelinetasks)
     - [Specifying Remote Tasks](#specifying-remote-tasks)
     - [Specifying `Pipelines` in `PipelineTasks`](#specifying-pipelines-in-pipelinetasks)
     - [Specifying `Parameters` in `PipelineTasks`](#specifying-parameters-in-pipelinetasks)
@@ -37,6 +38,7 @@ weight: 203
   - [Configuring the `Task` execution order](#configuring-the-task-execution-order)
   - [Adding a description](#adding-a-description)
   - [Adding `Finally` to the `Pipeline`](#adding-finally-to-the-pipeline)
+    - [Specifying Display Name](#specifying-displayname-in-finally-tasks)
     - [Specifying `Workspaces` in `finally` tasks](#specifying-workspaces-in-finally-tasks)
     - [Specifying `Parameters` in `finally` tasks](#specifying-parameters-in-finally-tasks)
     - [Specifying `matrix` in `finally` tasks](#specifying-matrix-in-finally-tasks)
@@ -90,7 +92,7 @@ A `Pipeline` definition supports the following fields:
   - [`workspaces`](#specifying-workspaces) - Specifies a set of Workspaces that the `Pipeline` requires.
   - [`tasks`](#adding-tasks-to-the-pipeline):
       - [`name`](#adding-tasks-to-the-pipeline) - the name of this `Task` within the context of this `Pipeline`.
-      - [`displayName`](#specifying-a-display-name) - a user-facing name of this `Task` within the context of this `Pipeline`.
+      - [`displayName`](#specifying-displayname-in-pipelinetasks) - a user-facing name of this `Task` within the context of this `Pipeline`.
       - [`description`](#adding-tasks-to-the-pipeline) - a description of this `Task` within the context of this `Pipeline`.
       - [`taskRef`](#adding-tasks-to-the-pipeline) - a reference to a `Task` definition.
       - [`taskSpec`](#adding-tasks-to-the-pipeline) - a specification of a `Task`.
@@ -112,7 +114,7 @@ A `Pipeline` definition supports the following fields:
   - [`finally`](#adding-finally-to-the-pipeline) - Specifies one or more `Tasks` to be executed in parallel after
     all other tasks have completed.
     - [`name`](#adding-finally-to-the-pipeline) - the name of this `Task` within the context of this `Pipeline`.
-    - [`displayName`](#specifying-a-display-name) - a user-facing name of this `Task` within the context of this `Pipeline`.
+    - [`displayName`](#specifying-displayname-in-finally-tasks) - a user-facing name of this `Task` within the context of this `Pipeline`.
     - [`description`](#adding-finally-to-the-pipeline) - a description of this `Task` within the context of this `Pipeline`.
     - [`taskRef`](#adding-finally-to-the-pipeline) - a reference to a `Task` definition.
     - [`taskSpec`](#adding-finally-to-the-pipeline) - a specification of a `Task`.
@@ -297,6 +299,43 @@ tasks:
 
 Note that any `task` specified in `taskSpec` will be the same version as the `Pipeline`.
 
+### Specifying `displayName` in `PipelineTasks`
+
+The `displayName` field is an optional field that allows you to add a user-facing name of the `PipelineTask` that can be
+used to populate and distinguish in the dashboard. For example:
+
+```yaml
+spec:
+  tasks:
+    - name: scan
+      displayName: "Code Scan"
+      taskRef:
+        name: sonar-scan
+```
+
+The `displayName` also allows you to parameterize the human-readable name of your choice based on the
+[params](#specifying-parameters), [the task results](#passing-one-tasks-results-into-the-parameters-or-when-expressions-of-another),
+and [the context variables](#context-variables). For example:
+
+```yaml
+spec:
+  params:
+    - name: application
+  tasks:
+    - name: scan
+      displayName: "Code Scan for $(params.application)"
+      taskRef:
+        name: sonar-scan
+    - name: upload-scan-report
+      displayName: "Upload Scan Report $(tasks.scan.results.report)"
+      taskRef:
+        name: upload
+```
+
+Specifying task results in the `displayName` does not introduce an inherent resource dependency among `tasks`. The
+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).
+
 ### Specifying Remote Tasks
 
 **([beta feature](https://github.com/tektoncd/pipeline/blob/main/docs/install.md#beta-features))**
@@ -1384,6 +1423,29 @@ spec:
         name: cleanup
 ```
 
+### Specifying `displayName` in `finally` tasks
+
+Similar to [specifying `displayName` in `pipelineTasks`](#specifying-displayname-in-pipelinetasks), `finally` tasks also
+allows to add a user-facing name of the `finally` task that can be used to populate and distinguish in the dashboard.
+For example:
+
+```yaml
+spec:
+  finally:
+    - name: notification
+      displayName: "Notify"
+      taskRef:
+        name: notification
+    - name: notification-using-context-variable
+      displayName: "Notification from $(context.pipeline.name)"
+      taskRef:
+        name: notification
+```
+
+The `displayName` also allows you to parameterize the human-readable name of your choice based on the
+[params](#specifying-parameters), [the task results](#consuming-task-execution-results-in-finally),
+and [the context variables](#context-variables).
+
 ### Specifying `Workspaces` in `finally` tasks
 
 `finally` tasks can specify [workspaces](workspaces.md) which `PipelineTasks` might have utilized

diff --git a/docs/variables.md b/docs/variables.md
@@ -75,54 +75,55 @@ For instructions on using variable substitutions see the relevant section of [th
 
 ## Fields that accept variable substitutions
 
-| CRD | Field |
-| --- | ----- |
-| `Task` | `spec.steps[].name` |
-| `Task` | `spec.steps[].image` |
-| `Task` | `spec.steps[].imagePullPolicy` |
-| `Task` | `spec.steps[].command` |
-| `Task` | `spec.steps[].args` |
-| `Task` | `spec.steps[].script` |
-| `Task` | `spec.steps[].onError` |
-| `Task` | `spec.steps[].env.value` |
-| `Task` | `spec.steps[].env.valuefrom.secretkeyref.name` |
-| `Task` | `spec.steps[].env.valuefrom.secretkeyref.key` |
-| `Task` | `spec.steps[].env.valuefrom.configmapkeyref.name` |
-| `Task` | `spec.steps[].env.valuefrom.configmapkeyref.key` |
-| `Task` | `spec.steps[].volumemounts.name` |
-| `Task` | `spec.steps[].volumemounts.mountpath` |
-| `Task` | `spec.steps[].volumemounts.subpath` |
-| `Task` | `spec.volumes[].name` |
-| `Task` | `spec.volumes[].configmap.name` |
-| `Task` | `spec.volumes[].configmap.items[].key` |
-| `Task` | `spec.volumes[].configmap.items[].path` |
-| `Task` | `spec.volumes[].secret.secretname` |
-| `Task` | `spec.volumes[].secret.items[].key` |
-| `Task` | `spec.volumes[].secret.items[].path` |
-| `Task` | `spec.volumes[].persistentvolumeclaim.claimname` |
-| `Task` | `spec.volumes[].projected.sources.configmap.name` |
-| `Task` | `spec.volumes[].projected.sources.secret.name` |
+| CRD | Field                                                           |
+| --- |-----------------------------------------------------------------|
+| `Task` | `spec.steps[].name`                                             |
+| `Task` | `spec.steps[].image`                                            |
+| `Task` | `spec.steps[].imagePullPolicy`                                  |
+| `Task` | `spec.steps[].command`                                          |
+| `Task` | `spec.steps[].args`                                             |
+| `Task` | `spec.steps[].script`                                           |
+| `Task` | `spec.steps[].onError`                                          |
+| `Task` | `spec.steps[].env.value`                                        |
+| `Task` | `spec.steps[].env.valuefrom.secretkeyref.name`                  |
+| `Task` | `spec.steps[].env.valuefrom.secretkeyref.key`                   |
+| `Task` | `spec.steps[].env.valuefrom.configmapkeyref.name`               |
+| `Task` | `spec.steps[].env.valuefrom.configmapkeyref.key`                |
+| `Task` | `spec.steps[].volumemounts.name`                                |
+| `Task` | `spec.steps[].volumemounts.mountpath`                           |
+| `Task` | `spec.steps[].volumemounts.subpath`                             |
+| `Task` | `spec.volumes[].name`                                           |
+| `Task` | `spec.volumes[].configmap.name`                                 |
+| `Task` | `spec.volumes[].configmap.items[].key`                          |
+| `Task` | `spec.volumes[].configmap.items[].path`                         |
+| `Task` | `spec.volumes[].secret.secretname`                              |
+| `Task` | `spec.volumes[].secret.items[].key`                             |
+| `Task` | `spec.volumes[].secret.items[].path`                            |
+| `Task` | `spec.volumes[].persistentvolumeclaim.claimname`                |
+| `Task` | `spec.volumes[].projected.sources.configmap.name`               |
+| `Task` | `spec.volumes[].projected.sources.secret.name`                  |
 | `Task` | `spec.volumes[].projected.sources.serviceaccounttoken.audience` |
-| `Task` | `spec.volumes[].csi.nodepublishsecretref.name` |
-| `Task` | `spec.volumes[].csi.volumeattributes.* `|
-| `Task` | `spec.sidecars[].name` |
-| `Task` | `spec.sidecars[].image` |
-| `Task` | `spec.sidecars[].imagePullPolicy` |
-| `Task` | `spec.sidecars[].env.value` |
-| `Task` | `spec.sidecars[].env.valuefrom.secretkeyref.name` |
-| `Task` | `spec.sidecars[].env.valuefrom.secretkeyref.key` |
-| `Task` | `spec.sidecars[].env.valuefrom.configmapkeyref.name` |
-| `Task` | `spec.sidecars[].env.valuefrom.configmapkeyref.key` |
-| `Task` | `spec.sidecars[].volumemounts.name` |
-| `Task` | `spec.sidecars[].volumemounts.mountpath` |
-| `Task` | `spec.sidecars[].volumemounts.subpath` |
-| `Task` | `spec.sidecars[].command` |
-| `Task` | `spec.sidecars[].args` |
-| `Task` | `spec.sidecars[].script` |
-| `Task` | `spec.workspaces[].mountPath` |
-| `Pipeline` | `spec.tasks[].params[].value` |
-| `Pipeline` | `spec.tasks[].conditions[].params[].value` |
-| `Pipeline` | `spec.results[].value` |
-| `Pipeline` | `spec.tasks[].when[].input` |
-| `Pipeline` | `spec.tasks[].when[].values` |
-| `Pipeline` | `spec.tasks[].workspaces[].subPath` |
+| `Task` | `spec.volumes[].csi.nodepublishsecretref.name`                  |
+| `Task` | `spec.volumes[].csi.volumeattributes.* `                        |
+| `Task` | `spec.sidecars[].name`                                          |
+| `Task` | `spec.sidecars[].image`                                         |
+| `Task` | `spec.sidecars[].imagePullPolicy`                               |
+| `Task` | `spec.sidecars[].env.value`                                     |
+| `Task` | `spec.sidecars[].env.valuefrom.secretkeyref.name`               |
+| `Task` | `spec.sidecars[].env.valuefrom.secretkeyref.key`                |
+| `Task` | `spec.sidecars[].env.valuefrom.configmapkeyref.name`            |
+| `Task` | `spec.sidecars[].env.valuefrom.configmapkeyref.key`             |
+| `Task` | `spec.sidecars[].volumemounts.name`                             |
+| `Task` | `spec.sidecars[].volumemounts.mountpath`                        |
+| `Task` | `spec.sidecars[].volumemounts.subpath`                          |
+| `Task` | `spec.sidecars[].command`                                       |
+| `Task` | `spec.sidecars[].args`                                          |
+| `Task` | `spec.sidecars[].script`                                        |
+| `Task` | `spec.workspaces[].mountPath`                                   |
+| `Pipeline` | `spec.tasks[].params[].value`                                   |
+| `Pipeline` | `spec.tasks[].conditions[].params[].value`                      |
+| `Pipeline` | `spec.results[].value`                                          |
+| `Pipeline` | `spec.tasks[].when[].input`                                     |
+| `Pipeline` | `spec.tasks[].when[].values`                                    |
+| `Pipeline` | `spec.tasks[].workspaces[].subPath`                             |
+| `Pipeline` | `spec.tasks[].displayName`                                      |
diff --git a/examples/v1/pipelineruns/pipeline-with-displayname.yaml b/examples/v1/pipelineruns/pipeline-with-displayname.yaml
@@ -42,7 +42,7 @@ spec:
       default: "1"
   tasks:
     - name: sum-two-numbers
-      displayName: Calculate the first two numbers
+      displayName: "Calculate the first two numbers $(params.a) + $(params.b)"
       description: Calculate the sum of the first two numbers
       taskRef:
         name: sum
@@ -52,7 +52,7 @@ spec:
         - name: b
           value: "$(params.b)"
     - name: sum-with-third-number
-      displayName: Sum with the third number
+      displayName: "Sum with the third number - $(tasks.sum-two-numbers.results.sum) + $(params.c)"
       description: Calculate the sum of the first two numbers and the third number
       taskRef:
         name: sum
@@ -81,7 +81,7 @@ spec:
 apiVersion: tekton.dev/v1
 kind: PipelineRun
 metadata:
-  name: sum
+  generateName: sum-
 spec:
   params:
     - name: a

diff --git a/pkg/reconciler/pipelinerun/resources/apply.go b/pkg/reconciler/pipelinerun/resources/apply.go
@@ -218,6 +218,7 @@ func ApplyPipelineTaskContexts(pt *v1.PipelineTask, pipelineRunStatus v1.Pipelin
 			pt.Matrix.Include[i].Params = pt.Matrix.Include[i].Params.ReplaceVariables(replacements, map[string][]string{}, map[string]map[string]string{})
 		}
 	}
+	pt.DisplayName = substitution.ApplyReplacements(pt.DisplayName, replacements)
 	return pt
 }
 
@@ -244,6 +245,7 @@ func ApplyTaskResults(targets PipelineRunState, resolvedResultRefs ResolvedResul
 			if pipelineTask.TaskRef != nil && pipelineTask.TaskRef.Params != nil {
 				pipelineTask.TaskRef.Params = pipelineTask.TaskRef.Params.ReplaceVariables(stringReplacements, arrayReplacements, objectReplacements)
 			}
+			pipelineTask.DisplayName = substitution.ApplyReplacements(pipelineTask.DisplayName, stringReplacements)
 			resolvedPipelineRunTask.PipelineTask = pipelineTask
 		}
 	}
@@ -259,6 +261,7 @@ func ApplyPipelineTaskStateContext(state PipelineRunState, replacements map[stri
 			if pipelineTask.TaskRef != nil && pipelineTask.TaskRef.Params != nil {
 				pipelineTask.TaskRef.Params = pipelineTask.TaskRef.Params.ReplaceVariables(replacements, nil, nil)
 			}
+			pipelineTask.DisplayName = substitution.ApplyReplacements(pipelineTask.DisplayName, replacements)
 			resolvedPipelineRunTask.PipelineTask = pipelineTask
 		}
 	}
@@ -299,6 +302,7 @@ func ApplyReplacements(p *v1.PipelineSpec, replacements map[string]string, array
 		if p.Tasks[i].TaskRef != nil && p.Tasks[i].TaskRef.Params != nil {
 			p.Tasks[i].TaskRef.Params = p.Tasks[i].TaskRef.Params.ReplaceVariables(replacements, arrayReplacements, objectReplacements)
 		}
+		p.Tasks[i].DisplayName = substitution.ApplyReplacements(p.Tasks[i].DisplayName, replacements)
 		p.Tasks[i] = propagateParams(p.Tasks[i], replacements, arrayReplacements, objectReplacements)
 	}
 
@@ -317,6 +321,7 @@ func ApplyReplacements(p *v1.PipelineSpec, replacements map[string]string, array
 		if p.Finally[i].TaskRef != nil && p.Finally[i].TaskRef.Params != nil {
 			p.Finally[i].TaskRef.Params = p.Finally[i].TaskRef.Params.ReplaceVariables(replacements, arrayReplacements, objectReplacements)
 		}
+		p.Finally[i].DisplayName = substitution.ApplyReplacements(p.Finally[i].DisplayName, replacements)
 		p.Finally[i] = propagateParams(p.Finally[i], replacements, arrayReplacements, objectReplacements)
 	}