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

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

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

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

特定の再利用可能なワークフローのみを実行できるセルフホステッド ランナー グループを作成することで、デプロイを標準化できます。 詳細については、 [AUTOTITLE を](/ja/enterprise-server@3.22/actions/how-tos/manage-runners/self-hosted-runners/manage-access)参照してください。

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

```yaml
on:
  workflow_call:
```

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

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

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

   ```yaml
   on:
     workflow_call:
       inputs:
         config-path:
           required: true
           type: string
       secrets:
         personal_access_token:
           required: true
   ```

   入力とシークレットを定義するための構文の詳細については、 [`on.workflow_call.inputs`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_callinputs) と [`on.workflow_call.secrets`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_callsecrets)を参照してください。

2. 再利用可能なワークフローで、前の手順で `on` キーに定義した入力またはシークレットを参照します。

   > \[!NOTE]
   > 注: 呼び出し元ワークフローで `secrets: inherit` を使用してシークレットが継承されている場合は、`on` キーに明示的に定義されていない場合でも参照できます。 詳しくは、「[GitHub Actions　のワークフロー構文](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretsinherit)」をご覧ください。

   ```yaml
   jobs:
     reusable_workflow_job:
       runs-on: ubuntu-latest
       steps:
       - uses: actions/labeler@v6
         with:
           repo-token: ${{ secrets.personal_access_token }}
           configuration-path: ${{ inputs.config-path }}
   ```

   上記の例では、 `personal_access_token` リポジトリまたは組織レベルで定義されているシークレットです。

   > \[!WARNING]
   > `on.workflow_call` は `environment` キーワード (keyword) をサポートしていないため、呼び出し元のワークフローから環境シークレットを渡すことはできません。 `environment`再利用可能なワークフローにジョブ レベルで含める 場合、呼び出し元のワークフローから渡されたシークレットではなく、環境シークレットが使用されます。 詳細については、「[デプロイメント用の環境管理](/ja/enterprise-server@3.22/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)」および「[GitHub Actions　のワークフロー構文](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_call)」を参照してください。

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

   名前付き入力を呼び出されたワークフローに渡すには、ジョブで `with` キーワードを使用します。 `secrets` キーワードを使用して名前付きシークレットを渡します。 入力の場合、入力値のデータ型は、呼び出されたワークフローで指定された型 (ブール値、数値、または文字列) と一致する必要があります。

   ```yaml
   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` キーワードを使ってシークレットを暗黙的に渡すことができます。

   ```yaml
   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` という名前のワークフロー ファイル (後述の[呼び出し元ワークフローの例](#example-caller-workflow)でこれを参照します) では、入力文字列とシークレットを呼び出し元ワークフローから受け取り、それらをアクションで使用します。

```yaml copy
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@v6
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}
```

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

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

[`jobs.<job_id>.uses`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iduses)

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

* `$/.github/workflows/{filename}` 同じリポジトリ内の再利用可能なワークフローの場合。 これは、同じリポジトリ内の再利用可能なワークフローを参照するための推奨構文です。 この構文は、 GitHub Enterprise Serverでは使用できません。
* `{owner}/{repo}/.github/workflows/{filename}@{ref}`
  、パブリック リポジトリ、内部リポジトリ、プライベート リポジトリの再利用可能なワークフロー向け
* `./.github/workflows/{filename}` 同じリポジトリ内の再利用可能なワークフロー用。

`{owner}/{repo}`と`@{ref}`を使用して再利用可能なワークフローを参照する場合、`{ref}`には SHA、リリース タグ、またはブランチ名を指定できます。 リリース タグとブランチの名前が同じ場合は、リリース タグがブランチの名前よりも優先されます。 コミット SHA を使用することが、安定性とセキュリティにとって最も安全なオプションです。 詳しくは、「[セキュリティで保護された使用に関するリファレンス](/ja/enterprise-server@3.22/actions/reference/security/secure-use#reusing-third-party-workflows)」をご覧ください。

`$/`または`./` (`{owner}/{repo}`および`@{ref}`なし) を使用して同じリポジトリ内の再利用可能なワークフローを参照する場合、呼び出されたワークフローは呼び出し元ワークフローと同じコミットから取得されます。
`$/`参照には`@{ref}`サフィックスを含めてはなりません。また、`$/`はGitHub Enterprise Serverで使用できません。
`refs/heads` や `refs/tags` などの ref プレフィックスは使用できません。 このキーワード中では、コンテキストや式を使うことはできません。

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

```yaml
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
  # The `$/` syntax is not available in GitHub Enterprise Server.
  call-workflow-in-same-repo-at-running-commit:
    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` ([再利用可能なワークフローの例](#example-reusable-workflow)に示されています) では、入力 (`config-path`) とシークレット (`token`) が渡されます。

```yaml copy
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` キーワードを使用して名前付きシークレットを渡します。 入力の場合、入力値のデータ型は、呼び出されたワークフローで指定された型 (ブール値、数値、または文字列) と一致する必要があります。

```yaml
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` キーワードを使ってシークレットを暗黙的に渡すことができます。

```yaml
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 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。 たとえば、マトリックス戦略を使用して、再利用可能なワークフローに異なる入力を渡すことができます。 マトリックスの詳細については、「[ワークフローでのジョブのバリエーションの実行](/ja/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations)」を参照してください。

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

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

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

最上位レベルの呼び出し元ワークフローと最大 9 レベルの再利用可能なワークフローなど、最大 ワークフローは4レベルまで、つまり最上位の呼び出し元ワークフローと、最大3レベルの再利用可能なワークフローです。 たとえば: *caller-workflow\.yml* → *called-workflow-1.yml* → *called-workflow-2.yml* → *called-workflow-3.yml*。

ワークフロー ツリー内のループは許可されません。

> \[!NOTE] 入れ子になった再利用可能なワークフローでは、チェーン内のすべてのワークフローに呼び出し元がアクセスできる必要があります。アクセス許可は、チェーン全体を通して維持または降格されるだけであり、昇格されることはありません。 詳しくは、「[ワークフロー構成の再利用](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/reusing-workflow-configurations)」をご覧ください。

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

```yaml copy
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` を使用して、呼び出し元ワークフローのすべてのシークレットを直接呼び出されたワークフローに渡すことができます。 詳しくは、上記の「[ワークフローを再利用する](/ja/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#passing-inputs-and-secrets-to-a-reusable-workflow)」セクションと、参照記事「[GitHub Actions　のワークフロー構文](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretsinherit)」を参照してください。 シークレットは直接呼び出されたワークフローにのみ渡されるため、ワークフロー チェーン A > B > C、ワークフロー C では、A から B に、次に B から C に渡された場合にのみ A からシークレットを受け取ります。

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

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

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

詳細については、「[ジョブ間で情報を渡す](/ja/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/pass-job-outputs)」および「[GitHub Actions　のワークフロー構文](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#onworkflow_calloutputs)」を参照してください。

```yaml copy
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 copy
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　のワークフロー構文](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idoutputs)」を参照してください。 ワークフロー間で変数以外の変数 (ビルド成果物など) を共有する場合は、「[ワークフロー成果物を使ったデータの格納と共有](/ja/enterprise-server@3.22/actions/tutorials/store-and-share-data)」を参照してください。

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

GitHub Enterprise Cloudを使用する組織は、GitHub REST API を介して監査ログを操作して、使用されているワークフローを監視できます。 詳細については、[GitHub Enterprise Cloudドキュメントを参照してください](/ja/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#using-the-audit-log-api)。

## 次のステップ

ワークフローの再利用の複雑さの詳細については、「[ワークフロー構成の再利用](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/reusing-workflow-configurations)」を参照してください。