GitHub Actions でテストやビルドを自動化する際、異なるOSやソフトウェアバージョンで実行したいケースがよくありますよね。そんな時に役立つのが strategy: matrix: です！
matrix を使うと、複数の組み合わせのジョブを簡単に定義し、実行することができます。初心者の方にも分かりやすく、matrix の使い方を説明していきます。

`matrix` の基本

matrix は、ジョブ内で変数を定義し、その変数の組み合わせに基づいて複数のジョブを自動的に生成します。例えば、異なる OS や Node.js のバージョンでテストを実行したい場合、次のように記述します。

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [14, 16]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm test

このワークフローでは、3種類のOS (ubuntu-latest, macos-latest, windows-latest) と 2つのNode.jsバージョン (14, 16) の組み合わせ、つまり合計6つのジョブが実行されます。 runs-on: ${{ matrix.os }} のように、matrix で定義した変数を ${{ matrix.変数名 }} で参照することで、各ジョブで異なる値が使用されます。

さらに便利に使うためのテクニック

matrix をさらに活用するためのテクニックをいくつか紹介します。

1. 組み合わせの追加 (include)

特定の組み合わせを追加したい場合は include を使用します。

matrix:
  os: [ubuntu-latest, windows-latest]
  node: [14, 16]
  include:
    - os: ubuntu-latest
      node: 18
      npm: 6

この例では、既存の組み合わせに加えて、Ubuntu 上で Node.js 18 と npm 6 を使用するジョブが追加されます。

2. 組み合わせの除外 (exclude)

特定の組み合わせを除外したい場合は exclude を使用します。

matrix:
  os: [ubuntu-latest, macos-latest, windows-latest]
  node-version: [14, 16]
  exclude:
    - os: windows-latest
      node-version: 14

この例では、Windows 上で Node.js 14 を使用するジョブは実行されません。

3. 部分的な組み合わせでの除外

exclude は部分一致でも機能します。

matrix:
  os: [macos-latest, windows-latest]
  version: [12, 14, 16]
  environment: [staging, production]
  exclude:
    - os: windows-latest
      version: 16

この例では、windows-latest と version: 16 の組み合わせを持つジョブは、environment の値に関係なく、すべて除外されます。

4. ジョブの失敗時の挙動 (fail-fast, continue-on-error)

デフォルトでは、1つのジョブが失敗しても、他のジョブは実行されます。全てのジョブを即座に停止したい場合は、fail-fast: true を strategy 内に記述します。逆に、特定のジョブの失敗を許容したい場合は、そのジョブに continue-on-error: true を記述します。

5. 同時実行数の制御 (max-parallel)

同時に実行するジョブの数を制限するには max-parallel を使用します。

strategy:
  max-parallel: 2
  matrix:
    # ...

この例では、最大2つのジョブが同時に実行されます。

6. 前のジョブの結果を利用した動的なマトリックス生成

前のジョブの出力結果を fromJSON() 関数で解析し、matrix の値として使用することで、動的なマトリックスを生成できます。

jobs:
  generate-matrix:
    # ... (何らかの処理で matrix.json を生成)
    outputs:
      matrix_values: ${{ steps.generate.outputs.matrix }}

  use-matrix:
    needs: generate-matrix
    strategy:
      matrix:
        value: ${{ fromJSON(needs.generate-matrix.outputs.matrix_values) }}

まとめ

strategy: matrix: を使うことで、GitHub Actions ワークフローをより簡潔に記述し、効率的に実行することができます。紹介したテクニックを使いこなせば、様々なテスト・ビルドシナリオに柔軟に対応できます。ぜひ活用してみてください！より詳しい情報や高度な使い方は、GitHub の公式ドキュメントを参照することをおすすめします。

参考文献