Pipeline conditions

2 minute readDeveloper productivity

Pipeline runs can start or end at any point as well as skip a specific stage, task, or gate using Run if and Wait until conditions. You can also control behavior of triggering pipelines in a pipeline hierarchy with wait dependencies.

In the UI, you can set run the Run if and Wait until conditions and on pipeline stages, tasks, and gates.

You can also set the Run if and Wait until conditions on pipeline stages, tasks, and gates using API commands through the command-line interface or through the DSL IDE while authoring pipelines.

  • A Run if (run condition) is a property reference that the pipeline evaluates before executing the next stage, task, or approval gate. The pipeline waits until one or more dependent run conditions are met.

    In an API command, this condition is "fixed text" or text embedding property references that are evaluated into a logical TRUE or FALSE. A \"0\" or \"false\" is interpreted as FALSE. An empty string or any other result is interpreted as TRUE. By default, this condition is not set and is FALSE. The property reference can be a JavaScript expression. For example, this expression could test whether the name of a step is equal to the value of a property called "restartStep": $[/javascript (myStep.stepName == myJob.restartStep)].

  • A Wait until condition (precondition or wait condition) allows you to create a stage, task, or gate that waits until one or more dependent conditions are met. When the pipeline status is eligible to transition from pending to runnable, this condition is evaluated.

    In an API command, this condition is fixed text or text embedding a property reference that is evaluated to TRUE or FALSE. An empty string, a \"0\" or \"false\" is interpreted as FALSE. Any other result string is interpreted as TRUE. The pipeline does not progress until the condition is TRUE. By default, this condition is not set and is FALSE.

    You cannot use timestamps in preconditions on any object that supports preconditions. This includes stages, gates, and tasks as well as procedures and process steps.

    CloudBees recommends that you do not use /increment when setting preconditions for pipeline objects or procedures.

You can use Run if and Wait until conditions to:

  • Control a stage task based on the previous task.

  • Skip some pipeline states based on some specific conditions, such as if a Linux installer file was not successfully built, tested, and verified.

  • Execute certain approvals only if certain conditions are met. For example, during a functional test suite, the pipeline meets a rule or gate approval criteria if 90% of the functional tests have passed. If not, the pipeline waits for manual approval by assigned users before it can proceed.

For examples of how to set Run if and Wait until conditions on pipeline objects, refer to Pipeline objects and conditions.