Cloud costs
March 8, 2022
min read

Using the "When" Directive and Built-in Variables in CI for Conditional Execution


The "when" directive enables Pipelines to determine whether a step or a stage should be executed depending on a given condition.

Why is it needed?

Let’s say we need to build a pipeline that executes the following logic:

  1. Build and push an image of an application
  2. Run integration tests to test the application is working properly // Only for Pull Requests
  3. Create a Jira ticket // Only if a failure occurred during the execution

This is a very common use case.

When building, testing, and pushing applications, users often need to run/skip steps and stages based on the type of build. Some variations in the pipeline logic might be needed when pushing to feature branches, when changing a PR, or when building a Tag. 

The way to achieve this is by using the “when” directive. The “when” directive allows the user to set:

  1. Status-based condition: Execute based on the status of the step/stage - on success (default behavior), always, or on failure.
  2. JEXL condition: User can set additional conditions on top of the status. 

For example, a stage with the conditions configured as below, will run only for Pull Request builds if errors have not occurred prior to that stage execution.  

"When" Directive Example - PR Builds

In the pipeline YAML, the condition would look like this:

pipelineStatus: Success
condition: <> == "PR"

In the example above, we are combining the “when” directive with built-in variables. You can also use the JEXL condition with other variables, such as pipeline variables, stage variables, and step output variables, to conditionally determine when a stage/step should execute.

Best Practices When Using Built-in Variables With “When” Conditions 

We have multiple types of built-in variables; Pipeline, user variables, triggers, and codebase. 

Variables with the format <+codebase.X> hold information related to the clone operation performed as a part of the CI stage. Variables with the format <+trigger.X> hold information related to how the pipeline was triggered.

Some built-in variables might not get resolved in run time, depending on how the pipeline is triggered (manual, webhook, etc.) and the build type (Tag, Branch, PR). For example, <+codebase.tag> is only populated when building a tag, while <+trigger.prTitle> is only populated if the pipeline was triggered by a Pull Request Git event.

To make working with variables easier, built-in variables have a default value of the string “null”. This means that you can test whether a variable value equals “null” to see if a value was populated.  

So, if you have a stage that should only execute for tags that start with a certain pattern like “v.”, you can easily achieve that using a JEXL that matches a regex pattern to <+codebase.tag>. You can still use this pipeline for building a PR , or a branch, and this stage will be skipped in these cases, as the <+codebase.tag> will be resolved to the string “null,” which does not match the pattern.

pipelineStatus: Success
condition: <+codebase.tag> ~/v.*/


In this blog post, we learned all about conditional execution, using the “when” directive and built-in variables. 

We demonstrated how users can use a single pipeline for similar but slightly different use cases, rather than authoring and maintaining multiple pipelines. 

To learn more, please refer to:

Sign up now

Sign up for our free plan, start building and deploying with Harness, take your software delivery to the next level.

Get a demo

Sign up for a free 14 day trial and take your software development to the next level


Learn intelligent software delivery at your own pace. Step-by-step tutorials, videos, and reference docs to help you deliver customer happiness.

Case studies

Learn intelligent software delivery at your own pace. Step-by-step tutorials, videos, and reference docs to help you deliver customer happiness.

We want to hear from you

Enjoyed reading this blog post or have questions or feedback?
Share your thoughts by creating a new topic in the Harness community forum.

Sign up for our monthly newsletter

Subscribe to our newsletter to receive the latest Harness content in your inbox every month.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
Continuous Integration