How to use matrix builds in GitHub Actions?

Short answer

Matrix builds in GitHub Actions run a job multiple times with different combinations of variables. They are useful for testing across operating systems, language versions, and dependency sets.

Steps

1. Define a strategy.matrix in the job.
2. Reference matrix variables in steps.
3. GitHub Actions spawns a job for each combination.

Example

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [16, 18, 20]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Tips

• Use fail-fast: false to run all combinations even if one fails.
• Exclude specific combinations with exclude.
• Include additional combinations with include.

Common issues

• Large matrices consume many runner minutes.
• Cross-platform shell differences can cause script failures.
• Matrix variables must be referenced correctly with ${{ matrix.var }}.