Skip to main content
ドキュメントへの更新が頻繁に発行されており、このページの翻訳はまだ行われている場合があります。 最新の情報については、「英語のドキュメント」を参照してください。
現在、GitHub AE は限定的リリースです。

ワークフローの再利用

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

概要

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

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

ランナーの使用

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

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

制限事項

  • 再利用可能なワークフローでは、他の再利用可能なワークフローを呼び出すことはできません。
  • 1 つのワークフロー ファイルから最大 20 個の再利用可能なワークフローを呼び出すことができます。
  • プライベート リポジトリ内に格納されている再利用可能なワークフローは、同じリポジトリ内のワークフローでのみ使うことができます。* strategy プロパティは、再利用可能なワークフローを呼び出すジョブではサポートされていません。
  • 呼び出し元ワークフローのワークフロー レベルで定義され、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 キーに定義した入力またはシークレットを参照します。

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

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

この再利用可能な 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}パブリックと内部リポジトリの再利用可能ワークフローの

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

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

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

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

このワークフロー ファイルでは、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 セクションでは、これらのステップの出力を、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 - 実行されたジョブの名前。

  • job_workflow_ref - 使用されたワークフロー ファイル。形式は {owner}/{repo}/{path}/{filename}@{ref}。 別のワークフローを呼び出すジョブの場合、これは呼び出し先ワークフローを示します。

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

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

次の手順

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