Introduction

By default, CircleCI automatically triggers a pipeline (which runs builds) every time you push a commit to your repository. While this continuous integration workflow works well for many projects, you might want to control when builds run to save compute credits, reduce build queue times, or run pipelines only for specific branches or events. This article explains several methods to prevent or control automatic build triggers when pushing commits to your repository.

Prerequisites

Before implementing these solutions, you should have:

An active CircleCI account with at least one connected project
Access to your project's .circleci/config.yml configuration file
Permission to modify your repository (for Git commit methods)
Permission to modify CircleCI project settings (for project-level changes)

Solutions

Option 1: Use [ci skip] or [skip ci] Tags

The simplest way to prevent a build from triggering on a specific commit is to include a skip tag in your commit message.

How it works:

When you include [ci skip] or [skip ci] in the commit message (either in the title or body), CircleCI will not trigger a pipeline for that push.

Steps:

When making your commit, include one of these tags in your commit message:

git commit -m "Update documentation [ci skip]"

Or in the commit body:

git commit -m "Update README [skip ci] This is just a documentation update"

Push your commit as normal:

git push origin your-branch

Important notes:

If you push multiple commits at once and only the latest commit includes the skip tag, all commits in that push will be skipped
This feature does NOT work for forked pull requests
Scheduled workflows will still run, even if you push commits with skip tags
This wont work for GitHub App pipelines, custom webhook or schedule-triggered pipelines
For GitHub OAuth and Bitbucket Cloud pipelines, this applies to API triggers, manual web app triggers, and scheduled pipelines as well

Option 2: Use Workflow Filters to Run Builds Only on Specific Branches

Workflow filters can be used in your config file to control which branches trigger builds at a job-level. This certain jobs in a workflow to run whilst ignoring others that don't meet the conditions of the filter.

How it works:

Workflow filters can be applied to each job in a workflow by using the filters key with the branches parameter to specify which branches should or should not trigger that job. You can use only to allow specific branches or ignore to exclude specific branches.

Steps:

Open your .circleci/config.yml file
Add or modify your workflows section with branch filters:

version: 2.1jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run: echo "Building application"
  
  test:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run: echo "Running tests"workflows:
  main-workflow:
    jobs:
      - build:
          filters:
            branches:
              only:
                - main
                - develop
      - test:
          requires:
            - build
          filters:
            branches:
              only:
                - main
                - develop

Note: In this example the jobs in the main-workflow workflow will only trigger on the main and develop branches

Commit and push your configuration changes

Filter options:

You can use several filter patterns:

only: Specifies which branches SHOULD trigger the job
ignore: Specifies which branches SHOULD NOT trigger the job
Regular expressions: Use regex patterns for flexible matching for the branch name

Examples:

only examples:

The only tag can be applied to a single branch, e.g the main branch, using the following:

filters:
  branches:
    only: main

The only tag can also be applied to multiple branches to run builds on specific branches, using the following:

filters:
  branches:
    only:
      - main
      - staging
      - production

only and regular expression:

Regular expressions can also be used with the only tag to prevent builds triggering on branches that contain key words, characters and phrases, e.g Run on main and all release branches:

filters:
  branches:
    only:
      - main
      - /release\/.*/

ignore examples:

The ignore tag can also be applied to single or multiple branches to prevent builds triggering, you can use the following to implement this:

filters:
  branches:
    ignore:
      - staging 
      - /feature\/.*/
      - /bugfix\/.*/

Note: Although this example uses a mixture of branch names and regular expression, you can also use one or the other

Important notes:

If you specify both only and ignore, the only filter is evaluated first, followed by the ignore filter
If you include the filters and branches filters, you must include only and/or ignore below branches otherwise the jobs will be skipped for all branches
With Regular expression there are some important things to note:
- The pattern must start and end with a forward slash (/)
- Patterns must match the entire branch name, e.g /feature/ will look for branches that are exclusively called feature
- To find branches with characters before feature use ^ at the beginning and use .* at the end of your regex expression, e.g /^feature.*/
- To find branches with characters after feature use .* at the beginning and use $ at the end of your regex expression, e.g /.*feature$/
- To find branches with characters before after feature using .* at the beginning and end of your regex expression, e.g /.*feature.*/
When using regex, remember to escape special characters with backslashes

Option 3: Use Conditional Workflows with Pipeline Parameters

For more granular control over your workflows, you can use conditional workflows with pipeline parameters. This method allows you to trigger builds when certain conditions are met or when manually specified.

How it works:

Conditional workflows use a mixture of pipeline parameters and use conditional logic (when clauses)to control when they run. This gives you fine-grained control over build execution.

Steps:

Add pipeline parameters to your .circleci/config.yml:

version: 2.1parameters:
  run_build:
    type: boolean
    default: false
  run_tests:
    type: boolean
    default: falsejobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run: echo "Building"
  
  test:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - run: echo "Testing"workflows:
  build_workflow:
    when: << pipeline.parameters.run_build >>
    jobs:
      - build
  
  test_workflow:
    when: << pipeline.parameters.run_tests >>
    jobs:
      - test

Note: In the example above, neither of the workflows will run automatically as the parameter in the when condition needs to be true and the default value for both parameters are set to false

To manually trigger a workflow, use the CircleCI API and set the relevant parameter to true, for example:

To trigger the build_workflow from the example above use the following API command:

curl --request POST \
  --url https://circleci.com/api/v2/project/{vcs-slug}/{org-name}/{repo-name}/pipeline \
  --header 'Circle-Token: YOUR_API_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "parameters": {
      "run_build": true
    }
  }'

To trigger the test_workflow from the example above use the following API command:

curl --request POST \
  --url https://circleci.com/api/v2/project/{vcs-slug}/{org-name}/{repo-name}/pipeline \
  --header 'Circle-Token: YOUR_API_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "parameters": {
      "run_tests": true
    }
  }'

Alternative use for conditional workflows

Conditional workflows can also be used if you want your workflow to only run for certain branches. This is similar to "Option 2" but these conditions are applied at a workflow-level meaning that all jobs in that workflow will run if the conditions are met. Please see the examples below for how to implement this:

Run the workflow only on main branch:

workflows:
  main_only:
    when:
      equal: [ main, << pipeline.git.branch >> ]
    jobs:
      - build

Only run the workflow when it's not the main branch:

workflows:
  feature_branches:
    when:
      not:
        equal: [ main, << pipeline.git.branch >> ]
    jobs:
      - test

Solution 4: Enable Auto-Cancel for Redundant Workflows

While this doesn't prevent the initial build from triggering, auto-cancel can help manage resources by automatically canceling older builds when you push new commits to the same branch.

How it works:

When enabled, CircleCI automatically cancels non-terminated workflows when a newer pipeline is triggered on the same non-default branch. This prevents old builds from consuming resources when you've already pushed newer changes.

Steps:

Navigate to your project in CircleCI web app
Go to Project Settings
Select Advanced Settings
Toggle on Auto-cancel redundant workflows

Important notes:

This feature does NOT auto-cancel workflows on your default branch (usually main)
Only affects workflows triggered by pushes to your VCS (Version Control System) or via API
Does NOT cancel scheduled workflows or re-run workflows
Only workflows that were triggered after enabling this feature will be auto-cancelled

When to use this method:

Use auto-cancel when:

You frequently push multiple commits to feature branches
You want to avoid wasting credits on outdated builds
You need the most recent build results faster
You're working on fast-moving feature branches

Additional Notes

Combining multiple methods:

You can combine these methods for even more control. For example:

Use branch filters to run builds only on certain branches
Use skip tags for occasional commits that don't need builds
Enable auto-cancel to manage queue times on active branches

Cost considerations:

Controlling when builds run can significantly reduce your CircleCI credit consumption. Consider your team's workflow when deciding which method to implement.

GitHub Status Checks:

If you're using GitHub protected branches with required status checks, be aware that:

Skipped builds won't report status to GitHub
This might block merging if CircleCI checks are required
You may need to adjust your branch protection rules accordingly

Troubleshooting:

If your configuration isn't working as expected:

Verify your YAML syntax is correct
Check that branch names match exactly (case-sensitive)
For regex patterns, test them to ensure they match intended branches
Review CircleCI's pipeline processing errors in the web app

Additional Resources

Troubleshooting [ci skip] or [skip ci] Not Working

How to Schedule a Nightly Build

Troubleshooting duplicate builds triggered upon every commit/push

How to Trigger a Workflow via CircleCI API v2

Triggering CircleCI Builds on New Branches via API

How to Prevent Triggering Builds on Commit Pushes

Introduction

Prerequisites

Solutions

Option 1: Use [ci skip] or [skip ci] Tags

How it works:

Steps:

Option 2: Use Workflow Filters to Run Builds Only on Specific Branches

How it works:

Steps:

Filter options:

Examples:

only examples:

only and regular expression:

ignore examples:

Option 3: Use Conditional Workflows with Pipeline Parameters

How it works:

Steps:

Alternative use for conditional workflows

Solution 4: Enable Auto-Cancel for Redundant Workflows

Additional Notes

Combining multiple methods:

Cost considerations:

GitHub Status Checks:

Troubleshooting:

Additional Resources