Conditional execution of steps

Skip specific pipeline steps according to one or more conditions

For each step in a codefresh.yml file, you can define a set of conditions which need to be satisfied in order to execute the step. For details on the codefresh.yml file, see Pipeline definitions YAML.)

There are currently two main methods to define conditions:

• Branch conditions
• Expression conditions

Branch Conditions

Usually, you’ll want to define a branch condition, be it of the type ignore for blacklisting a set of branches or of the type only for allowlisting a set of branches. Each branch specification can either be an exact branch name, e.g. master, or a regular expression, e.g. /hotfix$/. Case insensitive regexps (/^FB-/i) are also supported.

Here are some examples:

Only execute for the master branch

only-master-branch.yml

build-step:
  description: Building the image.
  type: build
  dockerfile: Dockerfile
  image-name: someRepo/someUser
  when:
    branch:
      only:
        - master

Only execute for feature branches

Only execute for branches whose name begins with FB- prefix, (feature branches):

only-feature-branches.yml

build-step:
  description: Building the image.
  type: build
  dockerfile: Dockerfile
  image-name: someRepo/someUser
  when:
    branch:
      only:
        - /^FB-.*/i

Ignore specific branches

Ignore the development branch and master branch:

ignore-master-and-develop-branch.yml

build-step:
  description: Building the image.
  type: build
  dockerfile: Dockerfile
  image-name: someRepo/someUser
  when:
    branch:
      ignore:
        - master
        - develop

Conditional expressions

Alternatively, you can use more advanced condition expressions.

This follows the standard condition expression syntax. In this case, you can choose to execute if all expression conditions evaluate to true, or to execute if any expression conditions evaluate to true.

NOTE
Use “” around variables with text to avoid errors in processing the conditions. Example: “$”

Here are some examples.

AND conditional expression

Execute if the string [skip ci] is not part of the main repository commit message AND if the branch is master

all-conditions.yml

build-step:
  description: Building the image.
  type: build
  dockerfile: Dockerfile
  image-name: someRepo/someUser
  when:
    condition:
      all:
        noSkipCiInCommitMessage: 'includes(lower("${{CF_COMMIT_MESSAGE}}"), "skip ci") == false'
        masterBranch: '"${{CF_BRANCH}}" == "master"'

OR conditional expression

Execute if the string [skip ci] is not part of the main repository commit message, OR if the branch is not a feature branch (i.e. name starts with FB-)

any-condition.yml

build-step:
  description: Building the image.
  type: build
  dockerfile: Dockerfile
  image-name: someRepo/someUser
  when:
    condition:
      any:
        noSkipCiInCommitMessage: 'includes(lower("${{CF_COMMIT_MESSAGE}}"), "skip ci") == false'
        notFeatureBranch: 'match("${{CF_BRANCH}}", "^FB-", true) == false'

ALL conditions to be met

Each step in codefresh.yml file can contain conditions expressions that must be satisfied for the step to execute.

This is a small example of where a condition expression can be used: YAML

step-name:
  description: Step description
  image: image/id
  commands:
    - bash-command1
    - bash-command2
  when:
    condition:
      all:
        executeForMasterBranch: "'${{CF_BRANCH}}' == 'master'"

Conditional expression syntax

A conditional expression is a basic expression that is evaluated to true/false (to decide whether to execute or not to execute), and can have the following syntax:

Types

Variables

You can use the user-defined variables, including the variables exposed by each individual pipeline step. See Variables in pipelines.

Unary Operators

Binary Operators

Comparisons

Functions

Execute steps according to the presence of a variable

If a variable does not exist in a Codefresh pipeline, then it will simply stay as a string inside the definition. When the ${{MY_VAR}} variable is not available, the engine will literally print ${{MY_VAR}}, because that variable doesn’t exist.

You can use this mechanism to decide which steps will be executed if a variable exists or not.

codefresh.yml

version: "1.0"
steps:
  step1:
    title: "Running if variable exists"
    type: "freestyle" 
    image: "alpine:3.9" 
    commands:
      - echo "Step 1 is running"
    when:
      condition:
        all:
          whenVarExists: 'includes("${{MY_VAR}}", "{{MY_VAR}}") == false'
  step2:
    title: "Running if variable does not exist"
    type: "freestyle" 
    image: "alpine:3.9" 
    commands:
      - echo "Step 2 is running"
    when:
      condition:
        all:
          whenVarIsMissing: 'includes("${{MY_VAR}}", "{{MY_VAR}}") == true'

Try running the pipeline above and see how it behaves when a variable called MY_VAR exists (or doesn’t exist).

NOTE
If you use this pattern frequently it means that you are trying to create a complex pipeline that is very smart. We suggest you create instead multiple simple pipelines for the same project.

Single step dependencies

When parallel execution is enabled, use the when: condition to set up step dependencies through the keywords, steps: and on:. For more information, see parallel pipeline execution.

Related articles

Codefresh YAML for pipeline definitions
Variables in pipelines
Pull Requests and Branches
Hooks in pipelines