Reusable Workflows と Composite Actions の使い分け

個人の見解です.

GitHub Actions 内の実行単位

GitHub Actions で基本となる実行単位は workflow ですが, その中に job, さらにその中に step という階層構造があるということをまずは理解しておきましょう.

workflow
- トップレベルの実行単位
job
- workflow の中で並列に実行される (直列に実行したい場合は needs で依存関係を持たせる)
- runner (VM) は job ごとに用意される
step
- job の中で直列に実行される

Reusable workflows と composite actions

GitHub から公開されている記事 (ref) で比較がされているのでそれも参考にしつつ, 簡単にまとめると,

reusable workflows
- 複数の job をまとめて 1 つの job のように扱えるようにしたもの
- 1 つの workflow 内でのネストは 4 段まで, 呼び出せるのは合計 20 個まで (ref) の制限がある
- (明示的に許可が与えられたら) リポジトリや organization の secrets を読める
- 呼び出し元の workflow で設定された環境変数は読めない (入力として渡す必要がある)
- .github/workflows に YAML ファイルを配置する
composite actions
- 複数の step をまとめて 1 つの step のように扱えるようにしたもの
- 1 つの workflow 内でのネストは 10 段まで. 呼び出せる個数の制限はない?
- リポジトリや organization の secrets は読めない (入力として渡す必要がある)
- (明示的に許可が与えられなくても) 呼び出し元の workflow や job で設定された環境変数を読める
- 個別にディレクトリを作り, そこに YAML ファイルを配置する

といった違いがあります. なお上記の記事には composite actions では if が使えないように書いてありますが, 記事が公開された時点では既にサポートされていたはず (ref).

使い分け方

Reusable workflows と composite actions のどちらを使うかを判断する上ではいくつか軸がありそうで, ここでは以下の 3 つを考えます:

job が必要か / 不要か
再利用を目的として作成するのか / 単に処理を分割するだけか
同じリポジトリ内でしか使わないか / 他のリポジトリから使われるか

まずは「job が必要か / 不要か」の軸については, job が必要な場合は reusable workflows を使う必要があります. 具体的に job が必要になるのはどういった場合かというと, job と step の違いを思い出すと,

複数の処理を並列に実行したい
特定の runner で実行されるようにしたい

などがあります.

続いて「再利用を目的として作成するのか / 単に処理を分割するだけか」ですが, 再利用を目的とする場合は composite actions の方が利用者側としては扱いやすいことが多いかと思います. ネストや個数の制限も reusable workflows と比較して緩く, 粒度としても job ではなく step となるため, 利用者側で使い方を細かくカスタマイズできる余地があります.

最後に「同じリポジトリ内でしか使わないか / 他のリポジトリから使われるか」ですが, 同じリポジトリ内で利用するだけであれば, 専用のディレクトリを作成する必要がない分 reusable workflows の方が利用しやすいかもしれません. secrets: inherit のように読み取り許可を与えれば, 個別に secrets を渡す必要もなくなります (リポジトリ外, 特にサードパーティの reusable workflows にこの許可を与えるのは怖い).

まとめると以下のようになるかと思います. ? がついているところはどちらかといえばという感じなので, 最終的にはお好みで.

用途	job が必要	job が不要
他リポジトリから再利用	reusable workflows	composite actions
同リポジトリ内で再利用	reusable workflows	composite actions?
同リポジトリ内で処理を分割	reusable workflows	reusable workflows?