GitHub Actions - 再利用可能ワークフローを使う

| 3 min read
Author: masahiro-kondo

GitHub Actions のワークフローから別のワークフローを再利用する機能が昨年11月にリリースされました。この機能がなくて不便に感じていた人も多いのではないでしょうか。

シンプルなワークフローを作って試してみました。

呼び出し側のワークフロー。同一リポジトリのワークフローを呼び出すには、uses キーワードを使ってプロジェクトルートからの相対パスで .github/workflow 配下のワークフローファイルを指定します。通常のジョブと違って runs-on などは指定しません。

name: Caller Job
on:
workflow_dispatch:

jobs:
Reuse:
uses: ./.github/workflows/callee.yml

呼び出されるワークフロー。ワークフローのトリガーには workflow_call を指定します。runs-on は呼び出される側で指定します。

name: Callee Job
on:
workflow_call:

jobs:
Build:
runs-on: ubuntu-latest
steps:
- run: echo called!

呼び出し側のワークフローを手動で実行しました。呼び出し側と呼び出される側が1つにまとめられたジョブ Reuse / Build として表示されました。

ログを見ると、呼び出されるワークフローに書いた step の処理がそのまま出力されています。

呼び出し側フローに呼び出されるフローをインライン展開しているような動きですね。

公式ドキュメントによると再利用可能ワークフローには以下のような制限があります。

  1. 再利用可能ワークフローは他の再利用可能ワークフローを呼び出すことはできない
  2. プライベートリポジトリ内の再利用可能ワークフローは、同一リポジトリ内のワークフローでのみ使用可能
  3. 呼び出し元ワークフローで定義されたワークフローレベルの環境変数は呼び出されたワークフローに伝播されない
  4. strategy プロパティは、再利用可能ワークフローを呼び出すジョブではサポートされない

2番目の制約はちょっと残念ですね。1つのプライベートリポジトリに再利用可能ワークフローを集約して他のリポジトリのワークフローから呼ぶという使い方はできないようです[1]。public なリポジトリのワークフローであれば以下のように指定可能です。

jobs:
Reuse1:
uses: mamezou-tech/reusable-flows/.github/workflows/reuse1.yml@main
Reuse2:
uses: mamezou-tech/reusable-flows/.github/workflows/reuse2.yml@v1

4番目の制約によれば、マトリクス実行や fail-fast のような strategy の機能を呼び出し側ジョブで使えないということになります。

外部の Action を実行するのと同じ構文で、再利用可能ワークフローにパラメータを受け渡すことができます。 パラメータは with キーワードで指定します。 secret は secrets キーワードで渡せます。

jobs:
call-workflow-passing-data:
uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
with:
username: mona
secrets:
token: ${{ secrets.TOKEN }}

呼び出されるワークフローでは、パラメータや secret の名前、型などを指定します[2]${{ inputs.username }}${{ secrets.token }} のよう渡されたパラメータや secret を利用できます。

name: Reusable workflow example

on:
workflow_call:
inputs:
username:
required: true
type: string
secrets:
token:
required: true

jobs:
example_job:
name: Pass input and secrets to my-action
runs-on: ubuntu-latest
steps:
- uses: ./.github/workflows/my-action
with:
username: ${{ inputs.username }}
token: ${{ secrets.token }}

再利用可能なワークフローが使えることで、ビルドやテストなどのワークフローを個別のファイルに切り出して E2E テスト用のワークフローやリリース用のワークフローから利用できるようになりました。ワークフローのコード重複を削減するためにうまく利用したいですね。


  1. ワークフローをオーガニゼーション単位で共有する機能は将来提供される予定ですが、マイルストーンは未定です。https://github.com/github/roadmap/issues/52 ↩︎

  2. GitHub Actionsのメタデータ構文 - GitHub Docs ↩︎