Filtering Workflows and Jobs
1. Filtering by Branch
| Filter Type | Configuration | Description |
|---|---|---|
| branches.ignore | ["master", "develop"] |
Excludes specified branches from triggering workflows. |
| branches.only | ["main", "release/*"] |
Only runs workflows on specified branches. |
Example: Filtering by Branch
workflows:
version: 2
build-and-test:
jobs:
- build
- test
jobs:
build:
docker:
- image: circleci/node:16
steps:
- checkout
- run: npm install
test:
docker:
- image: circleci/node:16
steps:
- checkout
- run: npm test
workflows:
version: 2
build-and-test:
branches:
only:
- main
- release/*
Note: The
branches.only filter takes precedence over branches.ignore.2. Filtering by Tag
| Filter Type | Description | Example |
|---|---|---|
| tags | Filter jobs based on Git tags applied to the commit. | tags: [v1.0, v2.0] |
| tags.exclude | Exclude jobs when a specific tag is present. | tags.exclude: [nightly] |
| tags.regex | Use regex to match tags for filtering. | tags.regex: /^v\d+\.\d+$/ |
Example: Using Tag Filters in a Workflow
workflows:
build-and-test:
jobs:
- build:
tags:
- v1.0
- v2.0
- test:
tags:
- v1.0
- v2.0
Example: Excluding Jobs with a Specific Tag
workflows:
build-and-test:
jobs:
- build:
tags:
exclude: [nightly]
- test:
tags:
exclude: [nightly]
Note: Tag filtering is useful for running specific jobs only on tagged commits, such as release builds or versioned deployments.
3. Using Regex Patterns
| Pattern Type | Description | Example | Notes |
|---|---|---|---|
| branch | Matches branch names using regex | feature\/.* |
Matches any branch starting with feature/ |
| tag | Matches tag names using regex | v[0-9]+\.[0-9]+\.[0-9]+ |
Matches semantic version tags like v1.0.0 |
| job | Matches job names using regex | test-.* |
Matches any job starting with test- |
Example: Filtering by Branch Regex
workflows:
version: 2
main:
jobs:
- build:
filters:
branches:
only: /feature\/.*/Example: Filtering by Tag Regex
workflows:
version: 2
main:
jobs:
- deploy:
filters:
tags:
only: /v[0-9]+\.[0-9]+\.[0-9]+/4. Using Wildcard Patterns
CircleCI supports wildcard patterns in workflow and job filtering to allow flexible matching of job names. These patterns can be used in configuration files to select jobs based on naming conventions.
| Pattern | Description | Example | Matched Jobs |
|---|---|---|---|
| *suffix | Matches any job name ending with the specified suffix | *test |
Any job ending with test, such as unit-test or integration-test |
| prefix* | Matches any job name starting with the specified prefix | build* |
Any job starting with build, such as build-app or build-deploy |
| *middle* | Matches any job name containing the specified substring | *deploy* |
Any job containing deploy, such as staging-deploy or prod-deploy |
| prefix*suffix | Matches any job name starting with prefix and ending with suffix | test*prod |
Any job starting with test and ending with prod, such as test-integration-prod |
Example: Using Wildcard Patterns in Workflow Configuration
workflows:
version: 2
main-workflow:
jobs:
- build-app
- test-app
- deploy-staging
- deploy-prod
filtered-workflow:
jobs:
- <span class="property">test*</span>
- <span class="property">deploy*</span>
Note: Wildcard patterns are case-sensitive and must match the full job name exactly as defined in the configuration.
5. Combining Branch and Tag Filters
| Filter Type | Pattern | Description |
|---|---|---|
| branches | only: [main, develop] |
Run on specific branches |
| branches | ignore: [feature/*] |
Exclude branches matching pattern |
| tags | only: [v1.0.*, v2.*] |
Run on specific tag patterns |
| tags | ignore: [v0.*] |
Exclude tags matching pattern |
Example: Combining Filters in Workflow
workflows:
version: 2
build-and-test:
jobs:
- build:
filters:
branches:
only:
- main
- develop
tags:
only:
- v1.0.*
- v2.*
Note: Filters are evaluated in order, with
only taking precedence over ignore.
6. Understanding Filter Logic
| Filter Type | Description | Usage Example |
|---|---|---|
| branches | Filters jobs based on branch names. | branches: { only: [main, develop] } |
| tags | Filters jobs based on tag names. | tags: { only: [v1.0.*, v2.0.*] } |
| statuses | Filters jobs based on build status (success, failed, etc.). | statuses: { only: [success] } |
| pull_requests | Filters jobs based on whether they are part of a pull request. | pull_requests: { ignore: [main] } |
Example: Branch-based filtering
workflows:
build:
jobs:
- test:
filters:
branches:
only:
- main
- develop
Note: Filters are evaluated in the order they appear in the configuration file.
Warning: If no filter matches, the job will not run.
7. Understanding Filter Precedence
| Filter Type | Scope | Precedence Level | Notes |
|---|---|---|---|
| branch | branches section |
Level 1 | Applies to all jobs in the branch |
| tag | tags section |
Level 2 | Overrides branch filters if matched |
| workflow | workflows section |
Level 3 | Applies to specific workflow jobs |
| job | jobs section |
Level 4 | Highest precedence, overrides all others |
Note: Filters are evaluated in order of precedence, with job-level filters taking priority over workflow and branch-level filters.
8. Filtering Scheduled Workflows
| Property | Description | Values | Notes |
|---|---|---|---|
| schedule | Defines the cron schedule for the workflow | 0 0 * * * |
Uses standard cron syntax |
| filters.branches | Branch names to include or exclude | main, feature/* |
Supports wildcards and regex patterns |
| filters.tags | Tag names to include or exclude | v1.0*, release/* |
Supports regex patterns |
| filters.status | Workflow status to filter by | success, failed |
Can filter based on previous job status |
Example: Scheduled Workflow with Branch Filtering
version: 2.1
jobs:
build:
docker:
- image: circleci/python:3.9
steps:
- run: echo "Building..."
workflows:
scheduled-build:
triggers:
- schedule:
cron: "0 0 * * *"
filters:
branches:
only:
- main
- develop
Note: The
schedule trigger supports cron expressions and can be combined with branch or tag filters to control when workflows run.
9. Filtering API-Triggered Pipelines
| Field | Description | Values |
|---|---|---|
| pipeline.trigger | Specifies the type of trigger that initiated the pipeline | api |
| pipeline.filters.branch | Filters pipelines by branch name | main, feature/* |
| pipeline.filters.tag | Filters pipelines by tag pattern | v1.*, release/* |
| pipeline.filters.workflow | Filters pipelines by workflow name | build-and-test, deploy-staging |
Example: Filtering by Branch
version: 2.1
jobs:
build:
docker:
- image: circleci/node:16
steps:
- checkout
- run: echo "Building on branch $CIRCLE_BRANCH"
workflows:
version: 2
build-and-test:
jobs:
- build:
filters:
branches:
only: main
Example: Filtering by Tag
version: 2.1
jobs:
release:
docker:
- image: circleci/node:16
steps:
- checkout
- run: echo "Releasing version $CIRCLE_TAG"
workflows:
version: 2
release-workflow:
jobs:
- release:
filters:
tags:
only: /^v[0-9]+\.[0-9]+\.[0-9]+/
10. Debugging Filter Issues
Example: Using debug filter in CircleCI config
version: 2.1
jobs:
build:
docker:
- image: circleci/node:16
steps:
- checkout
- run:
name: Debug filter
command: |
echo "Filter debug info:"
echo "Branch: $CIRCLE_BRANCH"
echo "Tag: $CIRCLE_TAG"
echo "Event: $CIRCLE_EVENT"
| Filter Type | Description | Debugging Tips |
|---|---|---|
| branch | branches: filter for specific branches |
Use echo "Branch: $CIRCLE_BRANCH" to verify matching |
| tag | tags: filter for specific tags |
Check $CIRCLE_TAG in job to confirm matching |
| event | only: or ignore: for event types |
Log $CIRCLE_EVENT to see trigger type |
Note: CircleCI uses
CIRCLE_BRANCH, CIRCLE_TAG, and CIRCLE_EVENT environment variables to determine filter matches.Warning: Filters are evaluated before job execution, so debug output must be added to the job's command or script.