How to Run Matrix Jobs With parallel:matrix in GitLab CI/CD

parallel:matrix clones a job once per combination of the listed variables, each running in parallel.

Add parallel:matrix with one or more variables, each holding a list of values. GitLab creates one job per combination and injects the values as variables.

Steps

• Add parallel:matrix with a list of variable maps.
• Reference the variables in script or image.
• Each combination runs as its own parallel job instance.

Pipeline

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

Gotchas

• Total jobs equal the product of every list, so large matrices consume many runner slots.
• A downstream needs: on a matrix job must use needs:parallel:matrix to pick a specific combination.

Related guides