Adding pipeline results

docs/developers/README.md

@@ -280,3 +280,52 @@ status:
 ```
 
 Instead of hardcoding the path to the result file, the user can also use a variable. So `/tekton/results/current-date-unix-timestamp` can be replaced with: `$(results.current-date-unix-timestamp.path)`. This is more flexible if the path to result files ever changes.
+
+## How task results can be used in pipeline's tasks
+
+Now that we have tasks that can return a result, the user can refer to a task result in a pipeline by using the syntax
+`$(tasks.<task name>.results.<result name>)`. This will substitute the task result at the location of the variable.
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: Pipeline
+metadata:
+  name: sum-and-multiply-pipeline
+    #...
+  tasks:
+    - name: sum-inputs
+    #...
+    - name: multiply-inputs
+    #...
+- name: sum-and-multiply
+      taskRef:
+        name: sum
+      params:
+        - name: a
+          value: "$(tasks.multiply-inputs.results.product)$(tasks.sum-inputs.results.sum)"
+        - name: b
+          value: "$(tasks.multiply-inputs.results.product)$(tasks.sum-inputs.results.sum)"
+```
+
+This results in:
+
+```shell
+tkn pipeline start sum-and-multiply-pipeline
+? Value for param `a` of type `string`? (Default is `1`) 10
+? Value for param `b` of type `string`? (Default is `1`) 15
+Pipelinerun started: sum-and-multiply-pipeline-run-rgd9j
+
+In order to track the pipelinerun progress run:
+tkn pipelinerun logs sum-and-multiply-pipeline-run-rgd9j -f -n default
+```
+
+```shell
+tkn pipelinerun logs sum-and-multiply-pipeline-run-rgd9j -f -n default
+[multiply-inputs : product] 150
+
+[sum-inputs : sum] 25
+
+[sum-and-multiply : sum] 30050
+```
+
+As you can see, you can define multiple tasks in the same pipeline and use the result of more than one task inside another task parameter. The substitution is only done inside `pipeline.spec.tasks[].params[]`. For a complete example demonstrating Task Results in a Pipeline, see the [pipelinerun example](../examples/pipelineruns/task_results_example.yaml).

docs/pipelines.md

@@ -403,6 +403,22 @@ tasks:
       name: echo-hello
 ```
 
+### Results
+
+Tasks can declare [results](./tasks.md#results) that they will emit during their execution. These results can be used as values for params in subsequent tasks of a Pipeline. Tekton will infer the ordering of these Tasks to ensure that the Task emitting the results runs before the Task consuming those results in its parameters.
+
+Using a Task result as a value for another Task's parameter is done with variable substitution. Here is what a Pipeline Task's param looks like with a result wired into it:
+
+```yaml
+params:
+  - name: foo
+    value: "$(tasks.previous-task-name.results.bar-result)"
+```
+
+In this example the previous pipeline task has name "previous-task-name" and its result is declared in the Task definition as having name "bar-result".
+
+For a complete example demonstrating Task Results in a Pipeline see the [pipelinerun example](../examples/pipelineruns/task_results_example.yaml).
+
 ## Ordering
 
 The [Pipeline Tasks](#pipeline-tasks) in a `Pipeline` can be connected and run

examples/pipelineruns/task_results_example.yaml

@@ -0,0 +1,93 @@
+apiVersion: tekton.dev/v1alpha1
+kind: Pipeline
+metadata:
+  name: sum-and-multiply-pipeline
+spec:
+  params:
+    - name: a
+      type: string
+      default: "1"
+    - name: b
+      type: string
+      default: "1"
+  tasks:
+    - name: sum-inputs
+      taskRef:
+        name: sum
+      params:
+        - name: a
+          value: "$(params.a)"
+        - name: b
+          value: "$(params.b)"
+    - name: multiply-inputs
+      taskRef:
+        name: multiply
+      params:
+        - name: a
+          value: "$(params.a)"
+        - name: b
+          value: "$(params.b)"
+    - name: sum-and-multiply
+      taskRef:
+        name: sum
+      params:
+        - name: a
+          value: "$(tasks.multiply-inputs.results.product)$(tasks.sum-inputs.results.sum)"
+        - name: b
+          value: "$(tasks.multiply-inputs.results.product)$(tasks.sum-inputs.results.sum)"
+---
+apiVersion: tekton.dev/v1alpha1
+kind: Task
+metadata:
+  name: sum
+  annotations:
+    description: |
+      A simple task that sums the two provided integers
+spec:
+  inputs:
+    params:
+      - name: a
+        type: string
+        default: "1"
+        description: The first integer
+      - name: b
+        type: string
+        default: "1"
+        description: The second integer
+  results:
+    - name: sum
+      description: The sum of the two provided integers
+  steps:
+    - name: sum
+      image: bash:latest
+      script: |
+        #!/usr/bin/env bash
+        echo -n $(( "$(inputs.params.a)" + "$(inputs.params.b)" )) | tee $(results.sum.path)
+---
+apiVersion: tekton.dev/v1alpha1
+kind: Task
+metadata:
+  name: multiply
+  annotations:
+    description: |
+      A simple task that multiplies the two provided integers
+spec:
+  inputs:
+    params:
+      - name: a
+        type: string
+        default: "1"
+        description: The first integer
+      - name: b
+        type: string
+        default: "1"
+        description: The second integer
+  results:
+    - name: product
+      description: The product of the two provided integers
+  steps:
+    - name: product
+      image: bash:latest
+      script: |
+        #!/usr/bin/env bash
+        echo -n $(( "$(inputs.params.a)" * "$(inputs.params.b)" )) | tee $(results.product.path)