Skip to main content
ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

Using a matrix for your jobs

Create a matrix to define variations for each job.

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は利用可能なランナーに応じて並列に実行されるジョブ数を最大化します。 マトリックス内の変数の順序によって、ジョブが生成される順序が決まります。 定義された最初の変数が、ワークフロー中で生成される最初のジョブになります。 たとえば、上のマトリックスはジョブを以下の順序で生成します。

  • {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ホスト及びセルフホストの両方のランナーに適用されます。

定義した変数はmatrixコンテキストのプロパティとなり、このプロパティはワークフローファイルの他の領域から参照できます。 この例では、matrix.versionmatrix.osを使ってジョブが使用している現在のversionosの値にアクセスできます。 詳細については、「コンテキスト」を参照してください。

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

たとえば、以下のワークフローはosnodeの組み合わせに対応する6つのジョブを実行します。 osの値がwindows-latestnodeの値が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-latestversionの値が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-fasttrueに設定されていると、GitHubはマトリックス内のいずれかのジョブが失敗した場合、マトリックスの進行中及びキューイングされたすべてのジョブをキャンセルします。 この属性のデフォルトはtrueです。

jobs.<job_id>.continue-on-errorは単一のジョブに適用されます。 jobs.<job_id>.continue-on-errortrueの場合、jobs.<job_id>.continue-on-error: trueを指定されたジョブが失敗したとしても、マトリックス内の他のジョブは実行を継続します。

jobs.<job_id>.strategy.fail-fastjobs.<job_id>.continue-on-errorは合わせて利用できます。 たとえば、以下のワークフローは4つのジョブを開始します。 それぞれのジョブにおいて、continue-on-errormatrix.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は利用できるランナーに応じて並列に実行するジョブ数を最大化します。 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]