Documentation structure for LLMs (llms.txt)

Conditional recipes

Cloud Server

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 branches
    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?" 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:

    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

  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.

    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"

Notes

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