# ワークフロー構成の再利用

既存のワークフローを再利用し。

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

この記事では、アクセス ルール、制限事項、サポートされているキーワード、ランナーの動作など、再利用可能なワークフローとワークフロー テンプレートのリファレンス情報を提供します。

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

次のいずれかを満たしていれば、別のワークフローから再利用可能なワークフローを使用できます。

* どちらのワークフローも同じリポジトリ内にある。

* 呼び出されたワークフローは、上のパブリック リポジトリGitHub Enterprise Serverに格納されます。

GitHub.comで定義されている再利用可能なワークフローを直接使用することはできません。 代わりに、再利用可能なワークフローのコピーを お使いの GitHub Enterprise Server インスタンスに格納し、そのパスからワークフローを呼び出します。

* 呼び出し先ワークフローが内部リポジトリに格納され、そのリポジトリの設定によりアクセス可能になっている。 詳細については、 [AUTOTITLE を](/ja/enterprise-server@3.22/actions/how-tos/reuse-automations/share-with-your-enterprise)参照してください。
* 呼び出し先ワークフローがプライベート リポジトリに格納され、そのリポジトリの設定でアクセス可能になっている。 詳細については、「[アクションとワークフローを企業と共有する](/ja/enterprise-server@3.22/actions/how-tos/reuse-automations/share-with-your-enterprise).

次の表は、ホスト リポジトリの可視性に応じた、呼び出し元ワークフローに対する再利用可能なワークフローのアクセシビリティを示しています。

| 呼び出し元リポジトリ                  | アクセス可能なワークフロー リポジトリ |
| --------------------------- | ------------------- |
| `private`                   |                     |
| `private`                   |                     |
| 、 `internal`、 、および `public` |                     |
|                             |                     |
| `internal`                  |                     |
| `internal`、かつ `public`      |                     |
|                             |                     |
| `public`                    | `public`            |

呼び出し元リポジトリの \[Actions settings] ページの **\[Actions permissions]** は、アクションと再利用可能なワークフローの使用を許可するように構成する必要があります。「[リポジトリのGitHub Actions設定の管理](/ja/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-select-actions-and-reusable-workflows-to-run)」を参照してください。

内部リポジトリまたは private リポジトリの場合は、呼び出し元ワークフローを含むリポジトリからの**アクセス**を許可するように、呼び出されたワークフローのリポジトリの \[アクション設定] ページのアクセス ポリシーを明示的に構成する必要があります。[リポジトリのGitHub Actions設定の管理](/ja/enterprise-server@3.22/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository) を参照してください。

> \[!NOTE]
> セキュリティを強化するため、GitHub Actions はアクションまたは再利用可能なワークフローのリダイレクトをサポートしません。 つまり、所有者、アクションのリポジトリの名前、またはアクションの名前が変更されると、そのアクションを以前の名前で使用するすべてのワークフローは失敗します。

### 再利用可能なワークフローの制限事項

* 最大  4 レベルのワークフローに接続できます。 詳細については、「[再利用可能なワークフローをネスト化する](/ja/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#nesting-reusable-workflows)」を参照してください。

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

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

* 呼び出し元ワークフローのワークフロー レベルで定義され、`env` コンテキストで設定されている環境変数は、呼び出し先ワークフローには反映されません。 詳細については、「[変数に情報を格納する](/ja/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables)」および「[コンテキスト リファレンス](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#env-context)」を参照してください。

* 同様に、呼び出されたワークフローで定義されている `env` コンテキストで設定された環境変数は、呼び出し元ワークフローの `env` コンテキストではアクセスできません。 代わりに、再利用可能なワークフローの出力を使用する必要があります。 詳細については、「[再利用可能なワークフローからの出力の使用](/ja/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#using-outputs-from-a-reusable-workflow)」を参照してください。

* 複数のワークフローで変数を再利用するには、これを Organization レベル、リポジトリ レベル、または環境レベルで設定し、`vars` コンテキストを使って参照します。 詳細については、「[変数に情報を格納する](/ja/enterprise-server@3.22/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables)」および「[コンテキスト リファレンス](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#vars-context)」を参照してください。

* 再利用可能なワークフローは、ジョブ ステップ内からではなく、ジョブ内で直接呼び出されます。 したがって、`GITHUB_ENV` を使用して、呼び出し元ワークフローのジョブ ステップに値を渡すことはできません。

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

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

* [`jobs.<job_id>.name`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idname)
* [`jobs.<job_id>.uses`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_iduses)
* [`jobs.<job_id>.with`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idwith)
* [`jobs.<job_id>.with.<input_id>`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idwithinput_id)
* [`jobs.<job_id>.secrets`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecrets)
* [`jobs.<job_id>.secrets.<secret_id>`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretssecret_id)
* [`jobs.<job_id>.secrets.inherit`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idsecretsinherit)
* [`jobs.<job_id>.strategy`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategy)
* [`jobs.<job_id>.needs`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idneeds)
* [`jobs.<job_id>.if`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idif)
* [`jobs.<job_id>.concurrency`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idconcurrency)
* [`jobs.<job_id>.permissions`](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions)

  > \[!NOTE]
  >
  > * 呼び出し元のジョブで `jobs.<job_id>.permissions` が指定されていない場合は、呼び出し先ワークフローには `GITHUB_TOKEN` に対する既定のアクセス許可が与えられます。 詳しくは、「[GitHub Actions　のワークフロー構文](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/workflow-syntax#permissions)」をご覧ください。
  > * 呼び出し元ワークフローから渡された `GITHUB_TOKEN` アクセス許可は、呼び出し先ワークフローによってダウングレードのみできます (昇格されません)。
  > *

`jobs.<job_id>.concurrency.cancel-in-progress: true` を使用する場合は、呼び出し先ワークフローと呼び出し元ワークフローで `jobs.<job_id>.concurrency.group` に同じ値を使用しないでください。同じ値を使用すると、既に実行されているワークフローがキャンセルされます。 呼び出されたワークフローは、 ${{ github.workflow }}で呼び出し元ワークフローの名前を使用するため、呼び出し元ワークフローと呼び出されたワークフローの両方でこのコンテキストを `jobs.<job_id>.concurrency.group` の値として使用すると、呼び出されたワークフローの実行時に呼び出し元ワークフローが取り消されます。

### 再利用可能ワークフローでランナーを使用する方法

#### GitHub ホステッド ランナー

ホスト GitHubランナーの割り当ては、常に呼び出し元のコンテキストのみを使用して評価されます。
GitHubホステッド ランナーにかかる料金は、常に呼び出し元に関連付けられます。 呼び出し元ワークフローは、呼び出されたリポジトリからホスト GitHubランナーを使用できません。 詳しくは、「[GitHub ホステッド ランナー](/ja/enterprise-server@3.22/actions/concepts/runners/github-hosted-runners)」をご覧ください。

#### セルフホステッド ランナー

呼び出し元ワークフローと同じユーザー、組織、またはエンタープライズが所有するワークフローは、呼び出し元のコンテキストからセルフホステッドランナーにアクセスできます。 つまり、呼び出し先ワークフローでは、次のセルフホスト ランナーにアクセスできます。

* 呼び出し元リポジトリ内
* 呼び出し元リポジトリの組織 またはエンタープライズで、ランナーが呼び出し元リポジトリで使用できるようになった場合

### 入れ子になったワークフローのアクセスとアクセス許可

入れ子になった再利用可能なワークフローを含むワークフローは、入れ子になったワークフローのいずれかが最初の呼び出し元ワークフローにアクセスできない場合に失敗します。 詳しくは、「[再利用可能なワークフローへのアクセス](#access-to-reusable-workflows)」をご覧ください。

`GITHUB_TOKEN` アクセス許可は、入れ子になったワークフローでのみ同じまたはより制限的にすることができます。 たとえば、ワークフロー チェーン A > B > C では、ワークフロー A に `package: read` トークンアクセス許可がある場合、B と C は `package: write` アクセス許可を持つことができません。 詳しくは、「[ワークフローでの認証に GITHUB\_TOKEN を使用する](/ja/enterprise-server@3.22/actions/tutorials/authenticate-with-github_token)」をご覧ください。

API を使って、特定のワークフロー実行に関係していたワークフロー ファイルを特定する方法については、「[ワークフローを再利用する](/ja/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#monitoring-which-workflows-are-being-used)」をご覧ください。

### ジョブを再実行するときの再利用可能ワークフローの動作

パブリック リポジトリの再利用可能なワークフローは、SHA、リリース タグ、またはブランチ名を使って参照できます。 詳しくは、「[ワークフローを再利用する](/ja/enterprise-server@3.22/actions/how-tos/reuse-automations/reuse-workflows#calling-a-reusable-workflow)」をご覧ください。

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

* ワークフロー内のすべてのジョブを再実行すると、指定した参照の再利用可能なワークフローが使われます。 ワークフロー内のすべてのジョブの再実行の詳細については、「[ワークフローとジョブの再実行](/ja/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-all-the-jobs-in-a-workflow)」を参照してください。
* 失敗したジョブまたはワークフロー内の特定のジョブを再実行すると、最初の試行と同じコミット SHA の再利用可能なワークフローが使われます。 ワークフローで失敗したジョブを再実行する方法の詳細については、「[ワークフローとジョブの再実行](/ja/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-failed-jobs-in-a-workflow)」を参照してください。 ワークフロー内の特定のジョブの再実行の詳細については、「[ワークフローとジョブの再実行](/ja/enterprise-server@3.22/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs#re-running-a-specific-job-in-a-workflow)」を参照してください。

### `github` コンテキスト

再利用可能なワークフローが呼び出し元ワークフローによってトリガーされると、 `github` コンテキストが必ず呼び出し元ワークフローに関連付けられます。 呼び出し先ワークフローには、`github.token` と `secrets.GITHUB_TOKEN` へのアクセス権が自動的に付与されます。
`github` コンテキストの詳細については、「[コンテキスト リファレンス](/ja/enterprise-server@3.22/actions/reference/workflows-and-actions/contexts#github-context)」を参照してください。

## ワークフロー テンプレート

Organization のワークフロー テンプレートを作成するときに使う参照情報。

### `$default-branch` プレースホルダー

リポジトリの既定のブランチを参照する必要がある場合は、ワークフロー テンプレートで `$default-branch` プレースホルダーを使用できます。 ワークフローが作成されるとき、プレースホルダーはリポジトリの既定のブランチの名前に自動的に置き換えられます。

### `runs-on` キーのプレースホルダー値

`runs-on` キーの次の値もプレースホルダーとして扱われます。

* `ubuntu-latest` は `[ self-hosted ]` に置き換えられます
* `windows-latest` は `[ self-hosted, windows ]` に置き換えられます
* `macos-latest"` は `[ self-hosted, macOS ]` に置き換えられます

### ワークフロー テンプレート ファイルの例

この `octo-organization-ci.yml` というファイルは、基本的なワークフローを示しています。

```yaml copy
name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Run a one-line script
        run: echo Hello from Octo Organization
```

### メタデータ ファイルの要件

メタデータ ファイルは、ワークフロー ファイルと同じ名前にする必要がありますが、`.yml` 拡張子の代わりに、`.properties.json` を付ける必要があります。 たとえば、`octo-organization-ci.properties.json` という名前のこのファイルには、`octo-organization-ci.yml` という名前のワークフロー ファイルのメタデータが含まれます。

```json copy
{
    "name": "Octo Organization Workflow",
    "description": "Octo Organization CI workflow template.",
    "iconName": "example-icon",
    "categories": [
        "Go"
    ],
    "filePatterns": [
        "package.json$",
        "^Dockerfile",
        ".*\\.md$"
    ]
}
```

* `name`

- **必須。** ワークフローの名前です。 これは、使用可能なワークフローの一覧に表示されます。

* `description`

- **必須。** ワークフローの説明。 これは、使用可能なワークフローの一覧に表示されます。

* `iconName`

- **省略可。** ワークフローの一覧に表示されるワークフローのアイコンを指定します。
  `iconName` には、次のいずれかの型を指定できます。
  * `workflow-templates` ディレクトリに格納されている SVG ファイル。 ファイルを参照するには、その値がファイル拡張子のないファイル名である必要があります。 たとえば、`example-icon.svg` という名前の SVG ファイルは `example-icon` として参照されます。
  * GitHub の [Octicons](https://primer.style/octicons/) セットからのアイコン。 octicon を参照するには、値を `octicon <icon name>` にする必要があります。 たとえば、「 `octicon smiley` 」のように入力します。

* `categories`

- **省略可。** ワークフローが表示されるカテゴリを定義します。 次の一覧からのカテゴリ名を使用できます。
  * [starter-workflows](https://github.com/actions/starter-workflows/blob/main/README.md#categories) リポジトリの一般的なカテゴリ名。
  * [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml) リポジトリの一覧からの Linguist 言語。
  * [starter-workflows](https://github.com/github-starter-workflows/repo-analysis-partner/blob/main/tech_stacks.yml) リポジトリの一覧からのサポートされている技術スタック。

* `filePatterns`

- **省略可。** ユーザーのリポジトリのルート ディレクトリに、定義された正規表現に一致するファイルがある場合、そのワークフローを使用できるようにします。