About Conditions in Pipelines

A pipeline can include advanced orchestration logic, such as conditions.

There are two types of conditions:

pipeline conditions on status

Condition on statuses

Allows you to add conditions on the status of the jobs.

pipeline conditions on envvar

Condition on environment variables

Allows you to add conditions on environment variables.

Conditions do not override the initial behavior of the pipeline. As a reminder:

The status of a pipeline is Succeeded when all its jobs have been successfully executed or skipped.
The status of a pipeline is Failed as soon as one of its jobs has failed.
Jobs that follow a failed job are always Skipped.

Conditions on Statuses

Status conditions allow you to set more complex conditions on the status of your jobs.

When creating a condition on the job status, you can modify it and choose between three behaviors:

All input jobs succeeded: All input jobs have been successfully executed.
All input jobs succeeded or have been skipped: All input jobs have been successfully executed or skipped.
At least one input job succeeded: At least one input job has been successfully executed.

By default, the condition is set to the option All input jobs succeeded or have been skipped.

Regardless of the behavior chosen, a condition on a job status must have at least one successful job in its input to succeed. In this way, the rules for the condition on job statuses are as follows:

All Input Jobs Succeeded

pipeline status conditions all success 4

pipeline status conditions all success 1

pipeline status conditions all success 2

pipeline status conditions all success 3

→ All other input jobs must be in Succeeded for the condition to be met.

All Input Jobs Succeeded or Have Been Skipped

pipeline status conditions all success or skipped 4

pipeline status conditions all success or skipped 1

pipeline status conditions all success or skipped 2

pipeline status conditions all success or skipped 3

pipeline status conditions all success or skipped 5

→ All other input jobs must be in Succeeded or Skipped for the condition to be met.

At Least One Input Job Succeeded

pipeline status conditions at least one success 4

pipeline status conditions at least one success 1

pipeline status conditions at least one success 2

pipeline status conditions at least one success 3

→ All other input jobs can be in Succeeded, Skipped, or Failed for the condition to be met.

Conditions on Environment Variables

Conditions on environment variables allow you to set more complex conditions on existing and dynamic environment variables.

Expression and Expected Result

Conditions on environment variables are based on the CEL language. The only constraint for the expression defining your condition, is to return a Boolean value, either true or false. This result will define the condition as Succeeded if the Boolean returns true or as Failed if the Boolean returns false.

In other words, the only rule to evaluate a condition on environment variables is to have at least one parent job Succeeded or Failed.

The branches after the condition will be executed according to this result, as usual.

Figure 1. Condition on environment variables returning the Boolean true, and therefore the status Succeeded on the condition.

Figure 2. Condition on environment variables returning the Boolean false, and therefore the status Failed on the condition.

The Life Cycle of a Condition

Conditions have a life cycle similar to that of Saagie jobs, and can go through the following statuses:

Awaiting

pipeline status conditions lifecycle awaiting

Queued

pipeline status conditions lifecycle queued

Running

pipeline status conditions lifecycle running

Stopping

pipeline status conditions lifecycle stopping

Succeeded

pipeline status conditions lifecycle succeeded

Failed

pipeline status conditions lifecycle failed

Error

pipeline status conditions lifecycle error

Skipped

pipeline status conditions lifecycle skipped

Stopped

pipeline status conditions lifecycle stopped

Even in the case of manual pipeline shutdown, due to the execution time, the condition evaluation is usually completed before the stop order is received.

Syntax Validation

Your syntax condition is checked before saving. If there are syntax errors, warning message(s) appear with details about the error(s).

Hover over the condition in error to display the error message(s).

pipeline conditions on envvar syntax error message

Expression Validation

A condition will be in Error if it encounters a technical problem during its evaluation or if its expression cannot be evaluated correctly.

For example, an expression may be invalid because the CEL functions used, or the types manipulated are incorrect, or because the variables used do not exist or are not accessible in the condition.

pipeline conditions on envvar validation error message

You can use your Saagie platform’s GraphQL API to retrieve the logs of the instance of the condition(s) in error.

CEL Language

The possibilities of the CEL language combined with the variables available in your pipelines give you multiple ways to condition your branches. You can use Boolean logic and various basic CEL functions such as :

Comparison operators: >, <, >=, =<, ==, !=
Logical AND and OR: &&, ||
Mathematical operations: +, -, *, /
Conversion type operations
Functions on durations and timestamps
Collection manipulation functions

The variables used in the conditions are environment variables. By nature, they are not typed and are all strings. Do not forget to convert them to the required type if needed. For more information, see the List of Standard Definitions for CEL.

Example 1. Expressing the current date

The expression now() returns the current date and a google.protobuf.Timestamp type, allowing you to use CEL methods on timestamps, such as now().getDayOfMonth() < 15. This expression will be true if the current date is below 15.

See the Expression in Read-Only Mode

You can view the condition expression in read-only mode by clicking the condition, then settings env vars a See expression. A side panel is displayed with your expression and the number of jobs linked to the condition when it becomes Succeeded or Failed.

pipeline conditions on envvar read only mode

Usable Variables

You can use all the existing scopes of environment variables, that is, project, global, and pipeline environment variables.

In addition, if your pipeline has the settings env vars Variables setting enabled, you will be able to use dynamic variables, that is, output variables modified or created in the jobs preceding the condition, as follows:

VARIABLE_NAME: Corresponds to the last value written by the previous job.
INIT_VARIABLE_NAME: Corresponds to the pipeline initialization value, that is, the value of the corresponding environment variable readable by the pipeline.
jobAlias_VARIABLE_NAME: Corresponds to the output value written by the job referenced by the job alias.

Variables will be retrieved by the condition during pipeline execution. You can view a summary table of all the input variables for the condition. Click See Variables from the context menu of the condition to display the table.

pipeline conditions on envvar summary table

The summary table is only available if the Variables setting is enabled for the pipeline. If disabled, dynamic transfer of variables during pipeline execution is not allowed.
A condition cannot create output variables.