ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情� �を見ることができます。
概要
Use jobs.<job_id>.strategy
to create a build matrix for your jobs. それぞれのジョブを実行する様々なバリエーションを定義できます。
Creating a matrix of different job configurations
Use jobs.<job_id>.strategy.matrix
to define a matrix of different job configurations. マトリックスによって、単一のジョブの定義内の変数の置き換えを行い、複数のジョブを作成できるようになります。 たとえば、マトリックスを使って複数のサポートされているバージョンのプログラミング言語、オペレーティングシステ� 、ツールに対するジョブを作成できます。 マトリックスは、ジョブの設定を再利用し、設定した各マトリクスに対してジョブを作成します。
ジョブマトリックスは、ワークフローの実行ごとに最大で256のジョブを生成できます。 この制限は、セルフホストランナーにも適用されます。
matrix
内で定義した各オプションは、キーと値を持ちます。 定義したキーはmatrix
コンテキスト中の属性となり、ワークフローファイルの他のエリア内のプロパティを参照できます。 たとえば、オペレーティングシステ� の配列を含むos
というキーを定義したなら、matrix.os
属性をruns-on
キーワードの値として使い、それぞれのオペレーティングシステ� に対するジョブを作成できます。 詳細については、「コンテキスト」を参照してく� さい。
matrix
を定義する� �序は意味を持ちます。 最初に定義したオプションは、ワークフロー中で最初に実行されるジョブになります。
Example: Running multiple versions of Node.js
設定オプションに配列を指定すると、マトリクスを指定できます。 たとえばランナーがNode.jsのバージョン10、12、14,をサポートしている� �合、これらのバージョンの配列をmatrix
で指定できます。
この例では、node
キーにNode.jsの3つのバージョンの配列を設定することによって、3つのジョブのマトリクスを作成します。 このマトリックスを使用するために、この例ではmatrix.node
コンテキスト属性をsetup-node
アクションの入力パラメータであるnode-version
に設定しています。 その結果、3 つのジョブが実行され、それぞれが異なるバージョンのNode.js を使用します。
strategy:
matrix:
node: [10, 12, 14]
steps:
# GitHub でホストされているランナーで使用されるノードバージョンを設定する
- uses: actions/setup-node@v2
with:
# The Node.js version to configure
node-version: ${{ matrix.node }}
GitHubホストランナーを使う� �合にNode.jsのバージョンを設定する方法としては、setup-node
アクションをおすすめします。 詳しい情� �についてはsetup-node
アクションを参照してく� さい。
Example: Running with multiple operating systems
複数のランナーオペレーティングシステ� でワークフローを実行するマトリックスを作成できます。 複数のマトリックス設定を指定することもできます。 この例では、6つのジョブのマトリックスを作成します。
- 配列
os
で指定された2つのオペレーティングシステ� - 配列
node
で指定された3つのバージョンのNode.js
オペレーティングシステ� のマトリックスを定義する際には、runs-on
の値を、定義したmatrix.os
コンテキストのプロパティに設定しなければなりません。
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-18.04, ubuntu-20.04]
node: [10, 12, 14]
steps:
- uses: actions/setup-node@v2
with:
node-version: ${{ matrix.node }}
GitHub ホストランナーでサポートされている設定オプションについては、「GitHub の仮想環境」を参照してく� さい。
Example: Including additional values in combinations
既存のビルドマトリクスジョブに、設定オプションを追� できます。 たとえば、windows-latest
を使うジョブでnode
のバージョン 8 を実行しているときに、npm
の特定のバージョンを使いたい� �合は、include
を使って追� のオプションを指定できます。
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-18.04]
node: [8, 10, 12, 14]
include:
# osとバージョンに一致するマトリックスレッグの値が
# 6 の npm の新しい変数を含む
- os: windows-latest
node: 8
npm: 6
Example: Including new combinations
include
を使って新しいジョブを追� し、マトリックスを構築できます。 マッチしなかったincludeの設定があれば、マトリックスに追� されます。 たとえば、node
のバージョン14を使って複数のオペレーティングシステ� 上でビルドを行い、追� で実験的なジョブをUbuntu上でnodeバージョン15で行いたいなら、include
を使ってこの追� のジョブを指定できます。
runs-on: ${{ matrix.os }}
strategy:
matrix:
node: [14]
os: [macos-latest, windows-latest, ubuntu-18.04]
include:
- node: 15
os: ubuntu-18.04
experimental: true
Example: Excluding configurations from a matrix
exclude
オプションを使って、ビルドマトリクスに定義されている特定の設定を削除できます。 exclude
を使うと、ビルドマトリクスにより定義されたジョブが削除されます。 ジョブの数は、指定する配列に含まれるオペレーティングシステ� (os
) の外積から、任意の減算 (exclude
) で引いたものです。
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-18.04]
node: [8, 10, 12, 14]
exclude:
# macOS のノード 8 を除外する
- os: macos-latest
node: 8
ノート: すべてのinclude
の組み合わせは、exclude
の後に処理されます。 このため、include
を使って以前に除外された組み合わせを追� し直すことができます。
マトリックスで環境変数を使用する
それぞれのテストの組み合わせに、include
キーを使ってカスタ� の環境変数を追� できます。 そして、後のステップでそのカスタ� の環境変数を参照できます。
この例では、node-version
に対するマトリクスのエントリは、それぞれ環境変数のsite
及びdatacenter
に異なる値を使うように設定されています。 そしてEcho site details
ステップはenv: ${{ matrix.env }}
を使ってカスタ� 変数を参照しています。
name: Node.js CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- node-version: 10.x
site: "prod"
datacenter: "site-a"
- node-version: 12.x
site: "dev"
datacenter: "site-b"
steps:
- name: Echo site details
env:
SITE: ${{ matrix.site }}
DATACENTER: ${{ matrix.datacenter }}
run: echo $SITE $DATACENTER
Canceling remaining jobs if a matrix
job fails
When jobs.<job_id>.strategy.fail-fast
is set to true
, GitHub cancels all in-progress jobs if any matrix
job fails. デフォルト: true
Defining the maximum number of concurrent jobs in a matrix
Use jobs.<job_id>.strategy.max-parallel
to set the maximum number of jobs that can run simultaneously when using a matrix
job strategy. デフォルトでは、GitHubはGitHubがホストしている仮想マシン上で利用できるrunnerに応じてできるかぎりの数のジョブを並列に実行します。
strategy:
max-parallel: 2