Using Matrix Builds

1. Creating Matrix Jobs

Matrix jobs in GitLab CI/CD allow you to run multiple jobs with different configurations in parallel. This is useful for testing your application across different environments, versions, or platforms.

Property	Description	Values
matrix	Defines the matrix configuration for jobs	`strategy: matrix`
include	Allows you to define specific job configurations within the matrix	`include:`
exclude	Allows you to exclude specific job configurations from the matrix	`exclude:`

Example: Basic Matrix Job Configuration

job_name:
  script:
    - echo "Running job"
  matrix:
    include:
      - name: "Test on Ubuntu"
        image: "ubuntu:latest"
      - name: "Test on CentOS"
        image: "centos:latest"

Example: Matrix with Variables

test_job:
  script:
    - echo "Testing on $OS with version $VERSION"
  matrix:
    variables:
      OS: [ubuntu, centos]
      VERSION: [20.04, 22.04]

Note: The matrix strategy is supported in GitLab CI/CD version 15.0 and later.

2. Defining Matrix Variables

Variable	Values	Description
matrix	`['version: 1.0', 'version: 2.0']`	Defines the matrix dimensions for build jobs
strategy	`parallel`	Strategy to run jobs in parallel or sequential

Example: Matrix Variables in .gitlab-ci.yml

job_name:
  script:
    - echo "Running job with matrix variable: $MATRIX_VAR"
  matrix:
    variables:
      MATRIX_VAR: [&#34;value1&#34;, &#34;value2&#34;]

3. Combining Matrix with Variables

Variable Type	Description	Usage Example
CI_PIPELINE_ID	Unique identifier for the pipeline	`$CI_PIPELINE_ID`
CI_JOB_NAME	Name of the current job	`$CI_JOB_NAME`
MATRIX_VAR	Variable defined in the matrix strategy	`$MATRIX_VAR`

Example: Using Matrix Variables in Jobs

jobs:
  build:
    matrix:
      variables:
        NODE_VERSION: [14, 16, 18]
    script:
      - echo "Building with Node.js $NODE_VERSION"

Note: Matrix variables can be used in any part of the job configuration, including script commands and environment settings.

4. Using Matrix for Multi-Platform Builds

Variable	Description	Example
matrix	Defines the build matrix for multi-platform builds	`matrix: { platform: [linux, windows, macos] }`
platform	Target platform for the build	`linux`, `windows`, `macos`

Example: Matrix Configuration for Multi-Platform Builds

build:
  stage: build
  script:
    - echo "Building for $PLATFORM"
  matrix:
    platform: [linux, windows, macos]

Note: The matrix strategy allows you to run the same job across multiple platforms or environments.

Warning: Ensure that your build scripts are compatible with each target platform to avoid failures.

Platform	Support Status	Notes
linux	GOOD	Full support with extensive testing
windows	MODERN	Support available but limited testing
macos	GOOD	Full support with native tooling

5. Using Matrix for Multi-Version Testing

Variable	Description	Example
strategy.matrix	Defines the matrix of build configurations	`strategy: { matrix: { node: ['12', '14', '16'] } }`
strategy.matrix.include	Additional configurations to include in the matrix	`strategy: { matrix: { node: ['12', '14'], include: [{ node: '18', os: 'windows-latest' }] } }`
strategy.matrix.exclude	Configurations to exclude from the matrix	`strategy: { matrix: { node: ['12', '14', '16'], exclude: [{ node: '14' }] } }`

Example: Matrix Build Configuration

jobs:
  test:
    strategy:
      matrix:
        node: ['12', '14', '16']
        os: ['ubuntu-latest', 'windows-latest']
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Note: Matrix builds run in parallel, and each job uses a unique combination of matrix variables.

Example: Including Custom Configurations

jobs:
  test:
    strategy:
      matrix:
        node: ['12', '14']
        include:
          - node: '18'
            os: 'windows-latest'
          - node: '16'
            os: 'macos-latest'
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

Example: Excluding Specific Combinations

jobs:
  test:
    strategy:
      matrix:
        node: ['12', '14', '16', '18']
        os: ['ubuntu-latest', 'windows-latest']
        exclude:
          - node: '12'
            os: 'windows-latest'
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

6. Using Matrix for Cross-Browser Testing

Variable	Values	Description
browser	`chrome`, `firefox`, `safari`	Browser to test against
version	`latest`, `100`, `95`	Version of the browser to use

Example: Matrix Configuration for Cross-Browser Testing

test:
  stage: test
  image: node:18
  script:
    - npm install
    - npm run test:browser
  matrix:
    browser: [chrome, firefox, safari]
    version: [latest, 100]

Note: Ensure that your test environment supports the specified browsers and versions. Some cloud providers like Sauce Labs or BrowserStack may be required for full cross-browser compatibility.

7. Filtering Matrix Combinations

Filter Type	Description	Example
except	Excludes specific matrix combinations	`matrix: include: - ruby: '2.7' rails: '6.0' - ruby: '3.0' rails: '6.1' except: ruby: '2.7' rails: '6.0'`
only	Includes only specific matrix combinations	`matrix: include: - ruby: '2.7' rails: '6.0' - ruby: '3.0' rails: '6.1' only: ruby: '3.0'`

Example: Using `except` to Skip Combinations

test:
  stage: test
  image: ruby:3.0
  services:
    - postgres:13
  variables:
    POSTGRES_DB: test_db
  matrix:
    include:
      - ruby: '2.7'
        rails: '6.0'
      - ruby: '3.0'
        rails: '6.1'
      - ruby: '3.1'
        rails: '7.0'
  except:
    ruby: '2.7'
    rails: '6.0'
  script:
    - gem install bundler
    - bundle install --jobs=$(nproc)
    - bundle exec rspec

Note: The except and only filters work on the full matrix combination, not individual variables.

8. Using Matrix with needs

When using matrix builds in GitLab CI/CD, the needs keyword allows jobs to depend on jobs from different matrix dimensions. This is particularly useful when you want to run a job that aggregates or processes results from multiple matrix jobs.

Property	Description	Values
needs	Specifies the jobs that this job depends on. Can reference matrix jobs using `$CI_JOB_NAME` or `$CI_JOB_ID`.	`array` of job names or IDs

Example: Using needs with matrix jobs

job_with_matrix:
  stage: build
  script:
    - echo "Running matrix job"
  matrix:
    include:
      - variables:
          ENV: dev
      - variables:
          ENV: prod

aggregate_job:
  stage: deploy
  script:
    - echo "Aggregating results"
  needs:
    - job: job_with_matrix
      artifacts: true

Note: The needs keyword supports artifact sharing between matrix jobs, ensuring that dependencies are correctly resolved even when jobs are generated dynamically.

9. Optimizing Matrix Performance

Strategy	Description	Notes
parallelism	`max_parallel: 4`	Limit concurrent jobs to avoid resource exhaustion
cache	`cache: [key: $CI_COMMIT_REF_NAME]`	Reduce redundant setup by reusing artifacts
dependencies	`needs: [build]`	Control job execution order to prevent race conditions

Example: Parallel Jobs with Caching

build:
  stage: build
  script:
    - npm install
    - npm run build
  cache:
    key: "build-cache"
    paths:
      - node_modules/

test:
  stage: test
  script:
    - npm run test
  cache:
    key: "test-cache"
    paths:
      - node_modules/

Note: Matrix jobs can quickly consume resources; use max_parallel to control concurrency.

Warning: Avoid using needs in matrix jobs without proper dependency handling.

10. Debugging Matrix Configurations

Example: Using `echo` to debug matrix values

script:
  - echo "Running job for matrix value: $MATRIX_VAR"
  - echo "Current job name: $CI_JOB_NAME"

Variable	Description	Usage
$CI_JOB_NAME	Current job name including matrix values	Use for logging or conditional logic
$MATRIX_VAR	Value from the matrix configuration	Access specific matrix variable in job

Note: Matrix jobs are named using the pattern <job_name>_<matrix_value>, which can be used to identify specific job instances in logs.

Debugging Workflow

Use echo or print to output matrix variables
Check job names in the CI/CD pipeline logs
Verify that each matrix value is correctly applied to jobs