# ワークフローでのジョブのバリエーションの実行

マトリックスを作成して、各ジョブのバリエーションを定義します。

## マトリックス戦略について

マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。 たとえば、マトリックス戦略を使用して、複数バージョンの言語または複数のオペレーティング システムでコードをテストできます。

## ワークフロー ジョブへのマトリックス戦略の追加

`jobs.<job_id>.strategy.matrix` を使用して、さまざまなジョブの設定のマトリックスを定義します。 マトリックス内で、1 つ以上の変数と、それに続く値の配列を定義します。 たとえば、次のマトリックスには、値 `version` を伴う `[10, 12, 14]` という名前の変数と、値 `os` を伴う `[ubuntu-latest, windows-latest]` という名前の変数があります。

```yaml
jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]
```

ジョブは、変数の可能な組み合わせごとに実行されます。 この例のワークフローでは 6 つのジョブが、`os` 変数と `version` 変数の組み合わせごとに 1 つずつ実行されます。

上記のマトリックスでは、次の順序でジョブが作成されます。

* `{version: 10, os: ubuntu-latest}`
* `{version: 10, os: windows-latest}`
* `{version: 12, os: ubuntu-latest}`
* `{version: 12, os: windows-latest}`
* `{version: 14, os: ubuntu-latest}`
* `{version: 14, os: windows-latest}`

参考情報と例については、「[GitHub Actions　のワークフロー構文](/ja/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrix)」をご覧ください。

## コンテキストを使ったマトリックスの作成

ワークフローの実行、変数、ランナー環境、ジョブ、ステップに関する情報を含むマトリックスを作成するには、 `${{ <context> }}` 式構文を使用してコンテキストにアクセスします。 コンテキストについて詳しくは、「[コンテキスト リファレンス](/ja/actions/reference/workflows-and-actions/contexts)」をご覧ください。

たとえば、次のワークフローは `repository_dispatch` イベントをトリガーし、イベント ペイロードからの情報を使用してマトリックスを構築します。 次のようなペイロードを使用してリポジトリのディスパッチ イベントが作成されると、マトリックス `version` 変数の値は `[12, 14, 16]` になります。
`repository_dispatch` トリガーの詳細については、「[ワークフローをトリガーするイベント](/ja/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch)」を参照してください。

```json
{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}
```

```yaml
on:
  repository_dispatch:
    types:
      - test

jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.version }}
```

## マトリックス構成の展開または追加

既存のマトリックス構成を拡張したり、新しい構成を追加したりするには、`jobs.<job_id>.strategy.matrix.include` を使います。
`include` の値は、オブジェクトのリストです。

たとえば、次のマトリックスについて考えます。

```yaml
strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat
```

これは、次のマトリックスの組み合わせを持つ 6 つのジョブになります。

* `{fruit: apple, animal: cat, color: pink, shape: circle}`
* `{fruit: apple, animal: dog, color: green, shape: circle}`
* `{fruit: pear, animal: cat, color: pink}`
* `{fruit: pear, animal: dog, color: green}`
* `{fruit: banana}`
* `{fruit: banana, animal: cat}`

各 `include` エントリは、次の方法で適用されました。

* `{color: green}` は、元の組み合わせの一部を上書きせずに追加できるため、元のマトリックスの組み合わせすべてに追加されます。
* `{color: pink, animal: cat}` は、`color:pink` を含む元のマトリックスの組み合わせにのみ `animal: cat` を追加します。 これにより、前の `color: green` エントリによって追加された `include` が上書きされます。
* `{fruit: apple, shape: circle}` は、`shape: circle` を含む元のマトリックスの組み合わせにのみ `fruit: apple` を追加します。
* `{fruit: banana}` は、値を上書きせずに元のマトリックスの組み合わせに追加できないため、追加のマトリックスの組み合わせとして追加されます。
* `{fruit: banana, animal: cat}` は、値を上書きせずに元のマトリックスの組み合わせに追加できないため、追加のマトリックスの組み合わせとして追加されます。 この組み合わせは、元のマトリックスの組み合わせの 1 つではないため、`{fruit: banana}` マトリックスの組み合わせには追加されません。

リファレンス構成と構成例については、「[GitHub Actions　のワークフロー構文](/ja/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixinclude)」をご覧ください。

## マトリックス構成を除外する

マトリックスで定義されている特定の構成を削除するには、`jobs.<job_id>.strategy.matrix.exclude` を使用します。

たとえば、次のワークフローでは 9 つのジョブが実行されます。12 個の構成ごとに 1 つのジョブで、`{os: macos-latest, version: 12, environment: production}` と一致する 1 つのジョブと、`{os: windows-latest, version: 16}` と一致する 2 つのジョブが除外されます。

```yaml
strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}
```

参考情報については、「[GitHub Actions　のワークフロー構文](/ja/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymatrixexclude)」をご覧ください

## 出力を使って 2 つのマトリックスを定義する

1 つのジョブからの出力を使用して、複数のジョブのマトリックスを定義できます。

たとえば、次のワークフローは、1 つのジョブで値のマトリックスを定義し、2 番目のジョブでそのマトリックスを使用して成果物を生成し、3 番目のジョブでそれらの成果物を使用する方法を示しています。 各成果物は、マトリックスの値に関連付けられます。

```yaml copy
name: shared matrix
on:
  push:
  workflow_dispatch:

jobs:
  define-matrix:
    runs-on: ubuntu-latest

    outputs:
      colors: ${{ steps.colors.outputs.colors }}

    steps:
      - name: Define Colors
        id: colors
        run: |
          echo 'colors=["red", "green", "blue"]' >> "$GITHUB_OUTPUT"

  produce-artifacts:
    runs-on: ubuntu-latest
    needs: define-matrix
    strategy:
      matrix:
        color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}

    steps:
      - name: Define Color
        env:
          color: ${{ matrix.color }}
        run: |
          echo "$color" > color
      - name: Produce Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.color }}
          path: color

  consume-artifacts:
    runs-on: ubuntu-latest
    needs:
    - define-matrix
    - produce-artifacts
    strategy:
      matrix:
        color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}

    steps:
    - name: Retrieve Artifact
      uses: actions/download-artifact@v5
      with:
        name: ${{ matrix.color }}

    - name: Report Color
      run: |
        cat color
```

## エラー処理

ジョブ エラーの処理方法を制御するには、`jobs.<job_id>.strategy.fail-fast` と `jobs.<job_id>.continue-on-error` を使います。

`jobs.<job_id>.strategy.fail-fast` と `jobs.<job_id>.continue-on-error` は一緒に使用できます。 たとえば、次のワークフローは 4 つのジョブを開始します。 ジョブごとに、`continue-on-error` は `matrix.experimental` の値によって決定されます。
`continue-on-error: false` のいずれかのジョブが失敗すると、進行中またはキューに入っているすべてのジョブがキャンセルされます。
`continue-on-error: true` のジョブが失敗した場合、他のジョブは影響を受けません。

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true
```

参考情報については、「[`jobs.<job_id>.strategy.fail-fast`](/ja/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategyfail-fast)」と「[`jobs.<job_id>.continue-on-error`](/ja/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idcontinue-on-error)」をご覧ください。

## 同時ジョブの最大数の定義

`matrix` ジョブ戦略を使うとき、同時に実行できるジョブの最大数を設定するには、`jobs.<job_id>.strategy.max-parallel` を使います。

たとえば、次のワークフローでは、6 つのジョブすべてを一度に実行できるランナーがある場合でも、一度に最大 2 つのジョブを実行します。

```yaml
jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]
```

参考情報については、「[GitHub Actions　のワークフロー構文](/ja/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategymax-parallel)」をご覧ください。