Parallel Matrix Builds in GitLab CI

Parallel Matrix Builds

GitLab CI's parallel:matrix keyword automatically generates multiple job instances from variable combinations. This is ideal for testing across versions, platforms, or feature flags.

Testing Across Node.js Versions

test:
  stage: test
  image: node:$NODE_VERSION-alpine
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
  script:
    - npm ci
    - npm test

This generates three jobs: test 1/3, test 2/3, test 3/3, each with a different Node.js version.

Multi-Dimensional Matrix

test:
  stage: test
  image: python:$PYTHON_VERSION-slim
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.10", "3.11", "3.12"]
        DATABASE: ["postgres", "mysql"]
  services:
    - name: $DATABASE
  script:
    - pip install -r requirements.txt
    - pytest

This generates 6 jobs (3 Python versions x 2 databases), covering all combinations.

Platform Cross-Compilation

build:
  stage: build
  image: golang:1.22
  parallel:
    matrix:
      - GOOS: [linux, darwin, windows]
        GOARCH: [amd64, arm64]
  script:
    - go build -o app-$GOOS-$GOARCH ./cmd/server
  artifacts:
    paths:
      - app-*

Limits and Best Practices

• Maximum 50 jobs per matrix (GitLab limit).
• Each job gets its own log and can fail independently.
• Use allow_failure on experimental versions (e.g., Node.js nightly).
• Matrix variables are visible in the job name in the GitLab UI, making failures easy to identify.