---
title: "Branch and tag filtering"
description: "Control whether jobs, workflows, and steps run, based on the git branch or tag, using workflow filters or expression-based conditions."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-09-28"
---

> 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).

# Branch and tag filtering

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** with an expression.
    
*   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 with an expression

Set the `filters` key on a job to an expression. The job runs only when the expression evaluates to true. Expressions can reference pipeline values and pipeline parameters and use comparison and logic operators.

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

```yaml
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"
```

For the full operator list and more examples, see the [Expression-Based Job Filters](https://circleci.com/docs/reference/configuration-reference/#expression-based-job-filters) reference.

[Branch and Tag Job Filters](https://circleci.com/docs/reference/configuration-reference/#jobfilters) are deprecated. If you have a job that uses them, you can replace them with expression-based job filters as described in this section.

## 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 an expression to the workflow declaration. Expressions can reference pipeline values and pipeline parameters and use comparison and logic operators.

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

```yaml
version: 2.1

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

For the operators you can use in a condition, see the [Expression Operators](https://circleci.com/docs/reference/configuration-reference/#expression-operators) 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:

```yaml
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
```