ワークフローの再利用

概要

あるワークフローから別のワークフローにコピーして貼り付けるのではなく、ワークフローを再利用できます。再利用可能なワークフローにアクセスできるユーザーは誰でも、別のワークフローから再利用可能なワークフローを呼び出すことができます。

ワークフローを再利用すると、重複が回避されます。これにより、ワークフローの管理が容易になり、アクションと同様に、他のユーザーの作業を基にして新しいワークフローをより迅速に作成できます。また、ワークフローを再利用すると、適切に設計され、既にテスト済みで、効果的であることが証明されているワークフローを使用でき、ベストプラクティスが促進されます。 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 のスターターワークフローを作成する」を参照してください。

再利用可能なワークフローへのアクセス

次のいずれかを満たしていれば、別のワークフローから再利用可能なワークフローを使用できます。

どちらのワークフローも同じリポジトリ内にある。
呼び出し先ワークフローがパブリックリポジトリに格納されており、Organization でパブリックの再利用可能なワークフローを使うことができる。
呼び出し先ワークフローがプライベートリポジトリに格納され、そのリポジトリの設定でアクセス可能になっている。詳しくは、「アクションとワークフローを組織と共有する」と「プライベートリポジトリからのアクションとワークフローの共有」を参照してください。

ランナーの使用

GitHub ホステッドランナーの使用

GitHub ホステッドランナーの割り当ては、常に呼び出し元のコンテキストのみを使用して評価されます。 GitHub ホステッドランナーの支払いは、常に呼び出し元に関連付けられます。呼び出し元ワークフローは、呼び出し先リポジトリの GitHub ホステッドランナーを使用できません。詳しくは、「GitHub ホステッドランナーの概要」を参照してください。

セルフホストランナーの使用

呼び出し元ワークフローと同じユーザーまたは Organization が所有する呼び出し先ワークフローでは、呼び出し元のコンテキストからセルフホストランナーにアクセスできます。つまり、呼び出し先ワークフローでは、次のセルフホストランナーにアクセスできます。

呼び出し元リポジトリ内
呼び出し元リポジトリの Organization 内にあり、ランナーが呼び出し元リポジトリで使用できるようになっている

制限事項

最大 4 つのレベルのワークフローに接続できます。詳しくは、「再利用可能なワークフローを入れ子にする」を参照してください。
1 つのワークフローファイルから最大 20 個の再利用可能なワークフローを呼び出すことができます。この制限には、最上位の呼び出し元ワークフローファイルから始まる、呼び出される可能性がある入れ子になった再利用可能なワークフローのツリーが含まれます。

たとえば、top-level-caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml は、2 つの再利用可能なワークフローとしてカウントされます。
呼び出し元ワークフローのワークフローレベルで定義され、env コンテキストで設定されている環境変数は、呼び出し先ワークフローには反映されません。詳細については、「変数」および「コンテキスト」を参照してください。
同様に、呼び出されたワークフローで定義されている env コンテキストで設定された環境変数は、呼び出し元ワークフローの env コンテキストではアクセスできません。代わりに、再利用可能なワークフローの出力を使用する必要があります。詳細については、「ワークフローの再利用」を参照してください。
複数のワークフローで変数を再利用するには、これを Organization レベル、リポジトリレベル、または環境レベルで設定し、vars コンテキストを使って参照します。詳しくは、「変数」と「コンテキスト」をご覧ください。
再利用可能なワークフローは、ジョブステップ内からではなく、ジョブ内で直接呼び出されます。したがって、GITHUB_ENV を使用して、呼び出し元ワークフローのジョブステップに値を渡すことはできません。

再利用可能なワークフローの作成

再利用可能なワークフローは、他のワークフローファイルとよく似た 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 キーに定義した入力またはシークレットを参照します。

注: 呼び出し元ワークフローで secrets: inherit を使用してシークレットが継承されている場合は、on キーに明示的に定義されていない場合でも参照できます。詳しくは、「GitHub Actions のワークフロー構文」を参照してください。
```
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 }}
```
同じ Organizatio または Enterprise 内の再利用可能なワークフローを呼び出すワークフローでは、inherit キーワードを使ってシークレットを暗黙的に渡すことができます。
```
jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit
```

再利用可能なワークフローの例

この再利用可能な workflow-B.yml という名前のワークフローファイル (後述の呼び出し元ワークフローの例でこれを参照します) では、入力文字列とシークレットを呼び出し元ワークフローから受け取り、それらをアクションで使用します。

YAML

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 キーワードを使用して、再利用可能なワークフローを呼び出します。ワークフロー内でアクションを使用する場合とは異なり、ジョブステップ内からではなく、ジョブ内で再利用可能なワークフローを直接呼び出します。

jobs.<job_id>.uses

再利用可能なワークフローファイルを参照するには、次のいずれかの構文を使用します。

{owner}/{repo}/.github/workflows/{filename}@{ref}パブリックとプライベートリポジトリの再利用可能ワークフローの。
./.github/workflows/{filename} は同じリポジトリ内の再利用可能なワークフローの場合。

{ref} には、SHA、リリースタグ、またはブランチ名を指定できます。コミット SHA を使用することが、安定性とセキュリティにとって最も安全です。詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。 2 番目の構文オプションを ({owner}/{repo} および @{ref} なしで) 使用する場合、呼び出されたワークフローは呼び出し元ワークフローと同じコミットから取得されます。

複数のワークフローを呼び出し、それぞれを個別のジョブで参照できます。

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  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 }}

同じ Organizatio または Enterprise 内の再利用可能なワークフローを呼び出すワークフローでは、inherit キーワードを使ってシークレットを暗黙的に渡すことができます。

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

再利用可能なワークフローでのマトリックス戦略の使用

マトリックス戦略を使用するジョブでは、再利用可能なワークフローを呼び出すことができます。

マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。たとえば、マトリックス戦略を使用して、再利用可能なワークフローに異なる入力を渡すことができます。マトリックスの詳細については、「ジョブにマトリックスを使用する」を参照してください。

次のジョブ例では、再利用可能なワークフローを呼び出し、値 [dev, stage, prod] を使用して変数 target を定義することによってマトリックスコンテキストを参照します。変数の値ごとに 1 つずつ、3 つのジョブが実行されます。

YAML

jobs:
  ReuseableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

再利用可能なワークフローを呼び出すジョブでサポートされているキーワード

再利用可能なワークフローを呼び出すときは、呼び出しを含むジョブで次のキーワードのみを使用できます。

jobs.<job_id>.name
jobs.<job_id>.uses
jobs.<job_id>.with
jobs.<job_id>.with.<input_id>
jobs.<job_id>.secrets
jobs.<job_id>.secrets.<secret_id>
jobs.<job_id>.secrets.inherit
jobs.<job_id>.strategy
jobs.<job_id>.needs
jobs.<job_id>.if
jobs.<job_id>.permissions
jobs.<job_id>.concurrency
注:
- 呼び出し元のジョブで jobs.<job_id>.permissions が指定されていない場合は、呼び出し先ワークフローには GITHUB_TOKEN に対する既定のアクセス許可が与えられます。詳しくは、「自動トークン認証」を参照してください。
- 呼び出し元ワークフローから渡された GITHUB_TOKEN アクセス許可は、呼び出し先ワークフローによってダウングレードのみできます (昇格されません)。

呼び出し元ワークフローの例

このワークフローファイルでは、2 つのワークフローファイルを呼び出します。このうち 2 つ目の workflow-B.yml (再利用可能なワークフローの例に示されています) では、入力 (config-path) とシークレット (token) が渡されます。

YAML

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 }}

再利用可能なワークフローを入れ子にする

最大 4 つのレベルのワークフロー (つまり、最上位の呼び出し元ワークフローと最大 3 つのレベルの再利用可能なワークフロー) を接続できます。たとえば、caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml → called-workflow-3.yml です。ワークフローツリー内のループは許可されません。

再利用可能なワークフロー内から、別の再利用可能なワークフローを呼び出すことができます。

YAML

name: Reusable workflow

on:
  workflow_call:

jobs:
  call-another-reusable:
    uses: octo-org/example-repo/.github/workflows/another-reusable.yml@v1

入れ子になったワークフローにシークレットを渡す

呼び出し元ワークフローで jobs.<job_id>.secrets を使用して、直接呼び出されたワークフローに名前付きシークレットを渡すことができます。または、jobs.<job_id>.secrets.inherit を使用して、呼び出し元ワークフローのすべてのシークレットを直接呼び出されたワークフローに渡すことができます。詳しくは、上記の「ワークフローの再利用」セクションと、参照記事「GitHub Actions のワークフロー構文」を参照してください。シークレットは直接呼び出されたワークフローにのみ渡されるため、ワークフローチェーン A > B > C の場合、ワークフロー C では、A から B に、次に B から C に渡された場合にのみ A からシークレットを受け取ります。

次の例では、ワークフロー A で inherit キーワードを使用してすべてのシークレットをワークフロー B に渡しますが、ワークフロー B ではワークフロー C に 1 つのシークレットのみを渡します。ワークフロー B に渡されるその他のシークレットはいずれもワークフロー C では使用できません。

jobs:
  workflowA-calls-workflowB:
    uses: octo-org/example-repo/.github/workflows/B.yml@main
    secrets: inherit # pass all secrets

jobs:
  workflowB-calls-workflowC:
    uses: different-org/example-repo/.github/workflows/C.yml@main
    secrets:
      envPAT: ${{ secrets.envPAT }} # pass just this secret

アクセスおよびアクセス許可

入れ子になった再利用可能なワークフローを含むワークフローは、入れ子になったワークフローのいずれかが最初の呼び出し元ワークフローにアクセスできない場合に失敗します。詳しくは、「ワークフローの再利用」を参照してください。

GITHUB_TOKEN アクセス許可は、入れ子になったワークフローでのみ同じまたはより制限的にすることができます。たとえば、ワークフローチェーン A > B > C では、ワークフロー A に package: read トークンアクセス許可がある場合、B と C は package: write アクセス許可を持つことができません。詳しくは、「自動トークン認証」を参照してください。

API を使用して、特定のワークフロー実行に関係していたワークフローファイルを特定する方法については、「使用されているワークフローの監視」を参照してください。

再利用可能なワークフローからの出力の使用

再利用可能なワークフローでは、呼び出し元ワークフローで使用するデータが生成される場合があります。これらの出力を使用するには、再利用可能なワークフローの出力として指定する必要があります。

出力を設定する再利用可能なワークフローがマトリックス戦略で実行される場合、その出力は、実際に値を設定するマトリックスの最後の正常に完了した再利用可能なワークフローで設定された出力になります。つまり、最後の正常に完了した再利用可能なワークフローでその出力に空の文字列が設定され、最後から 2 番目の正常に完了した再利用可能なワークフローでその出力の実際の値が設定された場合、出力には最後から 2 番目の完了した再利用可能なワークフローの値が含まれます。

次の再利用可能なワークフローには、2 つのステップを含む 1 つのジョブがあります。これらの各ステップでは、"hello" と "world" という 1 つの単語を出力として設定します。ジョブの outputs セクションでは、これらのステップの出力を、output1 と output2 というジョブ出力にマップします。次に on.workflow_call.outputs セクションで、ワークフロー自体に対して 2 つの出力を定義します。1 つは firstword といい output1 にマップされ、もう 1 つは secondword といい output2 にマップされます。

YAML

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 "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

これで、同じワークフロー内のジョブからの出力を使用するのと同じ方法で、呼び出し元ワークフローの出力を使用できるようになりました。再利用可能なワークフローのワークフローレベルで定義した名前、firstword と secondword を使用して、出力を参照します。このワークフローでは、job1 によって再利用可能なワークフローが呼び出され、job2 によって再利用可能なワークフローの出力 ("hello world") がワークフローログの標準出力に出力されます。

YAML

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 - 実行されたジョブの名前。
calling_workflow_refs - このワークフロージョブに関係するすべての呼び出し元ワークフローのファイルパスの配列。配列内の項目は、呼び出された逆の順序になります。たとえば、ワークフロー A > B > C のチェーンでは、ワークフロー C 内のジョブのログを表示する場合、配列は ["octo-org/octo-repo/.github/workflows/B.yml", "octo-org/octo-repo/.github/workflows/A.yml"] になります。
calling_workflow_shas - このワークフロージョブに関係するすべての呼び出し元ワークフローの SHA の配列。配列には、calling_workflow_refs 配列と同じ順序で同じ数の項目が含まれています。
job_workflow_ref - 使用されたワークフローファイル。形式は {owner}/{repo}/{path}/{filename}@{ref}。別のワークフローを呼び出すジョブの場合、これは呼び出し先ワークフローを示します。

REST API を使って組織の監査ログを照会する方法については、「組織」を参照してください。

注: prepared_workflow_job の監査データは、REST API を使用してのみ表示できます。 GitHub Web インターフェイスでは表示されず、JSON/CSV 形式でエクスポートされる監査データにも含まれません。

再利用可能なワークフローでワークフローとジョブを再実行する

パブリックリポジトリの再利用可能なワークフローは、SHA、リリースタグ、またはブランチ名を使って参照できます。詳しくは、「ワークフローの再利用」を参照してください。

再利用可能なワークフローを使うワークフローを再実行し、参照が SHA ではない場合は、注意すべきいくつかの動作があります。

ワークフロー内のすべてのジョブを再実行すると、指定した参照の再利用可能なワークフローが使われます。ワークフロー内のすべてのジョブの再実行について詳しくは、「ワークフローとジョブの再実行」をご覧ください。
失敗したジョブまたはワークフロー内の特定のジョブを再実行すると、最初の試行と同じコミット SHA の再利用可能なワークフローが使われます。ワークフロー内の失敗したジョブの再実行について詳しくは、「ワークフローとジョブの再実行」をご覧ください。ワークフロー内の特定のジョブの再実行について詳しくは、「ワークフローとジョブの再実行」をご覧ください。

次の手順

GitHub Actions についてさらに学ぶには、「ワークフローをトリガーするイベント」をご覧ください。

ワークフローの再利用

この記事の内容