How to Use Github Actions Matrix Strategy to Run Parallel Multi-platform and Multi-version CI Builds

ByAkensai

Learning how to use GitHub Actions matrix strategy to run parallel multi-platform and multi-version CI builds is one of the best ways to speed up your development pipeline. Instead of running tests one at a time, the matrix strategy lets you test across multiple operating systems and language versions simultaneously. This cuts your CI time dramatically. In this tutorial, you’ll set up a real workflow file, define a matrix, and watch your builds run in parallel. By the end, you’ll have a reusable CI configuration that tests your code on Ubuntu, macOS, and Windows , across multiple Node.js or PHP versions , all at once.

Prerequisites and Requirements for Parallel CI Builds

Before you start, make sure you have the following in place:

– A GitHub account with a repository ready to use
– Basic familiarity with YAML syntax
– A project that uses Node.js, PHP, or Python (examples below use Node.js)
– GitHub Actions enabled on your repository (it’s on by default for public repos)
– Estimated time to complete: 20–30 minutes

You don’t need to install anything locally. All the configuration happens inside a YAML file you commit to your repository. GitHub handles the rest. If you’re new to GitHub Actions, review the official GitHub Actions workflow syntax documentation before continuing. It covers the core concepts you’ll need.

Step-by-Step Guide to Using the GitHub Actions Matrix Strategy

You might also find this useful: How to Create a Wordpress Block Theme From Scratch Using the Create Block Theme Plugin

Follow these steps carefully. Each one builds on the previous.

Step 1: Create your workflow directory

Navigate to the root of your repository. Create the required directory structure for GitHub Actions.

mkdir -p .github/workflows

GitHub automatically detects workflow files inside this folder. Every YAML file here becomes a separate workflow.

Step 2: Create your workflow file

Create a new file called ci.yml inside the workflows directory.

touch .github/workflows/ci.yml

Open this file in your editor. You’ll add your entire CI configuration here.

Step 3: Define the workflow trigger

Add the following at the top of ci.yml. This tells GitHub when to run your workflow.

name: CI Matrix Build

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

This triggers the workflow on every push or pull request to the main branch. You can adjust the branch names to match your project.

Step 4: Define the matrix strategy

This is the core of the tutorial. Add a job with a matrix that covers multiple platforms and versions.

jobs:
  build:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [16, 18, 20]

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

Here’s what’s happening. The strategy.matrix block defines two variables: os and node-version. GitHub Actions creates a separate job for every combination. With 3 operating systems and 3 Node.js versions, you get 9 parallel jobs. Each job checks out your code, sets up the correct Node.js version, installs dependencies, and runs your tests.

Step 5: Add matrix exclusions (optional)

Sometimes certain combinations don’t make sense. You can exclude specific pairs using the exclude keyword.

    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [16, 18, 20]
        exclude:
          - os: windows-latest
            node-version: 16

This removes the Windows + Node 16 combination from the matrix. You now have 8 jobs instead of 9.

Step 6: Add a fast-fail setting

By default, GitHub cancels all remaining matrix jobs if one fails. You can disable this behavior.

    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [16, 18, 20]

Setting fail-fast: false lets all jobs complete even if one fails. This is useful when you want a full picture of failures across all platforms.

Step 7: Commit and push your workflow

Save your file and push it to GitHub.

git add .github/workflows/ci.yml
git commit -m "Add matrix CI workflow"
git push origin main

Go to your repository on GitHub. Click the Actions tab. You’ll see your workflow running with all matrix jobs listed in parallel. Each job shows its OS and Node.js version clearly.

Step 8: Add a custom environment variable per matrix entry

You can include extra variables in your matrix. This is useful for passing custom config values.

    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            node-version: 20
            env_label: production
          - os: macos-latest
            node-version: 18
            env_label: staging

Then reference ${{ matrix.env_label }} anywhere in your steps. The include keyword adds new combinations without replacing your base matrix.

Troubleshooting Common Issues with Matrix CI Builds

Jobs aren’t running in parallel
Check that you haven’t set max-parallel to 1. Remove that line or increase the value. GitHub runs matrix jobs in parallel by default.

Windows jobs fail on shell commands
Windows runners use PowerShell by default. Add shell: bash to your steps if you’re using bash syntax.

      - name: Run script
        shell: bash
        run: ./scripts/build.sh

Dependency cache isn’t working across matrix jobs
Each matrix combination is a separate runner. Use the cache input with actions/setup-node to cache dependencies per combination.

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

YAML indentation errors
YAML is strict about spaces. Use a YAML linter before pushing. The official YAML specification explains the formatting rules in detail.

Matrix produces too many jobs
GitHub limits free accounts to 20 concurrent jobs. Use max-parallel to stay within your plan’s limits.

    strategy:
      max-parallel: 6
      matrix:
        os: [ubuntu-latest, macos-latest]
        node-version: [18, 20]

Conclusion

You now know how to use GitHub Actions matrix strategy to run parallel multi-platform and multi-version CI builds from start to finish. You created a workflow file, defined a matrix across operating systems and language versions, handled exclusions, and fixed common issues. Your CI pipeline now runs faster and catches platform-specific bugs before they reach production. From here, you can extend this setup by adding Docker-based builds, deploying to staging environments after tests pass, or integrating with code coverage tools. The matrix strategy scales well as your project grows. Apply the same pattern to PHP, Python, or any other runtime your stack uses.

Similar Posts