How to Run a Matrix / Parallel Build in GitLab CI

GitLab expands one job into many with parallel:matrix, or splits a test suite with parallel: N.

Use parallel:matrix: to run a job once per combination of variables, or parallel: N plus CI_NODE_INDEX/CI_NODE_TOTAL to shard tests.

Matrix across versions

Each combination becomes its own parallel job, with the matrix vars available as env vars.

test:
  image: node:${NODE_VERSION}
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
        SUITE: [unit, integration]
  script:
    - npm run test:$SUITE

Split a test suite

Run N copies and shard by index for faster wall-clock time.

test:
  parallel: 4
  script:
    - npm test -- --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL

Gotchas

• Each matrix combination consumes a runner slot - large matrices can exhaust concurrency.
• Matrix variable values must be strings; quote numbers like "20".
• For parallel: N, your test runner must understand CI_NODE_INDEX/CI_NODE_TOTAL or you will run the full suite N times.

Related guides