ワークフローを再利用する

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

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

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

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

on:
  workflow_call:

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

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

再利用可能なワークフローで、inputs と secrets のキーワードを使用して、呼び出し元ワークフローから渡す入力またはシークレットを定義します。
```
on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      personal_access_token:
        required: true
```
入力とシークレットを定義するための構文の詳細については、on.workflow_call.inputs と on.workflow_call.secrets を参照してください。
再利用可能なワークフローで、前の手順で on キーに定義した入力またはシークレットを参照します。

メモ

呼び出し元ワークフローで secrets: inherit を使用してシークレットが継承されている場合は、on キーに明示的に定義されていない場合でも参照できます。詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。
```
jobs:
  reusable_workflow_job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.personal_access_token }}
        configuration-path: ${{ inputs.config-path }}
```
上記の例では、 personal_access_token リポジトリまたは組織レベルで定義されているシークレットです。

警告

on.workflow_call は environment キーワード (keyword) をサポートしていないため、呼び出し元のワークフローから環境シークレットを渡すことはできません。 environment再利用可能なワークフローにジョブレベルで含める場合、呼び出し元のワークフローから渡されたシークレットではなく、環境シークレットが使用されます。詳細については、「デプロイに環境の使用」および「GitHub Actions　のワークフロー構文」を参照してください。
呼び出し元ワークフローから入力またはシークレットを渡します。

名前付き入力を呼び出されたワークフローに渡すには、ジョブで 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:
      personal_access_token: ${{ secrets.token }}
```
同じ organization または 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 }}

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 を使用することが、安定性とセキュリティにとって最も安全なオプションです。詳しくは、「セキュリティで保護された使用に関するリファレンス」をご覧ください。

2 番目の構文オプションを ({owner}/{repo} および @{ref} なしで) 使用する場合、呼び出されたワークフローは呼び出し元ワークフローと同じコミットから取得されます。 refs/heads や refs/tags などの 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

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

このワークフローファイルでは、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 }}

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

再利用可能なワークフローに入力とシークレットを渡す

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

同じ organization または 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:
  ReusableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

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

最大 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

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:
      repo-token: ${{ secrets.personal_access_token }} # pass just this secret

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

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

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

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

value は、呼び出されたワークフロー内のジョブレベルの出力の値に設定する必要があります。次に示すように、ステップレベルの出力はまずジョブレベルの出力にマップする必要があります。

詳細については、「ジョブ間で情報を渡す」および「GitHub Actions　のワークフロー構文」を参照してください。

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

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

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　のワークフロー構文」を参照してください。ワークフロー間で変数以外の変数 (ビルド成果物など) を共有する場合は、「Store and share data with workflow artifacts」を参照してください。

使用されているワークフローの監視

GitHub Enterprise Cloud を使う organization は、GitHub REST API を介して監査ログを操作し、どのワークフローが使われているかを監視できます。詳細については、GitHub Enterprise Cloud ドキュメントを参照してください。

次のステップ

ワークフローの再利用の複雑さについては、「再利用可能ワークフローリファレンス」をご覧ください。

この記事の内容

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

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

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

再利用可能なワークフローの呼び出し

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

再利用可能なワークフローに入力とシークレットを渡す

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

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

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

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

使用されているワークフローの監視

次のステップ