# Gitlab Matrix Expressions

> Use GitLab CI/CD Matrix Expressions to create dynamic 1:1 dependencies between parallel matrix jobs. This simplifies pipeline configuration by avoiding the manual listing of every job combination in `needs`. Use when this capability is needed.

- Skill: `tomevault-io/gitlab-matrix-expressions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/gitlab-matrix-expressions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/gitlab-matrix-expressions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/gitlab-matrix-expressions

---


# GitLab Matrix Expressions

Matrix expressions allow you to define dependencies between jobs that use `parallel:matrix` without manually listing every possible combination. This creates a "1:1 mapping" where a downstream job only waits for the specific upstream job that matches its matrix variables (e.g., `linux:test` waits only for `linux:build`, not `windows:build`).

## Syntax

The syntax uses the `matrix` context to reference the current job's matrix identifiers.

```yaml
'$[[ matrix.IDENTIFIER ]]'

```

> **Note:** The quotes `'` around the expression are required to ensure valid YAML parsing.

## Usage Patterns

### 1. Basic 1:1 Dependency

Use this pattern when you have two jobs (e.g., Build and Test) that run on the same matrix (e.g., multiple providers) and you want them to stay synchronized.

```yaml
linux:build:
  stage: build
  script: echo "Building..."
  parallel:
    matrix:
      - PROVIDER: [aws, gcp]

linux:test:
  stage: test
  script: echo "Testing..."
  parallel:
    matrix:
      - PROVIDER: [aws, gcp]
  needs:
    - job: linux:build
      parallel:
        matrix:
          # This maps the current job's PROVIDER to the upstream job's PROVIDER
          - PROVIDER: ['$[[ matrix.PROVIDER ]]']

```

**Result:** `linux:test [aws]` only waits for `linux:build [aws]`.

### 2. Using YAML Anchors (DRY Principle)

For complex matrices, define the matrix once in a hidden job or anchor to avoid repetition and errors.

```yaml
.build_matrix: &build_matrix
  parallel:
    matrix:
      - OS: ["ubuntu", "alpine"]
        ARCH: ["amd64", "arm64"]

compile_binary:
  <<: *build_matrix
  stage: compile
  script: echo "Compiling..."

integration_test:
  <<: *build_matrix
  stage: test
  needs:
    - job: compile_binary
      parallel:
        matrix:
          - OS: ['$[[ matrix.OS ]]']
            ARCH: ['$[[ matrix.ARCH ]]']

```

### 3. Subset Dependencies

You can mix matrix expressions with static values to depend on a specific subset of upstream jobs.

```yaml
needs:
  - job: prepare_env
    parallel:
      matrix:
        # Match the platform dynamically
        - PLATFORM: ['$[[ matrix.PLATFORM ]]']
          # But only depend on the specific Node version '18'
          VERSION: ["18"] 

```

## Limitations

* **Compile-time only:** Identifiers are resolved when the pipeline is created. You cannot use runtime variables.
* **String replacement only:** You cannot perform arithmetic or complex logic inside `[[ ... ]]`.
* **Scope:** You can only reference identifiers defined in the *current* job's `parallel:matrix` section.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/mreimbold) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->