Skip to main content

ワークフローの再利用

既存のワークフローを再利用してワークフローを作成するときに重複を回避する方法について説明します。

注: 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.tokensecrets.GITHUB_TOKEN へのアクセス権が自動的に付与されます。 github コンテキストの詳細については、GitHub Actions のコンテキストと式の構文に関するページを参照してください。

GitHub Actions ワークフローで参照されている再利用ワークフローは、ユーザーのワークフローを含むリポジトリの依存関係グラフで依存関係として表示できます。 詳細については、「依存関係グラフについて」を参照してください。

再利用可能なワークフローとスターター ワークフロー

スターター ワークフローを使用すると、ワークフローを作成するアクセス許可を持つ Organization 内のすべての人が、より迅速かつ簡単にワークフローを作成できます。 新しいワークフローを作成する場合は、スターター ワークフローを選択すると、ワークフローを作成する作業の一部またはすべてが自動的に行われます。 スターター ワークフロー内では、再利用可能なワークフローを参照して、一元管理されたワークフロー コードを再利用するメリットを簡単に得ることもできます。 再利用可能なワークフローを参照するときにコミット SHA を使うと、そのワークフローを再利用するすべてのユーザーが必ず同じ YAML コードを使用するようにできます。 ただし、タグまたはブランチを使用して再利用可能なワークフローを参照する場合は、そのバージョンのワークフローを信頼できることを確認してください。 詳細については、「GitHub Actions のセキュリティ強化」を参照してください。

詳細については、「Organization のスターター ワークフローの作成」を参照してください。

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

次のいずれかが true の場合、再利用可能なワークフローを別のワークフローで使用できます。

  • どちらのワークフローも同じリポジトリ内にある。
  • 呼び出し先ワークフローがパブリック リポジトリ。
  • 呼び出し先ワークフローが内部リポジトリに格納され、そのリポジトリの設定によりアクセス可能になっている。 詳しくは、「アクションとワークフローを企業と共有する」、をご覧ください。

ランナーの使用

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

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

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

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

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

制限事項

  • 最大 4 つのレベルのワークフローに接続できます。 詳しくは、「再利用可能なワークフローを入れ子にする」を参照してください。

  • 1 つのワークフロー ファイルから最大 20 個の再利用可能なワークフローを呼び出すことができます。 この制限には、最上位の呼び出し元ワークフロー ファイルから始まる、呼び出される可能性がある入れ子になった再利用可能なワークフローのツリーが含まれます。

    たとえば、top-level-caller-workflow.ymlcalled-workflow-1.ymlcalled-workflow-2.yml は、2 つの再利用可能なワークフローとしてカウントされます。

  • プライベート リポジトリ内に格納されている再利用可能なワークフローは、同じリポジトリ内のワークフローでのみ使うことができます。

  • 呼び出し元ワークフローのワークフロー レベルで定義され、env コンテキストで設定されている環境変数は、呼び出し先ワークフローには反映されません。 詳しくは、「変数」と「コンテキスト」をご覧ください。

  • 複数のワークフローで変数を再利用するには、これを Organization レベル、リポジトリ レベル、または環境レベルで設定し、vars コンテキストを使って参照します。 詳しくは、「変数」と「コンテキスト」をご覧ください。

  • 複合アクションが使用されている場合、再利用可能なワークフローを別のリポジトリから使うことはできません。 詳細については、「カスタム アクションについて」を参照してください。

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

再利用可能なワークフローは、他のワークフロー ファイルとよく似た YAML 形式のファイルです。 他のワークフロー ファイルと同様に、再利用可能なワークフローは、リポジトリの .github/workflows ディレクトリ内にあります。 workflows ディレクトリのサブディレクトリはサポートされていません。

ワークフローを再利用可能にするには、 on の値に workflow_call を含める必要があります。

on:
  workflow_call:

再利用可能なワークフローでの入力とシークレットの使用

入力とシークレットを定義し、呼び出し元のワークフローから渡して、呼び出し先ワークフロー内で使用できます。 再利用可能なワークフローで入力またはシークレットを使用するには、3 つの段階があります。

  1. 再利用可能なワークフローで、inputssecrets のキーワードを使用して、呼び出し元ワークフローから渡す入力またはシークレットを定義します。

    on:
      workflow_call:
        inputs:
          config-path:
            required: true
            type: string
        secrets:
          envPAT:
            required: true
    

    入力とシークレットを定義するための構文の詳細については、on.workflow_call.inputson.workflow_call.secrets を参照してください。

  2. 再利用可能なワークフローで、前の手順で 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 }}
    

    上記の例では、envPATproduction 環境に追加された環境シークレットです。 したがって、この環境はジョブ内で参照されます。

    : 環境シークレットは、リポジトリ用に定義した環境に格納される、暗号化された文字列です。 環境シークレットは、当該の環境を参照するワークフロー ジョブからのみ利用できます。 詳細については、「デプロイに環境を使用する」を参照してください。

  3. 呼び出し元ワークフローから入力またはシークレットを渡します。

    名前付き入力を呼び出されたワークフローに渡すには、ジョブで 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 }}

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

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

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

このワークフロー ファイルでは、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.ymlcalled-workflow-1.ymlcalled-workflow-2.ymlcalled-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 セクションでは、これらのステップの出力を、output1output2 というジョブ出力にマップします。 次に 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"

これで、同じワークフロー内のジョブからの出力を使用するのと同じ方法で、呼び出し元ワークフローの出力を使用できるようになりました。 再利用可能なワークフローのワークフロー レベルで定義した名前、firstwordsecondword を使用して、出力を参照します。 このワークフローでは、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 を使用して Organization の監査ログを照会する方法については、「Organization」を参照してください。

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

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

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

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

次の手順

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

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