How to Run a Job Only on Main in CircleCI

A filters.branches.only: main block on a workflow job runs that job for main commits only, while the rest of the pipeline runs everywhere.

Keep build and test jobs unfiltered so every branch runs them, and add filters.branches.only: main to the deploy job so it fires only on the default branch.

Steps

• Leave test jobs with no filters so they run on all branches.
• Add filters.branches.only: main to the deploy/release job.
• Use requires: so the gated job runs only after tests pass.

Config

version: 2.1
workflows:
  ci:
    jobs:
      - test
      - deploy:
          requires: [test]
          filters:
            branches:
              only: main

Gotchas

• If your default branch is master or trunk, update the filter; CircleCI does not assume main.
• Combine with an approval job before deploy if you want a human gate as well as the branch gate.

Related guides