How to Run a Parallel Test Matrix in GitLab CI

parallel:matrix fans out across versions while parallel:N splits one suite into evenly sized shards.

Use parallel:matrix to multiply a job over variable combinations, or parallel:N plus CI_NODE_INDEX to shard a slow suite across runners.

Matrix across versions

Each NODE_VERSION value spawns its own job in parallel.

.gitlab-ci.yml

test:
  image: node:${NODE_VERSION}
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
  script:
    - npm ci && npm test

Use CI_NODE_INDEX and CI_NODE_TOTAL to split test files across N parallel jobs.

.gitlab-ci.yml

unit:
  parallel: 4
  script:
    - npx jest --shard=${CI_NODE_INDEX}/${CI_NODE_TOTAL}