GitHub Actionsの再利用可能なワークフローとは
最終更新
再利用可能なワークフローは、他のワークフローが1つのジョブのように呼び出せるGitHub Actionsのワークフローファイルです。workflow_callトリガーを宣言し、入力とシークレットを受け取り、出力を返すことができるため、チームはパイプラインを一度定義すれば、複数のリポジトリで再利用できます。
仕組み
呼び出されるワークフローでは、on: workflow_callの下に、任意でinputs、secrets、outputsを指定します。呼び出し側では、uses:でそのファイルを指定するジョブを追加します。指定先は同じリポジトリ(./.github/workflows/ci.yml)でも別のリポジトリ(org/repo/.github/workflows/ci.yml@ref)でもかまいません。値はwith:とsecrets:で渡します。
呼び出されるワークフローは、そのジョブを独自のランナーで実行します。runs-onはワークフロー内部で設定されるため、共有パイプラインをより高速なマシンに移行する場合は、すべてのリポジトリではなく1つのファイルを変更するだけで済みます。
再利用可能なワークフローは、コンポジットアクションとは異なります。コンポジットアクションは1つのジョブ内のステップをまとめたものです。一方、再利用可能なワークフローは、独自のランナー、マトリックス、サービスを含むジョブ全体をまとめたものです。
例
呼び出されるワークフロー、acme/shared内の.github/workflows/node-ci.yml:
on:
workflow_call:
inputs:
node-version:
type: string
default: "22"
secrets:
NPM_TOKEN:
required: false
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: npm
- run: npm ci && npm test
Caller:
jobs:
ci:
uses: acme/shared/.github/workflows/node-ci.yml@v1
with:
node-version: "20"
secrets: inherit
よくある間違い
- 固定されていない参照です。
@mainを指定すると、共有リポジトリへのあらゆるプッシュが、すべての呼び出し元に影響します。タグまたはSHAを固定してください。 - ネストが深すぎます。再利用可能なワークフローが相互に呼び出せる階層の数には上限があります。
envが引き継がれると想定している場合です。呼び出し元で設定した環境変数は、呼び出されるワークフローからは参照できません。入力として渡してください。- シークレットが呼び出し先に届かない場合です。明示的に渡すか、許可されている場合は
secrets: inheritを使用してください。 - 権限に関する予期しない動作です。呼び出されるワークフローは、呼び出し元が付与している以上の
GITHUB_TOKEN権限を得ることはできません。 - 入力を公開せずに、その中にマトリックスビルドを隠すと、呼び出し側で調整できなくなります。
再利用可能なワークフローは、一貫した同時実行グループとセキュリティ設定の管理にも役立ちます。固定に関する推奨事項は、GitHub Actionsのセキュリティ確保を参照してください。
関連用語
よくある質問
プライベートリポジトリでワークフローを共有できますか。
はい。リポジトリのActionsアクセス設定で、組織内の他のリポジトリによる利用が許可されていれば可能です。
料金はどのように請求されますか。
呼び出されるワークフロー内のジョブは、他のジョブと同様に分数を消費します。呼び出しによる別途の料金は発生しません。
テンプレートとの違いは何ですか。
テンプレートはコピーされます。再利用可能なワークフローは参照されるため、更新は指定した参照に従って呼び出し元に反映されます。
関連記事
- Invalid Workflow File: YAML構文エラーの修正方法GitHub Actionsで"Invalid workflow file"と"You have an error in your yaml syntax"を解決する方法:インデント、予期しない値、不正な式をactionlintで確認します。
- GitHub Appによるワークフローの更新を拒否される:修正方法「refusing to allow a GitHub App to create or update workflow without workflows permission」の修正方法:ワークフローへの書き込み権限を持つPATまたはAppトークンを使用してください。
- GitHub Actionsのworkflow_dispatchとはworkflow_dispatchは、入力を指定してワークフローを手動で開始できるGitHub Actionsのトリガーです。構文、CLIやAPIでの利用方法、注意点を学びましょう。
- CI分とは? GitHub Actionsの料金の仕組みCI分とは、パイプラインが使用する課金対象のコンピュート時間です。GitHub Actionsでの分の数え方、切り上げと乗数、そして使用量を減らす方法を説明します。