注: 再利用できるワークフローは現在ベータ版であり、変更される可能性があります。
注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
概要
あるワークフローから別のワークフローにコピーして貼り付けるのではなく、ワークフローを再利用できます。 再利用可能なワークフローにアクセスできるユーザーは誰でも、別のワークフローから再利用可能なワークフローを呼び出すことができます。
ワークフローを再利用すると、重複が回避されます。 これにより、ワークフローの管理が容易になり、アクションと同様に、他のユーザーの作業を基にして新しいワークフローをより迅速に作成できます。 また、ワークフローを再利用すると、適切に設計され、既にテスト済みで、効果的であることが証明されているワークフローを使用でき、ベスト プラクティスが促進されます。 Organization では、一元的に管理できる再利用可能なワークフローのライブラリを構築できます。
次の図は、再利用可能なワークフローを使用する進行中のワークフロー実行を示しています。
- 図の左側にある 3 つのビルド ジョブが正常に完了すると、"Deploy" という依存ジョブが実行されます。
- "Deploy" ジョブによって、"Staging"、"Review"、"Production" の 3 つのジョブを含む再利用可能なワークフローが呼び出されます。
- "Production" デプロイ ジョブは、"Staging" ジョブが正常に完了した後にのみ実行されます。
- ジョブが環境を対象とする場合、ワークフロー実行には、ジョブ内のステップ数を示す進行状況バーが表示されます。 次の図では、"Production" ジョブには 8 つのステップが含まれており、ステップ 6 が現在処理中です。
- 再利用可能なワークフローを使用してデプロイ ジョブを実行すると、ワークフロー内のコードを複製することなく、ビルドごとにそれらのジョブを実行できます。
別のワークフローを使用するワークフローは、"呼び出し元" ワークフローと呼ばれます。 再利用可能なワークフローは、"呼び出し先" ワークフローです。 1 つの呼び出し元ワークフローで、複数の呼び出し先ワークフローを使用できます。 各呼び出し先ワークフローは、1 行で参照されます。 その結果、呼び出し元のワークフロー ファイルに含まれるのは数行の YAML だけでも、実行時に多数のタスクが実行される可能性があります。 ワークフローを再利用すると、呼び出し先ワークフロー全体が、呼び出し元ワークフローの一部であるかのように使用されます。
別のリポジトリのワークフローを再利用する場合、呼び出し先ワークフロー内のすべてのアクションは、呼び出し元ワークフローの一部であるかのように実行されます。 たとえば、呼び出し先ワークフローで actions/checkout
を使用する場合、アクションでは、呼び出し先ワークフローではなく、呼び出し元ワークフローがホストされるリポジトリの内容をチェックアウトします。
再利用可能なワークフローが呼び出し元ワークフローによってトリガーされると、 github
コンテキストが必ず呼び出し元ワークフローに関連付けられます。 呼び出し先ワークフローには、github.token
と secrets.GITHUB_TOKEN
へのアクセス権が自動的に付与されます。 github
コンテキストの詳細については、「コンテキスト」を参照してください。
GitHub Actions ワークフローで参照されている再利用ワークフローは、ユーザーのワークフローを含むリポジトリの依存関係グラフで依存関係として表示できます。 詳細については、「依存関係グラフについて」を参照してください。
再利用可能なワークフローとスターター ワークフロー
スターター ワークフローを使用すると、ワークフローを作成するアクセス許可を持つ Organization 内のすべての人が、より迅速かつ簡単にワークフローを作成できます。 新しいワークフローを作成する場合は、スターター ワークフローを選択すると、ワークフローを作成する作業の一部またはすべてが自動的に行われます。 スターター ワークフロー内では、再利用可能なワークフローを参照して、一元管理されたワークフロー コードを再利用するメリットを簡単に得ることもできます。 再利用可能なワークフローを参照するときにコミット SHA を使うと、そのワークフローを再利用するすべてのユーザーが必ず同じ YAML コードを使用するようにできます。 ただし、タグまたはブランチを使用して再利用可能なワークフローを参照する場合は、そのバージョンのワークフローを信頼できることを確認してください。 詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。
詳しくは、「Organization のスターター ワークフローを作成する」を参照してください。
再利用可能なワークフローへのアクセス
次のいずれかを満たしていれば、別のワークフローから再利用可能なワークフローを使用できます。
- どちらのワークフローも同じリポジトリ内にある。
- 呼び出し先ワークフローがパブリック リポジトリ。
- 呼び出し先ワークフローが内部リポジトリに格納され、そのリポジトリの設定によりアクセス可能になっている。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」を参照してください。
ランナーの使用
GitHub ホステッド ランナーの使用
GitHub ホステッド ランナーの割り当ては、常に呼び出し元のコンテキストのみを使用して評価されます。 GitHub ホステッド ランナーの支払いは、常に呼び出し元に関連付けられます。 呼び出し元ワークフローは、呼び出し先リポジトリの GitHub ホステッド ランナーを使用できません。 詳しくは、「GitHub ホステッド ランナーの概要」を参照してください。
セルフホスト ランナーの使用
呼び出し元ワークフローと同じユーザーまたは Organization あるいは Enterprise が所有する呼び出し先ワークフローでは、呼び出し元のコンテキストからセルフホスト ランナーにアクセスできます。 つまり、呼び出し先ワークフローでは、次のセルフホスト ランナーにアクセスできます。
- 呼び出し元リポジトリ内
- 呼び出し元リポジトリの Organization または Enterprise 内にあり、ランナーが呼び出し元リポジトリで使用できるようになっている
制限事項
- 再利用可能なワークフローでは、他の再利用可能なワークフローを呼び出すことはできません。
- 1 つのワークフロー ファイルから最大 20 個の再利用可能なワークフローを呼び出すことができます。
- プライベート リポジトリ内に格納されている再利用可能なワークフローは、同じリポジトリ内のワークフローでのみ使うことができます。*
strategy
プロパティは、再利用可能なワークフローを呼び出すジョブではサポートされていません。 - 呼び出し元ワークフローのワークフロー レベルで定義され、
env
コンテキストで設定されている環境変数は、呼び出し先ワークフローには反映されません。 詳細については、「変数」および「コンテキスト」を参照してください。 - 複数のワークフローで変数を再利用するには、これを Organization レベル、リポジトリ レベル、または環境レベルで設定し、
vars
コンテキストを使って参照します。 詳しくは、「変数」と「コンテキスト」をご覧ください。
再利用可能なワークフローの作成
再利用可能なワークフローは、他のワークフロー ファイルとよく似た YAML 形式のファイルです。 他のワークフロー ファイルと同様に、再利用可能なワークフローは、リポジトリの .github/workflows
ディレクトリ内にあります。 workflows
ディレクトリのサブディレクトリはサポートされていません。
ワークフローを再利用可能にするには、 on
の値に workflow_call
を含める必要があります。
on:
workflow_call:
再利用可能なワークフローでの入力とシークレットの使用
入力とシークレットを定義し、呼び出し元のワークフローから渡して、呼び出し先ワークフロー内で使用できます。 再利用可能なワークフローで入力またはシークレットを使用するには、3 つの段階があります。
-
再利用可能なワークフローで、
inputs
とsecrets
のキーワードを使用して、呼び出し元ワークフローから渡す入力またはシークレットを定義します。on: workflow_call: inputs: config-path: required: true type: string secrets: envPAT: required: true
入力とシークレットを定義するための構文の詳細については、
on.workflow_call.inputs
とon.workflow_call.secrets
を参照してください。 -
再利用可能なワークフローで、前の手順で
on
キーに定義した入力またはシークレットを参照します。jobs: reusable_workflow_job: runs-on: ubuntu-latest environment: production steps: - uses: actions/labeler@v4 with: repo-token: ${{ secrets.envPAT }} configuration-path: ${{ inputs.config-path }}
上記の例では、
envPAT
はproduction
環境に追加された環境シークレットです。 したがって、この環境はジョブ内で参照されます。注: 環境シークレットは、リポジトリ用に定義した環境に格納される、暗号化された文字列です。 環境シークレットは、当該の環境を参照するワークフロー ジョブからのみ利用できます。 詳しくは、「デプロイに環境を使用する」を参照してください。
-
呼び出し元ワークフローから入力またはシークレットを渡します。
名前付き入力を呼び出されたワークフローに渡すには、ジョブで
with
キーワードを使用します。secrets
キーワードを使用して名前付きシークレットを渡します。 入力の場合、入力値のデータ型は、呼び出されたワークフローで指定された型 (ブール値、数値、または文字列) と一致する必要があります。jobs: call-workflow-passing-data: uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main with: config-path: .github/labeler.yml secrets: envPAT: ${{ secrets.envPAT }}
再利用可能なワークフローの例
この再利用可能な workflow-B.yml
という名前のワークフロー ファイル (後述の呼び出し元ワークフローの例でこれを参照します) では、入力文字列とシークレットを呼び出し元ワークフローから受け取り、それらをアクションで使用します。
name: Reusable workflow example
on:
workflow_call:
inputs:
config-path:
required: true
type: string
secrets:
token:
required: true
jobs:
triage:
runs-on: ubuntu-latest
steps:
- uses: actions/labeler@v4
with:
repo-token: ${{ secrets.token }}
configuration-path: ${{ inputs.config-path }}
再利用可能なワークフローの呼び出し
uses
キーワードを使用して、再利用可能なワークフローを呼び出します。 ワークフロー内でアクションを使用する場合とは異なり、ジョブ ステップ内からではなく、ジョブ内で再利用可能なワークフローを直接呼び出します。
再利用可能なワークフロー ファイルを参照するには、次の構文を使用します。
{owner}/{repo}/.github/workflows/{filename}@{ref}
パブリックと内部リポジトリの再利用可能ワークフローの
{ref}
には、SHA、リリース タグ、またはブランチ名を指定できます。 コミット SHA を使用することが、安定性とセキュリティにとって最も安全です。 詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。
複数のワークフローを呼び出し、それぞれを個別のジョブで参照できます。
jobs:
call-workflow-1-in-local-repo:
uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
call-workflow-in-another-repo:
uses: octo-org/another-repo/.github/workflows/workflow.yml@v1
再利用可能なワークフローに入力とシークレットを渡す
名前付き入力を呼び出されたワークフローに渡すには、ジョブで with
キーワードを使用します。 secrets
キーワードを使用して名前付きシークレットを渡します。 入力の場合、入力値のデータ型は、呼び出されたワークフローで指定された型 (ブール値、数値、または文字列) と一致する必要があります。
jobs:
call-workflow-passing-data:
uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
with:
config-path: .github/labeler.yml
secrets:
envPAT: ${{ secrets.envPAT }}
再利用可能なワークフローを呼び出すジョブでサポートされているキーワード
再利用可能なワークフローを呼び出すときは、呼び出しを含むジョブで次のキーワードのみを使用できます。
-
注:
-
呼び出し元のジョブで
jobs.<job_id>.permissions
が指定されていない場合は、呼び出し先ワークフローにはGITHUB_TOKEN
に対する既定のアクセス許可が与えられます。 詳しくは、「自動トークン認証」を参照してください。 -
呼び出し元ワークフローから渡された
GITHUB_TOKEN
アクセス許可は、呼び出し先ワークフローによってダウングレードのみできます (昇格されません)。
-
呼び出し元ワークフローの例
このワークフロー ファイルでは、2 つのワークフロー ファイルを呼び出します。 このうち 2 つ目の workflow-B.yml
(再利用可能なワークフローの例に示されています) では、入力 (config-path
) とシークレット (token
) が渡されます。
name: Call a reusable workflow
on:
pull_request:
branches:
- main
jobs:
call-workflow:
uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1
call-workflow-passing-data:
permissions:
contents: read
pull-requests: write
uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
with:
config-path: .github/labeler.yml
secrets:
token: ${{ secrets.GITHUB_TOKEN }}
再利用可能なワークフローからの出力の使用
再利用可能なワークフローでは、呼び出し元ワークフローで使用するデータが生成される場合があります。 これらの出力を使用するには、再利用可能なワークフローの出力として指定する必要があります。
次の再利用可能なワークフローには、2 つのステップを含む 1 つのジョブがあります。 これらの各ステップでは、"hello" と "world" という 1 つの単語を出力として設定します。 ジョブの outputs
セクションでは、これらのステップの出力を、output1
と output2
というジョブ出力にマップします。 次に on.workflow_call.outputs
セクションで、ワークフロー自体に対して 2 つの出力を定義します。1 つは firstword
といい output1
にマップされ、もう 1 つは secondword
といい output2
にマップされます。
name: Reusable workflow
on:
workflow_call:
# Map the workflow outputs to job outputs
outputs:
firstword:
description: "The first output string"
value: ${{ jobs.example_job.outputs.output1 }}
secondword:
description: "The second output string"
value: ${{ jobs.example_job.outputs.output2 }}
jobs:
example_job:
name: Generate output
runs-on: ubuntu-latest
# Map the job outputs to step outputs
outputs:
output1: ${{ steps.step1.outputs.firstword }}
output2: ${{ steps.step2.outputs.secondword }}
steps:
- id: step1
run: echo "::set-output name=firstword::hello"
- id: step2
run: echo "::set-output name=secondword::world"
これで、同じワークフロー内のジョブからの出力を使用するのと同じ方法で、呼び出し元ワークフローの出力を使用できるようになりました。 再利用可能なワークフローのワークフロー レベルで定義した名前、firstword
と secondword
を使用して、出力を参照します。 このワークフローでは、job1
によって再利用可能なワークフローが呼び出され、job2
によって再利用可能なワークフローの出力 ("hello world") がワークフロー ログの標準出力に出力されます。
name: Call a reusable workflow and use its outputs
on:
workflow_dispatch:
jobs:
job1:
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1
job2:
runs-on: ubuntu-latest
needs: job1
steps:
- run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}
ジョブの出力の使用について詳しくは、「GitHub Actions のワークフロー構文」を参照してください。
使用されているワークフローの監視
GitHub REST API を使用して、再利用可能なワークフローがどのように使用されているかを監視できます。 prepared_workflow_job
監査ログ アクションは、ワークフロー ジョブが開始されるとトリガーされます。 記録されるデータには次のものが含まれます。
-
repo
- ワークフロー ジョブが配置されている Organization/リポジトリ。 別のワークフローを呼び出すジョブの場合、これは呼び出し元ワークフローの Organization/リポジトリです。 -
@timestamp
- ジョブが開始された日時 (UNIX エポック形式)。 -
job_name
- 実行されたジョブの名前。 -
job_workflow_ref
- 使用されたワークフロー ファイル。形式は{owner}/{repo}/{path}/{filename}@{ref}
。 別のワークフローを呼び出すジョブの場合、これは呼び出し先ワークフローを示します。
REST API を使って組織の監査ログを照会する方法については、「Organizations」を参照してください。
注: prepared_workflow_job
の監査データは、REST API を使用してのみ表示できます。 GitHub Web インターフェイスでは表示されず、JSON/CSV 形式でエクスポートされる監査データにも含まれません。
次の手順
GitHub Actions についてさらに学ぶには、「ワークフローをトリガーするイベント」をご覧ください。