How to Run a Build Across Multiple OSes in CircleCI

CircleCI fans across OSes with a parameterized job whose executor is chosen by a matrix parameter.

Define an executor per OS, make the job take an executor parameter, then use a workflow matrix over the executor names so each OS runs as its own job.

Matrix over per-OS executors

The job picks its executor from a parameter; the matrix runs it once per OS.

version: 2.1
executors:
  linux: { docker: [{ image: cimg/node:20.11 }] }
  macos: { macos: { xcode: "15.3.0" } }
  windows: { machine: { image: windows-server-2022-gui:current }, resource_class: windows.medium }

jobs:
  test:
    parameters:
      os: { type: executor }
    executor: << parameters.os >>
    steps:
      - checkout
      - run: npm ci && npm test

workflows:
  cross-platform:
    jobs:
      - test:
          matrix:
            parameters:
              os: [linux, macos, windows]

Gotchas

• macOS and Windows executors require those plans/resource classes to be enabled and are billed at higher rates.
• Each executor has different shells and preinstalled tools - keep steps portable or branch on the OS.
• Matrix parameters of type: executor reference the executor name, not a string you interpolate.

Related guides