Q: What is a build matrix in CI?
Run the same job with multiple combinations of parameters (OS, Python version, Node version). Useful for testing cross-compatibility.
Want to master this scenario in a live sandbox? KodeKloud's Enterprise GitOps with ArgoCD & Kubernetes Rollouts covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: A <strong>build matrix in CI</strong> is a way to define one job template and have the CI system expand it into many parallel jobs, one for every combination of variables such as operating system, language version or database. It replaces copy-pasted jobs and proves your code works on every supported target. Interviewers ask about it to see if you can balance coverage against cost, handle failures sensibly, and avoid traps like unstable required status check names and cache collisions between matrix legs.
Mental model: one template, many jobs
The matrix is the cartesian product of the variables you list, minus exclusions, plus inclusions.
- Expansion: Two operating systems and three Node versions produce six jobs. Each job gets its own runner, workspace and result.
- Independence: Legs share nothing unless you pass artifacts or caches, which makes them safe to run in parallel.
- Good fits: Library compatibility (Python 3.10 to 3.12), cross-OS builds, multiple Kubernetes versions for chart tests, or per-service builds in a monorepo.
- Bad fits: Huge cartesian products. Ten versions across four OS and three databases is 120 jobs, so prune to the combinations users actually run.
- Variables beyond version: A matrix can also carry feature flags, target architectures or cloud regions, and
includelets one leg carry extra settings such as a coverage upload flag.
Hands-on: build matrix in GitHub Actions and GitLab CI
Define the matrix once and reference its values with matrix.<name>.
# .github/workflows/ci.yml
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
max-parallel: 4
matrix:
os: [ubuntu-latest, windows-latest]
node: [18, 20, 22]
exclude:
- os: windows-latest
node: 18
include:
- os: ubuntu-latest
node: 22
coverage: true
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
cache: npm
- run: npm ci && npm test
# .gitlab-ci.yml
test:
image: python:$PY
parallel:
matrix:
- PY: ["3.10", "3.11", "3.12"]
script: [pip install -r requirements.txt, pytest]
- GitHub Actions: Put
strategy.matrixunder the job and reference values as${{ matrix.node }}. - Exclude and include:
excluderemoves unsupported pairs;includeadds extra legs or extra variables for one combination. - fail-fast and max-parallel:
fail-fast: falselets all legs finish so you see every failure;max-parallelcaps concurrency to protect runner quotas. - GitLab CI: Use
parallel: matrix:with lists of values; each combination becomes its own job. - Dynamic values: You can reference matrix values in names, environment variables and conditions, for example
if: matrix.coverageto run an upload step on one leg only.
Verify the matrix expanded the way you intended
Check job names, counts and cache behaviour before trusting green checks.
# Aggregate gate job: use this single name as the required status check
ci-ok:
needs: [test]
if: always()
runs-on: ubuntu-latest
steps:
- run: |
if [ "${{ needs.test.result }}" != "success" ]; then
echo "matrix failed: ${{ needs.test.result }}"; exit 1
fi
# Per-leg cache key including matrix values
# key: ${{ runner.os }}-node${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}
- Count the legs: The Actions run page lists each combination in the job name, for example
test (ubuntu-latest, 20); confirm excluded pairs are absent. - Print the context: Add a debug step that echoes
matrix.osand the tool version so each leg proves what it ran on. - Cache keys: Include matrix values in cache keys, such as
key: ${{ runner.os }}-node${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}, so legs do not restore incompatible dependencies. - Artifact names: In
actions/upload-artifact@v4, artifact names must be unique per run, so append the matrix values to the name. - Summary visibility: Write a short job summary per leg with versions and timings so you can spot a slow leg that dominates total pipeline time.
Failure modes and edge cases
Matrices fail in subtle ways, mostly around gating and naming.
- Required checks: Branch protection needs exact check names. If you rename or resize a matrix, required checks become pending forever. Use one aggregate job that depends on all legs.
- Aggregate job pattern: A final job with
needs: [test]andif: always()that fails whenneeds.test.result != 'success'gives branch protection a single stable name. - Flaky legs: With
fail-fast: trueone flaky leg cancels the others and hides real failures; for compatibility testing turn it off. - Experimental legs: Use
continue-on-error: ${{ matrix.experimental }}for nightly or pre-release toolchains so they inform without blocking.
Production practice: cost and signal
Keep the matrix focused so the feedback loop stays fast.
- Tiering: Run a minimal matrix on pull requests and the full matrix on merges or a nightly schedule.
- Dynamic matrices: Generate JSON in a prior job (for example only changed services in a monorepo) and feed it with
fromJSON(needs.plan.outputs.matrix). - Pin versions: Prefer explicit supported versions over
latestso the matrix is reproducible; add a scheduled leg for the newest release to get early warning. - Reuse: Combine the matrix with reusable workflows so the matrix definition lives in one place across repos.
- Review regularly: Drop end-of-life runtimes from the matrix when you stop supporting them, otherwise you pay for jobs that protect nothing.
- A build matrix in CI expands one job definition into parallel jobs for each combination of variables like OS and runtime version.
- I verify the expanded job names, include matrix values in cache keys and artifact names, and check excluded pairs are really gone.
- I automate with tiered matrices, dynamic monorepo matrices and an aggregate gate job for branch protection.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Using fail-fast true for compatibility testing One failing leg cancels the rest, so you only learn about one incompatibility at a time.
- Making each matrix leg a required status check Renaming a version changes the check name and leaves pull requests blocked on a check that never reports.
- Sharing a cache key across legs Legs restore dependencies built for another OS or runtime version and fail in confusing ways.
- Testing every possible combination The job count multiplies and slows feedback without covering combinations users actually run.