Expression-Based Job Filters

Overview

Expression-based job filters allow users to control when jobs run in a workflow based on dynamic conditions. This provides greater flexibility compared to standard branch or tag filters. By leveraging expressions, users can create advanced filtering rules based on pipeline parameters, environment variables, or other contextual data.

Method: Using Expression-Based Job Filters

1. Defining Expressions in Workflows

Expression-based filters can be used in the when condition within a workflow’s jobs declaration. The syntax follows the standard << pipeline.parameters.* >> format.

2. Example Usage

To filter a job based on a pipeline parameter:

version: 2.1

parameters:
  run_tests:
    type: boolean
    default: false

workflows:
  example_workflow:
    jobs:
      - test:
          when: << pipeline.parameters.run_tests >>

In this example, the test job only runs if run_tests is set to true when the pipeline is triggered.

3. Conditional Execution with Expressions

You can create more complex conditions using logical operators:

parameters:
  deploy_env:
    type: string
    default: "staging"

workflows:
  deploy_workflow:
    jobs:
      - deploy:
          when:
            equal: [ "production", << pipeline.parameters.deploy_env >> ]

Here, the deploy job runs only if the deploy_env parameter is set to "production".

4. Combining Multiple Conditions

Using or, and, or not operators:

workflows:
  conditional_workflow:
    jobs:
      - build:
          when:
            or:
              - equal: [ "main", << pipeline.git.branch >> ]
              - equal: [ "staging", << pipeline.parameters.deploy_env >> ]