Skip to content

Add matrix expressions

What does this MR do and why?

This MR implements a $[[ matrix.VARIABLE_NAME ]] CI expression syntax to enable dynamic job dependencies based on matrix values in needs:parallel:matrix configurations. This allows users to create 1:1 mappings between matrix jobs across pipeline stages without manual duplication.

Because this change is being made to a critical, high traffic part of the code, we'll derisk the deployment using a feature flag.

Note: The documentation for this feature will be added in a subsequent MR.

Issue: Support dynamic job dependencies in `needs:para... (#423553)

Rollout issue: [FF] Rollout ci_matrix_expressions gitlab_com_d... (#571105)

How to set up and validate locally

Enable ci_matrix_expressions feature flag!

Use this config to test that the new matrix expressions work and that existing uses of needs are not broken:

stages:
  - build
  - test
  - package

# Shared matrix definition
.platform_matrix: &platform_matrix
  parallel:
    matrix:
      - OS: ["ubuntu", "alpine"]
        VERSION: ["16", "18"]

# 1. Job with matrix but NO expressions (traditional approach)
build_base:
  stage: build
  script:
    - echo "Building base on $OS with version $VERSION"
    - echo "Base build complete"
  <<: *platform_matrix

# 2. Job with matrix AND expressions (new feature)
test_app:
  stage: test
  script:
    - echo "Testing app on $OS with version $VERSION"
    - echo "Tests complete"
  needs:
    - job: build_base
      parallel:
        matrix:
          - OS: $[[ matrix.OS ]]
            VERSION: $[[ matrix.VERSION ]]
  <<: *platform_matrix

# 3. Job using needs:parallel:matrix but NO expressions (manual specification)
validate_app:
  stage: test
  script:
    - echo "Validating app on $OS with version $VERSION"
    - echo "Validation complete"
  needs:
    - job: build_base
      parallel:
        matrix:
          - OS: ubuntu
            VERSION: 16
          - OS: alpine
            VERSION: 18
  <<: *platform_matrix

# 4. Job without matrix (baseline)
package_release:
  stage: package
  script:
    - echo "Creating release package"
    - echo "Package complete"
  needs:
    - job: test_app

The pipeline should look like this:

Screenshot 2025-09-17 at 17.32.08.png

Update any of the matrix expressions to a non-existent value and you should see this error when validating the config:

This GitLab CI configuration is invalid: JOB_NAME: Matrix value 'NON_EXISTENT_VALUE' does not exist in matrix configuration.

Edited by Avielle Wolfe

Merge request reports

Loading