Conditional recipes
These recipes show how to run workflows, jobs and steps conditionally. For expression syntax, see the 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 branchesworkflows: 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?" article for more information.
-
You can also choose to prevent the workflow from running for specific branches using the
notoperator withmatchesfor pattern matching: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:
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
-
Update config to declare a pipeline parameter with a default value of
false. -
Update your workflow config to use a when statement so the workflow will only run when the pipeline parameter is true.
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?" article for more information.
-
You can also use the shorthand syntax to achieve the same result:
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: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:
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. For workflow-level conditions, you can use Expression Syntax instead.
|
Steps
-
Update your CircleCI config to use The When Step with a nested logic statement.
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"
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.
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?" article for more information.
-
To trigger a pipeline and pass custom values for your pipeline parameters, you can either: