How to Deploy Only on the Main Branch in CircleCI

A filters.branches.only: main on the deploy job keeps every other branch running build and test while deploys fire from main alone.

Add a workflow-level branch filter to the deploy job so it is scheduled only on main, leaving the shared build and test jobs unfiltered.

Steps

• Keep build and test jobs without filters so PRs run them.
• Add filters.branches.only: main to the deploy job.
• Use requires so deploy runs after test.

Config

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

Gotchas

• Branch filters live on the workflow job, not inside the job definition.
• A filtered-out job is simply not scheduled; it does not show as skipped.

Related guides