正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

GitLab CI/CDでのジョブマトリックス式

マトリックス式を使用すると、parallel:matrix識別子に基づいて動的なジョブ依存関係を有効にし、parallel:matrixジョブ間に1対1マッピングを作成できます。

マトリックス式には、入力式と比較していくつかの制限があります:

  • コンパイル時のみ: 識別子は、ジョブの実行中ではなく、パイプラインの作成時に解決されます。
  • 文字列の置換のみ: 複雑なロジックや変換はありません。
  • マトリックス識別子のみ: CI/CD変数または入力を参照できません。

構文

マトリックス式は、$[[ 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つのジョブを作成します: 3つのPLATFORM値のみ。
  • 各build_projectジョブは、すべてのプラットフォーム（PLATFORM）のNode.js 18（VERSION）のみに依存します。

または、すべての依存関係を手動で設定することもできます。