How to Build a Matrix Across Different Runner Types

Put runner labels in strategy.matrix and set runs-on to the matrix value to fan one job out across several runner types at once.

A matrix keyed on the runner lets you cover OS, architecture, and size combinations without duplicating the job. Use include to attach per-runner settings and exclude to drop combinations you do not need.

Matrix over runner labels

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

Attach size per leg with include

strategy:
  matrix:
    include:
      - runner: ubuntu-latest
        suite: unit
      - runner: ubuntu-latest-8-cores
        suite: e2e

Watch the cost

Every matrix leg bills at its runner rate, and a macOS or 8-core leg costs a multiple of a standard Linux leg. Keep the matrix as small as the coverage you actually need.

Related guides