注: 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@v4
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@v4
with:
node-version: ${{ matrix.version }}
マトリックス内の変数構成は、object
の array
になります。
matrix:
os:
- ubuntu-latest
- macos-latest
node:
- version: 14
- version: 20
env: NODE_OPTIONS=--openssl-legacy-provider
このマトリックスでは、対応するコンテキストを持つ 4 つのジョブが生成されます。
- matrix.os: ubuntu-latest
matrix.node.version: 14
- matrix.os: ubuntu-latest
matrix.node.version: 20
matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
matrix.node.version: 14
- matrix.os: macos-latest
matrix.node.version: 20
matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
例: コンテキストを使ったマトリックスの作成
コンテキストを使用してマトリックスを作成できます。 コンテキストについて詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」をご覧ください。
たとえば、次のワークフローは 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@v4
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 つずつ、計 4 つのジョブが実行されます。 os
の値が windows-latest
で node
の値が 16
のジョブが実行されると、6
の値を持つ npm
という追加の変数がジョブに含まれます。
jobs:
example_matrix:
strategy:
matrix:
os: [windows-latest, ubuntu-latest]
node: [14, 16]
include:
- os: windows-latest
node: 16
npm: 6
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v4
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
を使って以前に除外された組み合わせを追加し直すことができます。
例: 出力を使用して 2 つのマトリックスを定義する
1 つのジョブからの出力を使用して、複数のジョブのマトリックスを定義できます。
たとえば、次のワークフローは、1 つのジョブで値のマトリックスを定義し、2 番目のジョブでそのマトリックスを使用して成果物を生成し、3 番目のジョブでそれらの成果物を使用する方法を示しています。 各成果物は、マトリックスの値に関連付けられます。
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@v3 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@v3 with: name: ${{ matrix.color }} - name: Report Color run: | cat color
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@v3
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@v3
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>.strategy.fail-fast
が true
に設定されているか、その式が 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]