コンテンツへスキップ

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アクセス設定で、組織内の他のリポジトリによる利用が許可されていれば可能です。

料金はどのように請求されますか。

呼び出されるワークフロー内のジョブは、他のジョブと同様に分数を消費します。呼び出しによる別途の料金は発生しません。

テンプレートとの違いは何ですか。

テンプレートはコピーされます。再利用可能なワークフローは参照されるため、更新は指定した参照に従って呼び出し元に反映されます。