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:
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.