About matrix strategies
マトリックス戦略を使うと、単一のジョブ定義中で変数を使って、変数の組み合わせに基づく複数のジョブの実行を自動的に生成できます。 たとえばマトリックス戦略を使って、コードを言語の複数のバージョンや、複数のオペレーティングシステムでテストできます。
Using a matrix strategy
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]
取り得る変数のそれぞれの組み合わせに対して、ジョブが実行されます。 この例では、ワークフローはos
及びversion
変数のそれぞれの組み合わせに対応する6つのジョブを実行します。
デフォルトでは、GitHub Enterprise Cloudは利用可能なランナーに応じて並列に実行されるジョブ数を最大化します。 マトリックス内の変数の順序によって、ジョブが生成される順序が決まります。 定義された最初の変数が、ワークフロー中で生成される最初のジョブになります。 たとえば、上のマトリックスはジョブを以下の順序で生成します。
{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}
1つのマトリックスはワークフローの実行ごとに最大で256のジョブを生成します。 この制限は、GitHub Enterprise Cloudホスト及びセルフホストの両方のランナーに適用されます。
定義した変数はmatrix
コンテキストのプロパティとなり、このプロパティはワークフローファイルの他の領域から参照できます。 この例では、matrix.version
とmatrix.os
を使ってジョブが使用している現在のversion
とos
の値にアクセスできます。 詳細については、「コンテキスト」を参照してください。
Example: Using a single-dimension matrix
1つの変数を指定して、1次元のマトリックスを作成できます。
たとえば、以下のワークフローは変数version
に[10, 12, 14]
という値を定義しています。 このワークフローは、変数中のそれぞれの値に対して1つずつ、3つのジョブを実行します。 それぞれのジョブはversion
の値にmatrix.version
コンテキストを通じてアクセスし、その値をnode-version
としてactions/setup-node
アクションに渡します。
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
steps:
- uses: actions/setup-node@v3
with:
node-version: ${{ matrix.version }}
Example: Using a multi-dimension matrix
複数の変数を指定して、多次元マトリックスを作成できます。 変数の取り得るそれぞれの組み合わせに対してジョブが実行されます。
たとえば、以下のワークフローは2つの変数を指定しています。
os
変数では2つのオペレーティングシステムが指定されていますversion
変数では、3つのNode.jsのバージョンが指定されています
このワークフローは、os
及びversion
変数のそれぞれの組み合わせに応じた6のジョブを実行します。 各ジョブは、runs-on
の値を現在のos
の値に設定し、現在のversion
の値をactions/setup-node
アクションに渡します。
jobs:
example_matrix:
strategy:
matrix:
os: [ubuntu-18.04, ubuntu-20.04]
version: [10, 12, 14]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v3
with:
node-version: ${{ matrix.version }}
Example: Using contexts to create matrices
コンテキストを使ってマトリックスを作成できます。 コンテキストに関する詳しい情報については「コンテキスト」を参照してください。
たとえば、以下のワークフローは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@v3
with:
node-version: ${{ matrix.version }}
Expanding or adding matrix configurations
jobs.<job_id>.strategy.matrix.include
を使って、既存のマトリックス設定を拡張したり、新しい設定を追加したりしてください。 include
の値は、オブジェクトのリストです。
include
リスト中の各オブジェクトについて、オブジェクト中のkey:valueペアがいずれもオリジナルのマトリックスの値を上書きしない場合、それらのkey:valueペアはそれぞれのマトリックスの組み合わせに追加されます。 オブジェクトがマトリックスの組み合わせのいずれにも追加できない場合、代わりに新しいマトリックスの組み合わせが作成されます。 オリジナルのマトリックスの値は上書きされませんが、追加されたマトリックスの値は上書きできることに注意してください。
たとえば、以下のマトリックス
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}
は、値を上書きせずにオリジナルのマトリックスの組み合わせに追加することができないので、追加のマトリックスの組み合わせとして追加されます。 これは{fruit: banana}
のマトリックスの組み合わせには追加されませんが、それはこの組み合わせがオリジナルのマトリックスの組み合わせの1つではないからです。
Example: Expanding configurations
たとえば、以下のワークフローはos
とnode
の組み合わせに対応する6つのジョブを実行します。 os
の値がwindows-latest
でnode
の値が16
に対するジョブが実行されると、そのジョブにはnpm
という追加の変数が6
を値として含まれます。
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@v3
with:
node-version: ${{ matrix.node }}
- if: ${{ matrix.npm }}
run: npm install -g npm@${{ matrix.npm }}
- run: npm --version
Example: Adding configurations
たとえばこのマトリックスは、マトリックス内のos
及びversion
の各組み合わせに、os
の値がwindows-latest
でversion
の値が17
の場合を加えて、10個のジョブを実行します。
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
マトリックス変数を指定しなければ、include
以下のすべての設定が実行されます。 たとえば、以下のワークフローはinclude
の各エントリに対応して2つのジョブを実行します。 これによって、完全にマトリックスを展開することなく、マトリックス戦略を活用できます。
jobs:
includes_only:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- site: "production"
datacenter: "site-a"
- site: "staging"
datacenter: "site-b"
Excluding matrix configurations
マトリックスで定義されている特定の設定を除外したい場合には、jobs.<job_id>.strategy.matrix.exclude
を使ってください。 除外する設定は、部分一致だけでかまいません。 たとえば、以下のワークフローは9つのジョブを実行します。12個の各設定に対応するジョブから、{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
を使って以前に除外された組み合わせを追加し直すことができます。
Handling failures
jobs.<job_id>.strategy.fail-fast
and jobs.<job_id>.continue-on-error
で、ジョブの失敗をどのように扱うかを制御できます。
jobs.<job_id>.strategy.fail-fast
はマトリックス全体に適用されます。 jobs.<job_id>.strategy.fail-fast
がtrue
に設定されていると、GitHub Enterprise Cloudはマトリックス内のいずれかのジョブが失敗した場合、マトリックスの進行中及びキューイングされたすべてのジョブをキャンセルします。 この属性のデフォルトはtrue
です。
jobs.<job_id>.continue-on-error
は単一のジョブに適用されます。 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
Defining the maximum number of concurrent jobs
デフォルトでは、GitHub Enterprise Cloudは利用できるランナーに応じて並列に実行するジョブ数を最大化します。 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]