ジョブにマトリックスを使用する

注: GitHub ホステッドランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。

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

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

マトリックス戦略の使用

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

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

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

既定で、GitHub Enterprise Server は、ランナーの可用性に応じて並列実行されるジョブの数を最大化します。マトリックス内の変数の� �序によって、ジョブが作成される� �序が決まります。定義する最初の変数は、ワークフローの実行で最初に作成されるジョブになります。たとえば、上記のマトリックスでは、次の� �序でジョブが作成されます。

{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}

このマトリックスでは、ワークフローの実行ごとに最大で 256 のジョブが生成されます。この制限は、GitHub Enterprise Server ホストランナーとセルフホステッドランナーの両方に適用されます。

定義した変数は、matrix のコンテキストでのプロパティとなり、ワークフローファイルの他のエリア内のプロパティを参照できます。この例では、matrix.version および matrix.os を使用して、ジョブが使用している version および os の現在の値にアクセスできます。詳細については、「コンテキスト」を参照してく� さい。

例: 1 次元マトリックスの使用

単一の変数を指定して、1 次元のマトリックスを作成できます。

たとえば、次のワークフローでは、変数 version に値 [10, 12, 14] を定義しています。このワークフローでは、変数の値ごとに 1 つずつ、3 つのジョブが実行されます。各ジョブは、matrix.version コンテキストを通して version 値にアクセスし、node-version として actions/setup-node アクションにその値を渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

例: 多次元マトリックスの使用

複数の変数を指定して、多次元マトリックスを作成できます。ジョブは、変数の可能な組み合わせごとに実行されます。

たとえば、次のワークフローでは 2 つの変数を指定しています。

os 変数で指定された 2 つのオペレーティングシステ�
version 変数で指定された 3 つの Node.js バージョン

このワークフローでは、os と version 変数の組み合わせごとに 1 つずつ、計 6 つのジョブが実行されます。各ジョブは、runs-on の値を現在の os の値に設定し、現在の version の値を actions/setup-node アクションに渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.version }}

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

コンテキストを使用してマトリックスを作成できます。コンテキストの詳細については、「コンテキスト」を参照してく� さい。

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

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

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@v2
        with:
          node-version: ${{ matrix.version }}

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

jobs.<job_id>.strategy.matrix.include を使用して、既存のマトリックス構成を展開したり、新しい構成を追� したりします。 include の値は、オブジェクトのリストです。

include リスト内の各オブジェクトに対して、キーと値のペアのいずれも元のマトリックス値を上書きしない� �合、オブジェクト内のキーと値のペアが各マトリックスの組み合わせに追� されます。オブジェクトをどのマトリックスの組み合わせにも追� できない� �合は、代わりに新しいマトリックスの組み合わせが作成されます。元のマトリックス値は上書きされませんが、追� されたマトリックス値は上書きできます。

たとえば、次のマトリックスを見てく� さい。

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}

このロジックに従うと、次のようになります。

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

例: 構成の展開

たとえば、次のワークフローでは、os と node の組み合わせごとに 1 つずつ、計 6 つのジョブが実行されます。 os の値が windows-latest で node の値が 16 のジョブが実行されると、6 の値を持つ npm という追� の変数がジョブに含まれます。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

例: 構成の追�

たとえば、このマトリックスでは 10 個のジョブが実行されます。マトリックス内の os と version の組み合わせごとに 1 つと、windows-latest の os 値と 17 の version 値のジョブです。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

マトリックス変数を指定しない� �合は、include の下のすべての構成が実行されます。たとえば、次のワークフローでは、include エントリごとに 1 つずつ、2 つのジョブが実行されます。これにより、マトリックスを完全に設定しなくても、マトリックス戦略を利用できます。

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

マトリックス構成の除外

マトリックスで定義されている特定の構成を削除するには、jobs.<job_id>.strategy.matrix.exclude を使用します。除外する構成は、それを除外するために部分一致である必要がある� けです。たとえば、次のワークフローでは 9 つのジョブが実行されます。12 個の構成ごとに 1 つのジョブで、{os: macos-latest, version: 12, environment: production} と一致する 1 つのジョブと、{os: windows-latest, version: 16} と一致する 2 つのジョブが除外されます。

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 }}

注: すべての include の組み合わせは、exclude の後に処理されます。このため、include を使って以前に除外された組み合わせを追� し直すことができます。

エラー処理

jobs.<job_id>.strategy.fail-fast と jobs.<job_id>.continue-on-error を使用して、ジョブエラーの処理方法制御できます。

jobs.<job_id>.strategy.fail-fast はマトリックス全体に適用されます。 jobs.<job_id>.strategy.fail-fast が true に設定されている� �合、マトリックス内のいずれかのジョブが失敗すると、GitHub Enterprise Server によってマトリックス内の進行中およびキューに入れられたすべてのジョブがキャンセルされます。このプロパティでは、既定値が true に設定されます。

jobs.<job_id>.continue-on-error は 1 つのジョブに適用されます。 jobs.<job_id>.continue-on-error が true の� �合、jobs.<job_id>.continue-on-error: true が失敗するジョブであっても、マトリックス内の他のジョブは引き続き実行されます。

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 のジョブが失敗した� �合、他のジョブは影響を受けません。

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

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

既定で、GitHub Enterprise Server は、ランナーの可用性に応じて並列実行されるジョブの数を最大化します。 matrix ジョブ戦略を使うとき、同時に実行できるジョブの最大数を設定するには、jobs.<job_id>.strategy.max-parallel を使います。

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

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

この記事では、次の� �目が扱われます。