---
title: "Conditional recipes"
description: "Recipes for running workflows, jobs and steps conditionally using expressions, pipeline parameters and logic statements."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-11-16"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Conditional recipes

These recipes show how to run workflows, jobs and steps conditionally. For expression syntax, see the [Using Expressions in Your Configuration](https://circleci.com/docs/reference/configuration-reference/#using-expressions-in-your-configuration).

## Run a workflow only for specific branches

### Goal

You may want to configure a workflow that will only run when the pipeline is triggered on a specific branch.

### Steps

*   Update your CircleCI config to include a workflow that will only run for specific branches. You can configure the workflow using an expression.
    
    The nightly-run-workflow only runs on the main and staging branches
    
    ```yaml
    workflows:
      nightly-run-workflow:
    # The "nightly-run-workflow" workflow only runs if the branch name is "main" OR "staging".
        when: pipeline.git.branch == "main" or pipeline.git.branch == "staging"
        jobs:
          - build
          - deploy:
              requires:
                - build
    ```
    

### Notes

*   Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.
    
    Expressions and logic statements are evaluated at compilation time whereas the actual values of environment variables only become available at run time.
    
    See the ["Can I use environment variables in conditional statements?"](https://support.circleci.com/hc/en-us/articles/21200178128155-Can-I-use-environment-variables-in-conditional-statements) article for more information.
    
*   You can also choose to prevent the workflow from running for specific branches using the `not` operator with `matches` for pattern matching:
    
    ```yaml
    workflows:
      my-workflow:
    # The "my-workflow" workflow will NOT run when the branch name matches the pattern "feature-.*"
        when: not (pipeline.git.branch matches /^feature-.*$/)
        jobs:
          - build
    ```
    
*   To trigger a pipeline and pass custom values for your pipeline parameters, you can either:
    
    *   [Trigger a Pipeline Using the API](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-using-the-api)
        
    *   [Trigger a Pipeline From the CircleCI Web App](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-from-the-circleci-web-app)
        
    *   [Schedule a Pipeline](https://circleci.com/docs/guides/orchestrate/triggers-overview/#schedule-a-pipeline)
        
    

## Run a workflow depending on the value of a boolean parameter

### Goal

You may want to configure a workflow that will only run when a boolean pipeline parameter is true.

### Steps

1.  Update config to declare a pipeline parameter with a default value of `false`.
    
2.  Update your workflow config to use a when statement so the workflow will only run when the pipeline parameter is true.
    
    ```yaml
    version: 2.1
    
    parameters:
      run_integration_tests:
        type: boolean
        default: false
    
    workflows:
      integration_tests:
    # The "integration_tests" workflow only runs if the pipeline parameter "run_integration_tests" is true.
        when: pipeline.parameters.run_integration_tests
        jobs:
          - mytestjob
    ```
    

### Notes

*   Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.
    
    Expressions and logic statements are evaluated at compilation time whereas the actual values of environment variables only become available at run time.
    
    See the ["Can I use environment variables in conditional statements?"](https://support.circleci.com/hc/en-us/articles/21200178128155-Can-I-use-environment-variables-in-conditional-statements) article for more information.
    
*   You can also use the shorthand syntax to achieve the same result:
    
    ```yaml
    version: 2.1
    
    parameters:
      run_integration_tests:
        type: boolean
        default: false
    
    workflows:
      integration_tests:
    # The "integration_tests" workflow only runs if the pipeline parameter "run_integration_tests" is true.
        when: << pipeline.parameters.run_integration_tests >>
        jobs:
          - mytestjob
    ```
    
*   You can create complex expressions that involve multiple parameters using `and`, `or`, and parentheses for grouping:
    
    ```yaml
    workflows:
      my-workflow:
    # This workflow runs when: branch is "main" AND param1 is false AND (param2 OR param3 is true)
        when: pipeline.git.branch == "main" and not pipeline.parameters.param1 and (pipeline.parameters.param2 or pipeline.parameters.param3)
        jobs:
          - build
    ```
    
*   To trigger a pipeline and pass custom values for your pipeline parameters, you can either:
    
    *   [Trigger a Pipeline Using the API](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-using-the-api)
        
    *   [Trigger a Pipeline From the CircleCI Web App](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-from-the-circleci-web-app)
        
    *   [Schedule a Pipeline](https://circleci.com/docs/guides/orchestrate/triggers-overview/#schedule-a-pipeline)
        
    

## Run a step based on a nested condition

### Goal

You may want to configure a step that will run depending on the output of a nested condition using logic statement syntax.

Expressions are not supported for step-level `when` conditions. Use logic statement syntax for the `condition` field of [The When Step](https://circleci.com/docs/reference/configuration-reference/#the-when-step). For workflow-level conditions, you can use [Expression Syntax](https://circleci.com/docs/reference/configuration-reference/#using-expressions-in-your-configuration) instead.

### Steps

*   Update your CircleCI config to use [The When Step](https://circleci.com/docs/reference/configuration-reference/#the-when-step) with a nested logic statement.
    
    ```yaml
    version: 2.1
    
    parameters:
      param1:
        type: boolean
        default: false
      param2:
        type: boolean
        default: false
      param3:
        type: boolean
        default: false
      param4:
        type: boolean
        default: true
    
    jobs:
      test:
        docker:
          - image: cimg/node:19.0.1
        steps:
          - checkout
          - when:
              condition:
                and:
                  - or:
                    - and:
                      - equal: [ main, << pipeline.git.branch >> ]
                      - equal: [ false, << pipeline.parameters.param1 >> ]
                    - not: << pipeline.parameters.param3 >>
                  - or:
                    - equal: [ false, << pipeline.parameters.param3 >> ]
                    - or: [ << pipeline.parameters.param1 >>, << pipeline.parameters.param2 >> ]  
    # The output of the nested logic statement will depend on the values of the pipeline parameters. This step will only run if the condition evaluates as true.
              steps:
                - run: echo "The condition evaluated as true"
    ```
    

### Notes

*   Logic statements can be nested to a maximum depth of 100 levels.
    
*   To trigger a pipeline and pass custom values for your pipeline parameters, you can either:
    
    *   [Trigger a Pipeline Using the API](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-using-the-api)
        
    *   [Trigger a Pipeline From the CircleCI Web App](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-from-the-circleci-web-app)
        
    *   [Schedule a Pipeline](https://circleci.com/docs/guides/orchestrate/triggers-overview/#schedule-a-pipeline)
        
    

## Run a job only on specific branches or when the value of a pipeline parameter is true

### Goal

You may want to configure a job that only runs on specific branches or when the value of a pipeline parameter is `true`.

### Steps

*   Update your CircleCI config to include an [Expression-Based Job Filter](https://circleci.com/docs/reference/configuration-reference/#expression-based-job-filters).
    
    ```yaml
    version: 2.1
    
    parameters:
      run-storybook-tests:
        type: boolean
        default: false
    
    ...
    # jobs configuration omitted for brevity
    
    workflows:
      build:
        jobs:
          - setup
          - storybook-tests:
    # The "storybook-tests" job only runs if the "setup" job completes successfully AND if either the "run-storybook-test"s pipeline parameter is true OR the branch name is "dry-run-deploy" OR the branch name starts with "deploy".
              requires:
                - setup
              filters: |
                pipeline.parameters.run-storybook-tests
                or pipeline.git.branch == "dry-run-deploy"
                or pipeline.git.branch starts-with "deploy"
    ```
    

### Notes

*   Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.
    
    Expressions and logic statements are evaluated at compilation time whereas the actual values of environment variables only become available at run time.
    
    See the ["Can I use environment variables in conditional statements?"](https://support.circleci.com/hc/en-us/articles/21200178128155-Can-I-use-environment-variables-in-conditional-statements) article for more information.
    
*   To trigger a pipeline and pass custom values for your pipeline parameters, you can either:
    
    *   [Trigger a Pipeline Using the API](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-using-the-api)
        
    *   [Trigger a Pipeline From the CircleCI Web App](https://circleci.com/docs/guides/orchestrate/triggers-overview/#run-a-pipeline-from-the-circleci-web-app)
        
    *   [Schedule a Pipeline](https://circleci.com/docs/guides/orchestrate/triggers-overview/#schedule-a-pipeline)