Orchestration cookbook

This option is only available for GitHub App pipelines. If you have a GitHub OAuth integration you can install the GitHub App into your GitHub org and then create GitHub App pipelines. This is a quick one-time action, as described in the Using the CircleCI GitHub App in an OAuth Organization page.

This option is only available for GitHub App pipelines. If you have a GitHub OAuth integration you can install the GitHub App into your GitHub org and then create GitHub App pipelines. This is a quick one-time action, as described in the Using the CircleCI GitHub App in an OAuth Organization page.

Update your CircleCI config to include a workflow that you only want to run when a PR is opened.

workflows:
  workflow-pr-open:
    # Only run this workflow when a PR is opened
    when: pipeline.event.name == "pull_request" and pipeline.event.action == "opened"
    jobs:
      - my-job-1
      - my-job-2

The pipeline.event.name and pipeline.event.action variables are only available for GitHub App pipelines. If you have a GitHub OAuth integration you can install the GitHub App into your GitHub org and then create GitHub App pipelines. This is a quick one-time action, as described in the Using the CircleCI GitHub App in an OAuth Organization page.

Update your CircleCI config to include a workflow that will only run for specific branches. You can configure the workflow using an expression.

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

Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.

You can also choose to prevent the workflow from running for specific branches using the not operator with matches for 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:

Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.

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:

You must define your pipeline parameters in the parameters section before using them in workflow conditions. The parameter name deploy in this example is just an example. You can use any parameter name you define, for example, run_tests, skip_validation, or enable_feature.

The workflow when clause expects a direct expression. Use pipeline parameter names directly (for example, pipeline.parameters.deploy).

Do not mix << >> delimiters with direct expressions. The << >> syntax is used to mark expressions inside string values. If the when clause contains << >> delimiters, the entire value is treated as a string with template replacement rather than as a direct expression. This causes the workflow to always be created regardless of the actual condition.

# Incorrect: mixing direct expression with << >> delimiters
workflows:
  my-workflow:
    when: pipeline.event.name == "push" or << pipeline.parameters.deploy >>
    jobs:
      - build

For simple parameter checks, you can use << >> syntax on its own, since the entire value is then a single expression. Remember to replace deploy with your own parameter name:

workflows:
  my-workflow:
    when: << pipeline.parameters.deploy >>
    jobs:
      - build

For more details, see the Using When in Workflows and Using Expressions in Your Configuration sections in the configuration reference.

To trigger a pipeline and pass custom values for your pipeline parameters, you can either:

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"

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:

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"

Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.

To trigger a pipeline and pass custom values for your pipeline parameters, you can either:

Update your CircleCI config to use the pipeline.trigger.type and pipeline.schedule.name Pipeline Values.

workflows:
  nightly-run-workflow:
# The "nightly-run-workflow" workflow only runs when the trigger is scheduled AND the name of that trigger is "nightly_build"
    when: pipeline.trigger.type == "schedule" and pipeline.schedule.name == "nightly_build"
    jobs:
      - build
      - deploy

Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.

Update your CircleCI config to use the pipeline.event.name and pipeline.event.action Pipeline Values.

workflows:
# The "run_on_pr" workflow only runs when open pull requests are labeled or updated with new commits.
  run_on_pr:
    when: (pipeline.event.name == "pull_request" and pipeline.event.action == "labeled") or (pipeline.event.name == "pull_request" and pipeline.event.action == "synchronize")

The pipeline.event.name and pipeline.event.action variables are not available for GitLab pipelines.

Environment variables cannot be used in expressions and logic statements. You can only use pipeline values or pipeline parameters.

The no-op job performs no actions and consumes no credits. This makes it an ideal structural element in your workflow.

This pattern is useful when you want to visually group related jobs in the CircleCI UI.

Using no-op jobs can simplify workflow management when dealing with complex dependency chains.

Without the test-coordinator job, the deploy job would need to list all test jobs in its requires section.

This approach simplifies branch protection management in GitHub by requiring only one status check.

When you add new checks, you only need to update the requires list for your no-op job.

The no-op job will succeed only if all its required jobs succeed.

This pattern helps keep GitHub and CircleCI configurations in sync without manual updates.