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