diff --git a/docs/pipelines.md b/docs/pipelines.md
index 1cf7ba2d85f..78b161b493b 100644
--- a/docs/pipelines.md
+++ b/docs/pipelines.md
@@ -590,9 +590,13 @@ tasks:
To run a `Task` only when certain conditions are met, it is possible to _guard_ task execution using the `when` field. The `when` field allows you to list a series of references to `when` expressions.
The components of `when` expressions are `input`, `operator` and `values`:
-- `input` is the input for the `when` expression which can be static inputs or variables ([`Parameters`](#specifying-parameters) or [`Results`](#using-results)). If the `input` is not provided, it defaults to an empty string.
-- `operator` represents an `input`'s relationship to a set of `values`. A valid `operator` must be provided, which can be either `in` or `notin`.
-- `values` is an array of string values. The `values` array must be provided and be non-empty. It can contain static values or variables ([`Parameters`](#specifying-parameters), [`Results`](#using-results) or [a Workspaces's `bound` state](#specifying-workspaces)).
+
+| Component | Description | Syntax |
+|------------|------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `input` | Input for the `when` expression, defaults to an empty string if not provided. | * Static values e.g. `"ubuntu"`
* Variables ([parameters](#specifying-parameters) or [results](#using-results)) e.g. `"$(params.image)"` or `"$(tasks.task1.results.image)"` or `"$(tasks.task1.results.array-results[1])"` |
+| `operator` | `operator` represents an `input`'s relationship to a set of `values`, a valid `operator` must be provided. | `in` or `notin` |
+| `values` | An array of string values, the `values` array must be provided and has to be non-empty. | * An array param e.g. `["$(params.images[*])"]`
* An array result of a task `["$(tasks.task1.results.array-results[*])"]`
* `values` can contain static values e.g. `"ubuntu"`
* `values` can contain variables ([parameters](#specifying-parameters) or [results](#using-results)) or [a Workspaces's `bound` state](#specifying-workspaces) e.g. `["$(params.image)"]` or `["$(tasks.task1.results.image)"]` or `["$(tasks.task1.results.array-results[1])"]` |
+
The [`Parameters`](#specifying-parameters) are read from the `Pipeline` and [`Results`](#using-results) are read directly from previous [`Tasks`](#adding-tasks-to-the-pipeline). Using [`Results`](#using-results) in a `when` expression in a guarded `Task` introduces a resource dependency on the previous `Task` that produced the `Result`.
diff --git a/examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml b/examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml
new file mode 100644
index 00000000000..775b0d94b52
--- /dev/null
+++ b/examples/v1beta1/pipelineruns/alpha/pipeline-with-when-expressions-using-array-results.yaml
@@ -0,0 +1,107 @@
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun
+metadata:
+ generateName: pipelinerun-with-when-expressions-using-array-results-
+spec:
+ pipelineSpec:
+ params:
+ - name: images
+ type: array
+ description: The list of images
+ tasks:
+ - name: task1
+ taskSpec:
+ results:
+ # a list of images in array-result-1
+ - name: array-results-1
+ type: array
+ description: The array results
+ steps:
+ - name: write-array
+ image: bash:latest
+ script: |
+ #!/usr/bin/env bash
+ image1="abc.dev/notsofamousimage/image"
+ image2="ubuntu"
+ image3="xyz.dev/awesomeness/awesomeness"
+ echo -n "[\"$image1\", \"$image2\", \"$image3\"]" | tee $(results.array-results-1.path)
+ - name: task2
+ when:
+ # indexing into array results in input
+ - input: "$(tasks.task1.results.array-results-1[1])"
+ operator: in
+ values: ["ubuntu"]
+ taskSpec:
+ steps:
+ - name: say-hi
+ image: bash:latest
+ script: |
+ echo "hi"
+ - name: task3
+ when:
+ # indexing into array results in values
+ - input: "ubuntu"
+ operator: in
+ values: ["$(tasks.task1.results.array-results-1[1])"]
+ # indexing into array results in input and values
+ - input: "$(tasks.task1.results.array-results-1[2])"
+ operator: in
+ values: ["$(tasks.task1.results.array-results-1[2])"]
+ taskSpec:
+ steps:
+ - name: say-hello
+ image: bash:latest
+ script: |
+ echo "hello"
+ - name: task4
+ when:
+ # indexing into array results in input and using start notation in values
+ - input: "$(tasks.task1.results.array-results-1[1])"
+ operator: in
+ values: ["$(tasks.task1.results.array-results-1[*])"]
+ taskSpec:
+ steps:
+ - name: say-hi
+ image: bash:latest
+ script: |
+ echo "hi"
+ - name: task5
+ when:
+ # indexing into array result in input along with array param
+ - input: "$(tasks.task1.results.array-results-1[1])"
+ operator: notin
+ values: ["$(params.images[*])"]
+ taskSpec:
+ steps:
+ - name: do-not-execute
+ image: bash:latest
+ script: |
+ exit 1
+ finally:
+ - name: validate-tasks
+ taskSpec:
+ steps:
+ - name: validate-tasks-section
+ image: bash:latest
+ script: |
+ if [[ $(context.task2.status) != "Succeeded" ]]; then
+ echo "task2 should have been succeeded but instead has status - $(context.task2.status)"
+ exit 1
+ fi
+ if [[ $(context.task3.status) != "Succeeded" ]]; then
+ echo "task3 should have been succeeded but instead has status - $(context.task3.status)"
+ exit 1
+ fi
+ if [[ $(context.task4.status) != "Succeeded" ]]; then
+ echo "task3 should have been succeeded but instead has status - $(context.task4.status)"
+ exit 1
+ fi
+ if [[ $(context.task5.status) != "None" ]]; then
+ echo "task3 should have been succeeded but instead has status - $(context.task5.status)"
+ exit 1
+ fi
+ params:
+ - name: images
+ value:
+ - ubuntu
+ - alpine