Using a build matrix for your jobs

ノート: 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