CI/CD expressions

CI/CD expressions enable dynamic configuration in your CI/CD pipelines by referencing variables and inputs in specialized contexts. GitLab evaluates expressions in the pipeline configuration before the pipeline is created.

Configuration expressions

Configuration expressions use the $[[ ]] syntax and are evaluated at pipeline creation time (compile-time). They enable dynamic configuration based on different contexts.

All configuration expressions share these characteristics:

  • Compile-time evaluation: Values are resolved when the pipeline configuration is created, not during job execution. A large number of expressions can increase pipeline creation time, but does not affect job execution time.
  • Static resolution: Cannot perform dynamic logic or access runtime job state.

Configuration expressions support different contexts for accessing values:

ContextSyntaxAvailabilityPurpose
Inputs context$[[ inputs.INPUT_NAME ]]GitLab 17.0Reference CI/CD inputs in reusable configurations.
Matrix context$[[ matrix.IDENTIFIER ]]GitLab 18.6 (Beta)Reference parallel:matrix identifiers in job dependencies.

Inputs context

Use the inputs. context to reference CI/CD inputs in reusable configurations using $[[ inputs.INPUT_NAME ]] syntax.

For example:

spec:
  inputs:
    environment:
      default: production
    job-stage:
      default: test
---
scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

input. expressions have the following characteristics:

  • Type validation: Supports string, number, boolean, and array types with validation. Input validation prevents pipeline creation with invalid values.
  • Function support: Predefined functions like expand_vars and truncate can manipulate values.
  • Scope: Available in the file where defined, or passed explicitly with include:inputs.

Matrix context

On GitLab Self-Managed, by default this feature is not available. To make it available, an administrator can enable the feature flag named ci_matrix_expressions. On GitLab.com and GitLab Dedicated, this feature is not available. This feature is not ready for production use.

Use the matrix. context to reference parallel:matrix values by using a $[[ matrix.IDENTIFIER ]] syntax. Use it in job dependencies to enable dynamic 1:1 mappings between parallel:matrix jobs.

For example:

.os-arch-matrix:
  parallel:
    matrix:
      - OS: [ubuntu, alpine]
        ARCH: [amd64, arm64]

build:
  script: echo "Testing $OS on $ARCH"
  parallel: !reference [.os-arch-matrix, parallel]

test:
  script: echo "Testing $OS on $ARCH"
  parallel: !reference [.os-arch-matrix, parallel]
  needs:
    - job: build
      parallel:
        matrix:
          - OS: ['$[[ matrix.OS ]]']
            ARCH: ['$[[ matrix.ARCH ]]']

matrix. expressions have the following characteristics:

  • Scoped to job-level parallel:matrix: Only values from the current job can be referenced.
  • Automatic mapping: Creates 1:1 dependencies between matrix jobs across stages