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]