GitLab CI/CD의 매트릭스 표현식

GitLab CI/CD의 매트릭스 표현식 (Matrix expressions in GitLab CI/CD)

GitLab 18.6에서 도입됐어요.

매트릭스 표현식은 parallel:matrix 식별자에 기반한 동적 잡 의존성을 가능하게 해서, parallel:matrix 잡 간에 1:1 매핑을 만들 수 있어요.

매트릭스 표현식은 입력 표현식과 비교해 몇 가지 제한이 있어요:

컴파일 시점 전용: 식별자는 잡 실행 중이 아니라 파이프라인이 생성될 때 해석돼요.
문자열 치환 전용: 복잡한 로직이나 변환은 없어요.
매트릭스 식별자 전용: CI/CD 변수나 입력은 참조할 수 없어요.

출처: 문서

본문

구문 (Syntax)

매트릭스 표현식은 $[[ matrix.IDENTIFIER ]] 구문을 사용해 잡 의존성에서 parallel:matrix 식별자를 참조해요. 예를 들면:

needs:
  - job: build
    parallel:
      matrix:
        - OS: ['$[[ matrix.OS ]]']
          ARCH: ['$[[ matrix.ARCH ]]']

`needs:parallel:matrix`에서의 매트릭스 표현식

잡 의존성에서 매트릭스 식별자를 동적으로 참조하는 데 매트릭스 표현식을 사용할 수 있어서, 모든 조합을 수동으로 지정하지 않고도 매트릭스 잡 간에 1:1 매핑을 만들 수 있어요.

예를 들면:

linux:build:
  stage: build
  script: echo "Building linux..."
  parallel:
    matrix:
      - PROVIDER: [aws, gcp]
        STACK: [monitoring, app1, app2]

linux:test:
  stage: test
  script: echo "Testing linux..."
  parallel:
    matrix:
      - PROVIDER: [aws, gcp]
        STACK: [monitoring, app1, app2]
  needs:
    - job: linux:build
      parallel:
        matrix:
          - PROVIDER: ['$[[ matrix.PROVIDER ]]']
            STACK: ['$[[ matrix.STACK ]]']

이 예시는 모든 linux:build와 linux:test 잡 사이에 1:1 의존성 매핑을 만들어요:

linux:test: [aws, monitoring]은 linux:build: [aws, monitoring]에 의존
linux:test: [aws, app1]은 linux:build: [aws, app1]에 의존
같은 방식이 6개 parallel:matrix 값 조합 모두에 적용돼요.

matrix. 표현식을 사용하면 각 매트릭스 조합을 일일이 지정할 필요가 없어요.

매트릭스 표현식은 현재 잡의 매트릭스 구성에서만 식별자를 참조해요.

YAML 앵커로 `parallel:matrix` 구성 재사용하기

YAML 앵커를 사용하면 복잡한 parallel:matrix 구성과 의존성이 있는 여러 잡에 걸쳐 parallel:matrix 구성을 재사용할 수 있어요.

예를 들면:

stages:
  - compile
  - test
  - deploy

.build_matrix: &build_matrix
  parallel:
    matrix:
      - OS: ["ubuntu", "alpine"]
        ARCH: ["amd64", "arm64"]
        VARIANT: ["slim", "full"]

compile_binary:
  stage: compile
  script:
    - echo "Compiling for $OS-$ARCH-$VARIANT"
  <<: *build_matrix

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

deploy_artifact:
  stage: deploy
  script:
    - echo "Deploying $OS-$ARCH-$VARIANT"
  <<: *build_matrix
  needs:
    - job: integration_test
      parallel:
        matrix:
          - OS: ['$[[ matrix.OS ]]']
            ARCH: ['$[[ matrix.ARCH ]]']
            VARIANT: ['$[[ matrix.VARIANT ]]']

이 구성은 24개 잡을 만들어요: 각 스테이지에 8개 잡(2 OS × 2 ARCH × 2 VARIANT 조합)이며, 스테이지 간 1:1 의존성이 있어요.

값의 부분 집합 사용하기

매트릭스 표현식을 특정 값과 결합해 선택적인 의존성 부분 집합을 만들 수 있어요:

stages:
  - prepare
  - build
  - test

.full_matrix: &full_matrix
  parallel:
    matrix:
      - PLATFORM: ["linux", "windows", "macos"]
        VERSION: ["16", "18", "20"]

.platform_only: &platform_only
  parallel:
    matrix:
      - PLATFORM: ["linux", "windows", "macos"]

prepare_env:
  stage: prepare
  script:
    - echo "Preparing $PLATFORM with Node.js $VERSION"
  <<: *full_matrix

build_project:
  stage: build
  script:
    - echo "Building on $PLATFORM"
  needs:
    - job: prepare_env
      parallel:
        matrix:
          - PLATFORM: ['$[[ matrix.PLATFORM ]]']
            VERSION: ["18"]  # Only depend on Node.js 18 preparations
  <<: *platform_only

이 예시에서:

prepare_env는 parallel:matrix로 9개 잡을 만들어요: 3 PLATFORM × 3 VERSIONS.
build_project는 parallel:matrix로 3개 잡을 만들어요: PLATFORM 값 3개만.
각 build_project 잡은 모든 플랫폼(PLATFORM)에 대해 Node.js 18(VERSION) 준비에만 의존해요.

또는 모든 의존성을 수동으로 구성할 수도 있어요.

더 알아보기

다음으로는 parallel:matrix와 needs 문서를 함께 보면, 대규모 병렬 잡 간의 1:1 의존성을 효율적으로 구성하는 방법을 익힐 수 있어요.

GitLab CI/CD의 매트릭스 표현식