ワークフローの再利用

概要

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

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

注: 呼び出し元ワークフローで 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

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

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

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

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

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

次の再利用可能なワークフローには、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 "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

これで、同じワークフロー内のジョブからの出力を使用するのと同じ方法で、呼び出し元ワークフローの出力を使用できるようになりました。再利用可能なワークフローのワークフローレベルで定義した名前、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 - 実行されたジョブの名前。
job_workflow_ref - 使用されたワークフローファイル。形式は {owner}/{repo}/{path}/{filename}@{ref}。別のワークフローを呼び出すジョブの場合、これは呼び出し先ワークフローを示します。

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

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

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

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

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

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

次の手順

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

特定の再利用可能なワークフローのみを実行できるセルフホストランナーグループを作成することで、デプロイを標準化できます。詳細については、「グループを使用してセルフホストランナーへのアクセスを管理する」を参照してください。

ワークフローの再利用

この記事の内容