TEP-0048: default results

config/300-crds/300-pipelinerun.yaml

@@ -2360,6 +2360,8 @@ spec:
                           type: boolean
                         enableConciseResolverSyntax:
                           type: boolean
+                        enableDefaultResults:
+                          type: boolean
                         enableKeepPodOnCancel:
                           type: boolean
                         enableKubernetesSidecar:
@@ -2740,6 +2742,8 @@ spec:
                                     type: boolean
                                   enableConciseResolverSyntax:
                                     type: boolean
+                                  enableDefaultResults:
+                                    type: boolean
                                   enableKeepPodOnCancel:
                                     type: boolean
                                   enableKubernetesSidecar:
@@ -3013,6 +3017,8 @@ spec:
                                           type: boolean
                                         enableConciseResolverSyntax:
                                           type: boolean
+                                        enableDefaultResults:
+                                          type: boolean
                                         enableKeepPodOnCancel:
                                           type: boolean
                                         enableKubernetesSidecar:
@@ -5459,6 +5465,8 @@ spec:
                           type: boolean
                         enableConciseResolverSyntax:
                           type: boolean
+                        enableDefaultResults:
+                          type: boolean
                         enableKeepPodOnCancel:
                           type: boolean
                         enableKubernetesSidecar:

config/300-crds/300-task.yaml

@@ -192,6 +192,9 @@ spec:
                     required:
                       - name
                     properties:
+                      default:
+                        description: Default
+                        x-kubernetes-preserve-unknown-fields: true
                       description:
                         description: Description
                         type: string
@@ -4357,6 +4360,12 @@ spec:
                     required:
                       - name
                     properties:
+                      default:
+                        description: |-
+                          Default is the value a result takes if no actual value is produced by the task.
+                          If default is set, a task may be executed without producing the result and
+                          the default value will be used instead.
+                        x-kubernetes-preserve-unknown-fields: true
                       description:
                         description: Description is a human-readable description of the result
                         type: string

config/300-crds/300-taskrun.yaml

@@ -1875,6 +1875,8 @@ spec:
                           type: boolean
                         enableConciseResolverSyntax:
                           type: boolean
+                        enableDefaultResults:
+                          type: boolean
                         enableKeepPodOnCancel:
                           type: boolean
                         enableKubernetesSidecar:
@@ -2148,6 +2150,8 @@ spec:
                                 type: boolean
                               enableConciseResolverSyntax:
                                 type: boolean
+                              enableDefaultResults:
+                                type: boolean
                               enableKeepPodOnCancel:
                                 type: boolean
                               enableKubernetesSidecar:
@@ -4029,6 +4033,8 @@ spec:
                           type: boolean
                         enableConciseResolverSyntax:
                           type: boolean
+                        enableDefaultResults:
+                          type: boolean
                         enableKeepPodOnCancel:
                           type: boolean
                         enableKubernetesSidecar:
@@ -4294,6 +4300,8 @@ spec:
                                 type: boolean
                               enableConciseResolverSyntax:
                                 type: boolean
+                              enableDefaultResults:
+                                type: boolean
                               enableKeepPodOnCancel:
                                 type: boolean
                               enableKubernetesSidecar:
@@ -4512,6 +4520,12 @@ spec:
                         required:
                           - name
                         properties:
+                          default:
+                            description: |-
+                              Default is the value a result takes if no actual value is produced by the task.
+                              If default is set, a task may be executed without producing the result and
+                              the default value will be used instead.
+                            x-kubernetes-preserve-unknown-fields: true
                           description:
                             description: Description is a human-readable description of the result
                             type: string

config/config-feature-flags.yaml

@@ -120,6 +120,10 @@ data:
   enable-artifacts: "false"
   # Setting this flag to "true" will enable the built-in param input validation via param enum.
   enable-param-enum: "false"
+  # Setting this flag to "true" will enable default values for task results.
+  # When enabled, tasks can define default values for results that will be used
+  # if the task doesn't produce the result. This is an alpha feature.
+  enable-default-results: "false"
   # Setting this flag to "pipeline,pipelinerun,taskrun" will prevent users from creating
   # embedded spec Taskruns or Pipelineruns for Pipeline, Pipelinerun and taskrun
   # respectively. We can specify "pipeline" to disable for Pipeline resource only.

docs/pipeline-api.md

@@ -1412,6 +1412,7 @@ _Appears in:_
 | `type` _[ResultsType](#resultstype)_ | Type is the user-specified type of the result. The possible type<br />is currently "string" and will support "array" in following work. |  | Optional: \{\} <br /> |
 | `properties` _object (keys:string, values:[PropertySpec](#propertyspec))_ | Properties is the JSON Schema properties to support key-value pairs results. |  | Optional: \{\} <br /> |
 | `description` _string_ | Description is a human-readable description of the result |  | Optional: \{\} <br /> |
+| `default` _[ResultValue](#resultvalue)_ | Default is the value a result takes if no actual value is produced by the task.<br />If default is set, a task may be executed without producing the result and<br />the default value will be used instead. |  | Schemaless: \{\} <br />Optional: \{\} <br /> |
 | `value` _[ResultValue](#resultvalue)_ | Value the expression used to retrieve the value of the result from an underlying Step. |  | Schemaless: \{\} <br />Optional: \{\} <br /> |
 
 
@@ -3871,6 +3872,7 @@ _Appears in:_
 | `type` _[ResultsType](#resultstype)_ | Type is the user-specified type of the result. The possible type<br />is currently "string" and will support "array" in following work. |  | Optional: \{\} <br /> |
 | `properties` _object (keys:string, values:[PropertySpec](#propertyspec))_ | Properties is the JSON Schema properties to support key-value pairs results. |  | Optional: \{\} <br /> |
 | `description` _string_ | Description is a human-readable description of the result |  | Optional: \{\} <br /> |
+| `default` _[ResultValue](#resultvalue)_ | Default is the value a result takes if no actual value is produced by the task.<br />If default is set, a task may be executed without producing the result and<br />the default value will be used instead. |  | Schemaless: \{\} <br />Optional: \{\} <br /> |
 | `value` _[ResultValue](#resultvalue)_ | Value the expression used to retrieve the value of the result from an underlying Step. |  | Schemaless: \{\} <br />Optional: \{\} <br /> |
 
 

docs/tasks.md

@@ -25,6 +25,7 @@ weight: 201
   - [Specifying `Workspaces`](#specifying-workspaces)
   - [Emitting `Results`](#emitting-results)
     - [Larger `Results` using sidecar logs](#larger-results-using-sidecar-logs)
+    - [Default Value](#default-value)
   - [Specifying `Volumes`](#specifying-volumes)
   - [Specifying a `Step` template](#specifying-a-step-template)
   - [Specifying `Sidecars`](#specifying-sidecars)
@@ -1059,6 +1060,91 @@ leading to bad user experience.
 Refer to the detailed instructions listed in [additional config](additional-configs.md#enabling-larger-results-using-sidecar-logs)
 to learn how to enable this feature.
 
+#### Default Value
+
+This is an alpha feature guarded behind its own feature flag.  The `enable-default-results` feature flag must be set to
+`true` to use default values for results.
+
+Result declarations (within Tasks and Pipelines) can include default values that are used if the Result is not produced.
+This allows you to specify defaults for `string`, `array`, and `object` results.
+
+##### `string` type
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: task-with-default-string-result
+spec:
+  results:
+  - name: branch
+    type: string
+    default: main
+```
+
+##### `array` type
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: task-with-default-array-result
+spec:
+  results:
+  - name: tags
+    type: array
+    default:
+    - latest
+    - v2.0
+    - v1.0
+```
+
+##### `object` type
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: task-with-default-object-result
+spec:
+  results:
+  - name: image
+    type: object
+    properties:
+      url:
+        type: string
+      digest:
+        type: string
+    default:
+      url: cr.io/foo/bar
+      digest: sha256:abc123
+```
+
+For a more detailed example showing how default results are defined, see the [pipelinerun-with-default-results.yaml](../examples/v1/pipelineruns/alpha/pipelinerun-with-default-results.yaml).
+
+**Note:** If a Task does not specify a default value for a particular `Result` and fails to emit that `Result`, the
+associated `TaskRun` will be marked as Failed, as described in
+[TEP-0048](https://github.com/tektoncd/community/blob/main/teps/0048-task-results-without-results.md).
+Below is an example where the `taskRun` fails because one of the results was not produced:
+
+```yaml
+apiVersion: tekton.dev/v1
+kind: TaskRun
+metadata:
+  generateName: test-tr-
+spec:
+  taskSpec:
+    results:
+      - name: result1
+        description: will be produced
+      - name: result2
+        description: will not be produced
+    steps:
+      - name: failing-step
+        image: busybox
+        script: "echo -n 123 | tee $(results.result1.path)"
+```
+
 ### Specifying Volumes
 
 Specifies one or more [`Volumes`](https://kubernetes.io/docs/concepts/storage/volumes/) that the `Steps` in your

examples/v1/pipelineruns/alpha/pipelinerun-emitting-default-results.yaml

@@ -0,0 +1,96 @@
+apiVersion: tekton.dev/v1
+kind: PipelineRun
+metadata:
+  generateName: pipelinerun-emit-default-results-
+spec:
+  pipelineSpec:
+    tasks:
+      - name: task1
+        taskSpec:
+          results:
+            - name: array-results
+              type: array
+              description: The array results
+              default:
+                - "1"
+                - "2"
+                - "3"
+          steps:
+            - name: write-array
+              image: bash:latest
+              script: |
+                #!/usr/bin/env bash
+                echo -n "this script won't emit array result"
+      - name: task2
+        taskSpec:
+          results:
+            - name: object-results
+              type: object
+              description: The object results
+              properties:
+                foo: {type: string}
+                hello: {type: string}
+              default:
+                foo: bar
+                hello: world
+          steps:
+            - name: write-array
+              image: bash:latest
+              script: |
+                #!/usr/bin/env bash
+                echo -n "this script won't emit object result"
+      - name: task3
+        # task3 is skipped because the when expression is never satisfied.
+        # The string-result declared below is never written by the step, so the
+        # pipeline result that references it is populated with the declared default.
+        when:
+          - input: "foo"
+            operator: in
+            values: ["bar"]
+        taskSpec:
+          results:
+            - name: string-result
+              type: string
+              description: The string result
+              default: "default-string-value"
+          steps:
+            - name: write-string
+              image: bash:latest
+              script: |
+                #!/usr/bin/env bash
+                echo -n "this step is skipped and won't emit string result"
+    results:
+      - name: array-results
+        type: array
+        description: whole array
+        value: $(tasks.task1.results.array-results[*])
+      - name: array-results-from-array-indexing-and-object-elements
+        type: array
+        description: whole array
+        value:
+          [
+            "$(tasks.task1.results.array-results[0])",
+            "$(tasks.task2.results.object-results.foo)",
+          ]
+      - name: array-indexing-results
+        type: string
+        description: array element
+        value: $(tasks.task1.results.array-results[1])
+      - name: object-results
+        type: object
+        description: whole object
+        value: $(tasks.task2.results.object-results[*])
+      - name: object-results-from-array-indexing-and-object-elements
+        type: object
+        description: whole object
+        value:
+          key1: $(tasks.task1.results.array-results[1])
+          key2: $(tasks.task2.results.object-results.hello)
+      - name: object-element
+        type: string
+        description: object element
+        value: $(tasks.task2.results.object-results.foo)
+      - name: string-result-from-skipped-task
+        type: string
+        description: string result from skipped task3, populated with the declared default
+        value: $(tasks.task3.results.string-result)