@@ -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
325328tasks:
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
342354Resources in conditions can also use the [`from`](#using-the-from-parameter) field to indicate that they
343355expect the output of a previous task as input. As with regular Pipeline Tasks, using `from`
0 commit comments