How to Set Up a Matrix of Operating Systems in GitHub Actions

Drive runs-on from a matrix dimension to run the same job on every operating system you support.

Put the OS list in strategy.matrix and set runs-on: ${{ matrix.os }}. Each OS runs as a parallel job.

Steps

Add an os: dimension to the matrix.
Set runs-on: ${{ matrix.os }}.
Use fail-fast: false to see every platform's result.

Workflow

.github/workflows/ci.yml

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

Gotchas

Windows and macOS minutes are billed at a multiple of Linux minutes.
Shell syntax differs per OS; set a shell: for portable scripts.

Related guides

How to Use a Matrix Build in GitHub ActionsUse a build matrix in GitHub Actions to run one job across many versions in parallel with strategy.matrix, fa… How to Exclude and Include Matrix Combinations in GitHub ActionsRefine a GitHub Actions matrix with exclude to drop combinations and include to add or extend specific ones,…