GitHub Actions の matrix build とは？

matrix build は 1 つのジョブを多数に展開し、定義した変数の組み合わせごとに 1 回実行します。

複数の言語バージョンやオペレーティングシステムでテストする必要があるとき、matrix はジョブをコピーする手間を省きます。変数を列挙すると、GitHub がすべての組み合わせを生成し並列で実行します。

それは何か

matrix は strategy.matrix の下で定義されます。各キーは値のリストを持つ変数で、GitHub は組み合わせごとに 1 つのジョブを作成します。

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20, 22]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test

どう動くか

GitHub は matrix 変数の直積を計算し、それぞれに並列ジョブを起動します。ジョブ内では値を ${{ matrix.<key> }} で読みます。

include と exclude

include で特定の追加の組み合わせを加えたり、exclude で不要なものを削除したりでき、どのセルが実際に実行されるかをきめ細かく制御できます。

なぜ重要か

matrix は広いカバレッジを安価に提供します。1 つの簡潔なブロックで多数の環境を一度にテストできます。ただしサイズには注意してください。組み合わせは掛け算で増え、多くのランナーの分を消費する可能性があります。

関連する概念

matrix は strategy キーで制御され、1 つの失敗したセルが残りをキャンセルするかを決める fail-fast と連携します。

重要なポイント

• matrix は 1 つのジョブを多数の変数の組み合わせで実行します。
• 値は ${{ matrix.key }} で読みます。
• include/exclude を使い、組み合わせ数に注意します。

関連ガイド