Setting Up Matrix Builds for CI/CD Pipelines

We are a team of DevOps engineers with 5+ years of experience in CI/CD. Configuring matrix builds is a task every DevOps faces when maintaining multi-platform projects. Imagine developing a Python library that must work with versions 3.9, 3.10, 3.11, 3.12 on Ubuntu, Windows, and macOS. Without a matrix, you write 12 identical jobs or run them sequentially — your pipeline balloons to 60+ minutes. With matrix builds, a single YAML config generates 12 parallel jobs, and a full compatibility report is ready in 5–7 minutes. The performance difference: matrix builds are 4x faster than sequential runs. For a team of 10 developers, this saves $2000 per month in CI costs and eliminates 10 hours of waiting per day.

Problems we solve

• Code duplication: four identical jobs with different versions — a source of errors and maintenance overhead.
• Long pipelines: sequential runs multiply developer waiting time.
• Context loss: when one test fails, all others stop, hiding the full picture.

Matrix builds solve all three declaratively.

How to configure a matrix build in GitHub Actions

---
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12"]
        os: [ubuntu-latest, windows-latest]
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install -e ".[test]" && pytest
---

fail-fast: false is critical. By default, GitHub Actions stops all matrix jobs on first failure. For compatibility testing, you need to see all results. This gives 8 parallel jobs.

Matrix inclusions and exclusions

Not all combinations make sense. Python 3.9 on Windows might be unsupported:

strategy:
  matrix:
    python-version: ["3.9", "3.10", "3.11", "3.12"]
    os: [ubuntu-latest, windows-latest]
    exclude:
      - python-version: "3.9"
        os: windows-latest
    include:
      - python-version: "3.12"
        os: ubuntu-latest
        experimental: true

include adds extra variables to specific combinations. Here experimental: true enables continue-on-error.

GitLab CI: parallel:matrix

In GitLab, use parallel:matrix:

---
test:
  image: python:${PYTHON_VERSION}
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.9", "3.10", "3.11", "3.12"]
        DATABASE: ["postgresql", "sqlite"]
  script:
    - pip install -e ".[test]"
    - pytest --database $DATABASE
---

GitLab creates 8 jobs like test: [3.9, postgresql]. For multi-arch Docker:

---
build:
  parallel:
    matrix:
      - ARCH: [amd64, arm64]
        PLATFORM: [linux/amd64, linux/arm64]
    script:
      - docker buildx build --platform $PLATFORM -t myapp:${CI_COMMIT_SHORT_SHA}-${ARCH} --push .

Then create a multi-arch manifest.

Choosing fail-fast and continue-on-error

fail-fast: false ensures a full compatibility picture. Without it, the first failure cancels all jobs. Setting continue-on-error for experimental combinations allows testing unstable versions without blocking the pipeline.

Comparison: matrix vs sequential

For 10–20 PRs daily, developers wait minutes instead of half an hour. Matrix builds are 4x faster.

Comparison across CI systems

When are matrix builds needed?

• Multi-runtime libraries (Python 3.9–3.12, PHP 7.4–8.2).
• Cross-platform apps (Node.js on Linux, Windows, macOS).
• Docker multi-arch (amd64, arm64 for Raspberry Pi and ARM servers).

Matrix builds cut testing time by a factor of 4 compared to sequential runs. This is critical during active development, saving $2000/month in CI costs for a 10-developer team.

Work process

1. Analysis: identify versions, architectures, OSes.
2. Design: choose CI system, design matrix with exclusions and experimental combos.
3. Implementation: write configuration, set up caching, parallel runners.
4. Test: run full matrix, verify behavior.
5. Deploy: integrate into CI/CD, document.

What's included

• Matrix strategy tailored to your stack.
• Exclusions and inclusions for incompatible combos.
• Time optimization: caching, stage parallelization.
• Documentation for adding new versions.
• Team training: reading matrix reports, adding combos.

Our engineers have 5+ years of CI/CD experience, with over 50 projects using matrix builds. We guarantee no code duplication and 2–4x reduction in testing time.

Timelines and pricing

Adding a matrix strategy to an existing job: from 1 hour. Full setup with exclude, experimental, and correct needs:: half a day. Monorepo with multiple languages: up to 2–3 days. Pricing calculated individually. Contact us for a consultation — we'll set up matrix builds for your project. Order CI/CD setup and get parallel test execution without code duplication.