Documentation structure for LLMs (llms.txt)
CircleCI Logo

Branch and tag filtering

27 days ago
Cloud Server v4+

You can control whether a job, workflow, or step runs, based on the git branch or tag that triggered the pipeline. CircleCI provides several mechanisms, covered in the sections below. Choose one based on what you want to control:

  • Filter a job by branch or tag with workflow filters.

  • Filter a job with an expression, for finer control than branch and tag filters allow.

  • Run a whole workflow only when a condition is met, using an expression.

  • Run a single step only when a condition is met, using a when step.

Expression-based conditions are the most flexible option. They can reference pipeline values and pipeline parameters and use comparison and logic operators, so they cover most cases where you previously needed branch filters.

Filter a job by branch or tag

To control which branches or tags run a job, add a filters key to the job in your workflow. The filters key takes branches and tags keys. Each accepts only and ignore values, which can be exact strings or regular expressions.

version: 2.1

workflows:
  build-test-deploy:
    jobs:
      - test:
          filters:
            branches:
              only:
                - main
                - /^feature-.*/ # any branch beginning feature-
      - deploy:
          filters:
            branches:
              ignore: main
CircleCI does not run workflows for tags unless you specify a tags filter. If a job uses a tag filter, every job it depends on must specify the same tag filter.

For regular-expression examples and tag-filtering detail, see the Using Filters in Your Workflows section.

Filter a job with an expression

For finer control than branches and tags allow, set the filters key on a job to an expression instead of a branches or tags map. The job runs only when the expression evaluates to true. Expressions can reference pipeline values and pipeline parameters and use comparison and logic operators. A single expression can replace conditions that would otherwise need several filters.

The following example runs integration-test on main or any branch starting with integration-, and runs deploy only on main:

version: 2.1

workflows:
  build-deploy:
    jobs:
      - integration-test:
          filters: pipeline.git.branch == "main" or pipeline.git.branch starts-with "integration-"
      - deploy:
          requires:
            - integration-test
          filters: pipeline.git.branch == "main"

Use either the expression form or the branches and tags form for a given job, not both. For the full operator list and more examples, see the Expression-Based Job Filters reference.

Filter a workflow with an expression

To run an entire workflow only when a condition is met, add a when clause (or the inverse unless clause) with a logic statement to the workflow declaration. This approach is more flexible than filters because the condition can use pipeline values, pipeline parameters, and operators.

The following example runs the integration_tests workflow only when the pipeline is on the main branch:

version: 2.1

workflows:
  integration_tests:
    when: pipeline.git.branch == "main"
    jobs:
      - mytestjob

For the operators you can use in a condition, see the Logic Statements reference.

Filter a step with when

To control whether a single step runs, wrap it in a when step with a condition. Use this approach when most of a job is shared across branches but one step runs only on a particular branch.

The following example uses the pipeline.git.branch pipeline value to run the echo step only when the commit is on the main branch:

version: 2.1

jobs:
  my-job:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - when:
          condition:
            equal: [ main, << pipeline.git.branch >> ]
          steps:
            - run: echo "I am on main"

workflows:
  my-workflow:
    jobs:
      - my-job