How to Set Up a Monorepo Pipeline in CircleCI

CircleCI handles monorepos with a setup workflow: the path-filtering orb sets parameters from changed files, then continues to a generated config.

Enable setup workflows, use the path-filtering orb to map changed paths to pipeline parameters, then continuation runs the real config with only the affected parts enabled.

Path-filtering setup workflow

The setup config maps changed paths to parameters and continues to the main config.

version: 2.1
setup: true
orbs:
  path-filtering: circleci/path-filtering@1

workflows:
  setup:
    jobs:
      - path-filtering/filter:
          base-revision: main
          config-path: .circleci/continue.yml
          mapping: |
            packages/api/.* run-api true
            packages/web/.* run-web true

Gotchas

• The top-level setup: true flag and "setup workflows" must be enabled in project settings, or the filter is ignored.
• The continued config (continue.yml) reads the parameters and gates each workflow with when: << pipeline.parameters.run-api >>.
• base-revision controls the diff base; on the default branch the diff may be empty, so handle the no-change case.

Related guides