Skip to content

Commit ac36195

Browse files
committed
Improve documentation about guarding Task execution using Conditions
As noted in #2635, it is not very clear what a Condition is in the context of a Pipeline. And it is not clear how they work or what happens after. This commit use the concept with "Guards" to explain how to guard Task execution within a Pipeline using Condition resources. An example showing the flow when a Condition is not successfully evaluated is also added. /kind documentation
1 parent 1fbac2a commit ac36195

File tree

1 file changed

+32
-20
lines changed

1 file changed

+32
-20
lines changed

docs/pipelines.md

Lines changed: 32 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ weight: 3
1515
- [Using the `from` parameter](#using-the-from-parameter)
1616
- [Using the `runAfter` parameter](#using-the-runafter-parameter)
1717
- [Using the `retries` parameter](#using-the-retries-parameter)
18-
- [Specifying execution `Conditions`](#specifying-execution-conditions)
18+
- [Guard `Task` execution using `Conditions`](#guard-task-execution-using-conditions)
1919
- [Configuring the failure timeout](#configuring-the-failure-timeout)
2020
- [Configuring execution results at the `Task` level](#configuring-execution-results-at-the-task-level)
2121
- [Configuring execution results at the `Pipeline` level](#configuring-execution-results-at-the-pipeline-level)
@@ -55,8 +55,8 @@ A `Pipeline` definition supports the following fields:
5555
should execute after one or more other `Tasks` without output linking.
5656
- [`retries`](#using-the-retries-parameter) - Specifies the number of times to retry the
5757
execution of a `Task` after a failure. Does not apply to execution cancellations.
58-
- [`conditions`](#specifying-execution-conditions) - Specifies `Conditions` that only allow a `Task`
59-
to execute if they evaluate to `true`.
58+
- [`conditions`](#guard-task-execution-using-conditions) - Specifies `Conditions` that only allow a `Task`
59+
to execute if they successfully evaluate.
6060
- [`timeout`](#configuring-the-failure-timeout) - Specifies the timeout before a `Task` fails.
6161
- [`results`](#configuring-execution-results-at-the-pipeline-level) - Specifies the location to which
6262
the `Pipeline` emits its execution results.
@@ -312,32 +312,44 @@ tasks:
312312
name: build-push
313313
```
314314

315-
### Specifying execution `Conditions`
315+
### Guard `Task` execution using `Conditions`
316316

317-
Sometimes you will need to run tasks only when some conditions are true. The `conditions` field
318-
allows you to list a series of references to [`Conditions`](./conditions.md) that are run before the task
319-
is run. If all of the conditions evaluate to true, the task is run. If any of the conditions are false,
320-
the Task is not run. Its status.ConditionSucceeded is set to False with the reason set to `ConditionCheckFailed`.
321-
However, unlike regular task failures, condition failures do not automatically fail the entire pipeline
322-
run -- other tasks that are not dependent on the task (via `from` or `runAfter`) are still run.
317+
To run a `Task` only when certain conditions are met, it is possible to _guard_ task execution using
318+
the `conditions` field. The `conditions` field allows you to list a series of references to
319+
[`Condition`](./conditions.md) resources. The declared `Conditions` are run before the `Task` is run.
320+
If all of the conditions successfully evaluate, the `Task` is run. If any of the conditions fails,
321+
the `Task` is not run and the `TaskRun` status field `ConditionSucceeded` is set to `False` with the
322+
reason set to `ConditionCheckFailed`.
323+
324+
In this example, `is-master-branch` refers to a [Condition](conditions.md) resource. The `deploy`
325+
task will only be executed if the condition successfully evaluates.
323326

324327
```yaml
325328
tasks:
326-
- name: conditional-task
327-
taskRef:
328-
name: build-push
329+
- name: deploy-if-branch-is-master
329330
conditions:
330-
- conditionRef: my-condition
331+
- conditionRef: is-master-branch
331332
params:
332-
- name: my-param
333+
- name: branch-name
333334
value: my-value
334-
resources:
335-
- name: workspace
336-
resource: source-repo
335+
taskRef:
336+
name: deploy
337337
```
338338

339-
In this example, `my-condition` refers to a [Condition](conditions.md) custom resource. The `build-push`
340-
task will only be executed if the condition evaluates to true.
339+
Unlike regular task failures, condition failures do not automatically fail the entire `PipelineRun` --
340+
other tasks that are **not dependent** on the `Task` (via `from` or `runAfter`) are still run.
341+
342+
In this example, `(task C)` has a `condition` set to _guard_ its execution. If the condition
343+
is **not** successfully evaluated, task `(task D)` will not be run, but all other tasks in the pipeline
344+
that not depend on `(task C)` will be executed and the `PipelineRun` will successfully complete.
345+
346+
```
347+
(task B) — (task E)
348+
/
349+
(task A)
350+
\
351+
(guarded task C) — (task D)
352+
```
341353
342354
Resources in conditions can also use the [`from`](#using-the-from-parameter) field to indicate that they
343355
expect the output of a previous task as input. As with regular Pipeline Tasks, using `from`

0 commit comments

Comments
 (0)