Zenn
🎈

Github Actions matrix includeを使った実装方法

2024/07/27に公開
GitHub
tech
GitHub Actions
tech

はじめに

実務では複数のプロジェクトを同時にCIで実行するケースが多くなります。
今回はサンプルコードをベースにincludeキーを使ったmatrixを説明します。

matrixとは

matrixは、1つのjobの定義で、複数のジョブを実行することができます。似たようなjobを複数実装した場合にはとても有効的です。
例えば3つの異なるjobで起動するときは${{ matrix.token }}とmatrixをcontext経由で参照することができます。

runs-on: ubuntu-latest
  strategy:
    matrix:
      token: [sample1, sample2, sample3]
    runs-on: ${{ matrix.token }}
    steps:
      - run echo "${{ matrix.token }}"
        shell: bash

多次元matrixとは

プロパティを複数定義する時は多次元matrixを使って実装出来ます。
多次元matrixは全パターンを網羅することができます。なので抜け漏れがなくjobを実行することが出来ます。
${{ matrix.project }}
${{ matrix.chromatic-token }}
上記のように参照することが出来ます。

runs-on: ubuntu-latest
  strategy:
    matrix:
      project: [sample1, sample2, sample3]
      chromatic-token: [CHROMATIC_SAMPLE1_APP_TOKEN, CHROMATIC_SAMPLE2_APP_TOKEN, CHROMATIC_SAMPLE3_APP_TOKEN]
    steps:
      - run echo "${{ matrix.project }}　　- ${{ matrix.chromatic-token }}"
        shell: bash

しかし、このパターンだと
package「sammple1」、chromatic-token「CHROMATIC_SAMPLE1_APP_TOKEN」
package「sammple1」、chromatic-token「CHROMATIC_SAMPLE2_APP_TOKEN」
package「sammple1」、chromatic-token「CHROMATIC_SAMPLE3_APP_TOKEN」

package「sammple2」、chromatic-token「CHROMATIC_SAMPLE1_APP_TOKEN」
package「sammple2」、chromatic-token「CHROMATIC_SAMPLE2_APP_TOKEN」
package「sammple2」、chromatic-token「CHROMATIC_SAMPLE3_APP_TOKEN」

package「sammple3」、chromatic-token「CHROMATIC_SAMPLE1_APP_TOKEN」
package「sammple3」、chromatic-token「CHROMATIC_SAMPLE2_APP_TOKEN」
package「sammple3」、chromatic-token「CHROMATIC_SAMPLE3_APP_TOKEN」

9パターンになってしまいます。

今回必要なパターンは

package「sammple1」、chromatic-token「CHROMATIC_SAMPLE1_APP_TOKEN」
package「sammple2」、chromatic-token「CHROMATIC_SAMPLE2_APP_TOKEN」
package「sammple3」、chromatic-token「CHROMATIC_SAMPLE3_APP_TOKEN」

だけになります。必要なパターンだけを作る場合にはincludeを使って実装することが出来ます。
それを踏まえて下記のケースで紹介します。

今回のケース(組み合わせ条件の手動定義(include))

今回は複数のprojectでchromaticを使ったケースを紹介します。

frontendディレクトリの中にsample1、sample2、sample3があるプロジェクトがあるケースを想定します。
それぞれのprojectで

sample1のchromatic
sample2のchromatic
sample3のchromatic

を作る必要があります。

chromaticとはここでは説明は割愛しますが、Storybookを使ってsnapshotを取り、UIの差分を確認できるツールです。エンジニア、デザイナー、PM、ビズサイドと連携してUIについてレビューすることができます。またUIの差分を見てデグレが起きていないかを確認することが出来ます。
詳しくは下記のリンクを参考にしてください。

chromatic | 公式ページ

Chromaticを導入しました！

chromaticに反映する時にはtokenが必要になります。

npx chromatic --project-token={{ projectのchromatic-token }}

上記のchromatic-tokenの値はgithubのsecretsで管理しています。

また上記のコマンドを実行する時は、frontend/package名に入って実行しなければいけません。

chromatic.yaml
name: 'Chromatic'

on:
  workflow_call:
    secrets:
      CHROMATIC_SAMPLE1_APP_TOKEN:
        required: true
      CHROMATIC_SAMPLE2_APP_TOKEN:
        required: true
      CHROMATIC_SAMPLE3_APP_TOKEN:
        required: true

jobs:
  chromatic-project:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        include:
          - package: 'sample1'
            chromatic-token: 'CHROMATIC_SAMPLE1_APP_TOKEN'
          - package: 'sample2'
            chromatic-token: 'CHROMATIC_SAMPLE2_APP_TOKEN'
          - package: 'sample3'
            chromatic-token: 'CHROMATIC_SAMPLE3_APP_TOKEN'
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Checkout
        uses: actions/setup-node@v4
        
      - name: yarn install
        run: yarn install
        working-directory: frontend

　　　　　　　　　　　　- name: Publish to Chromatic
        run: npx chromatic --project-token=${{ secrets[matrix.chromatic-token] }} --only-changed --exit-zero-on-changes
        working-directory: frontend/packages/${{ matrix.package }}

このようなケースでは、includeキーを使ってプロパティの組み合わせを作ります。少し記述量は増えますが必要な組み合わせを作成することが出来ます。

matrix:
  include:
    - package: 'sample1'
      chromatic-token: 'CHROMATIC_SAMPLE1_APP_TOKEN'
    - package: 'sample2'
      chromatic-token: 'CHROMATIC_SAMPLE2_APP_TOKEN'
    - package: 'sample3'
      chromatic-token: 'CHROMATIC_SAMPLE3_APP_TOKEN'

また、今回はtokenはsecretsで定義しているので、

${{ secrets[matrix.chromatic-token] }}

と定義しています。

余談

workflowとして呼び出す方法

別ファイルで定義したものを呼び出して使う方法があります。

サンプルコードを使って説明します。

main.yaml
name: Main CI

on:
  pull_request:
    types:
      - opened
      - synchronize
      - closed

jobs:
  lint:
    ~~ ここにruns-onやstepの処理を書く　~~
  build:
    ~~ ここにruns-onやstepの処理を書く　~~
  test:
    ~~ ここにruns-onやstepの処理を書く　~~

  chromatic:
    needs: [lint, build, test]　
    uses: ./.github/workflows/chromatic.yml
    secrets:
      CHROMATIC_SAMPLE1_APP_TOKEN: ${{ secrets.CHROMATIC_SAMPLE1_APP_TOKEN }}
　　　　　　　　　　　　CHROMATIC_SAMPLE2_APP_TOKEN: ${{ secrets.CHROMATIC_SAMPLE2_APP_TOKEN }}
　　　　　　　　　　　　CHROMATIC_SAMPLE3_APP_TOKEN: ${{ secrets.CHROMATIC_SAMPLE3_APP_TOKEN }}

今回の条件として、chromatic.ymlのCIが実行される条件が
「lint、build、test」のCIの全てが成功した時にchromatic.ymlのCIが実行されるようにします。

uses:は呼び出すファイルのパスを書きます。
secrets:は呼び出す側で使うsecretsを定義します。

最後に

includeを使って必要なパターンの実装パターンを説明しました。
個人的にはincludeを使って柔軟に対応できるのが良いかなと思います。
使い分けするとしたら、

全パターンを網羅するときは、多次元matrix
必要なパターンだけを作成するときはinclude

使う時はこれらを考えて使い分けるといいかなと思います。

github　actionsのCI/CDの実行方法は色んなパターンや書き方があると思いますが、書き慣れていないと構文エラーや書き方のルールでエラーの沼にハマることがあります。

また、実務ではなかなかgithub actionsのyamlファイルを新規作成、修正する機会はあんまりないと思います。
なので参考書籍を読んだり、実際に書いて実行してみて挙動がどうなるかを確認してみるといいと思います！

下記に参考技術図書や記事を紹介しますので参考にしてみてください。

参考

書籍

GitHub CI/CD実践ガイド――持続可能なソフトウェア開発を支えるGitHub Actionsの設計と運用

記事

GitHub Actions の matrix strategy で job を並列に実行する

Discussion