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

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

再利用可能なワークフローの参照情報。

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

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

どちらのワークフローも同じリポジトリ内にある。
呼び出されたワークフローは、GitHub Enterprise Server でパブリックリポジトリに格納されます。

GitHub.com で定義されている再利用可能なワークフローを直接使用することはできません。代わりに、お使いの GitHub Enterprise Server インスタンスで再利用可能なワークフローのコピーを格納し、そのパスからワークフローを呼び出します。
呼び出し先ワークフローが内部リポジトリに格納され、そのリポジトリの設定によりアクセス可能になっている。詳細については、「アクションとワークフローを企業と共有する」を参照してください。
呼び出し先ワークフローがプライベートリポジトリに格納され、そのリポジトリの設定でアクセス可能になっている。詳細については、「アクションとワークフローを企業と共有する」を参照してください。

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

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

呼び出し元リポジトリの [Actions settings] ページの [Actions permissions] は、アクションと再利用可能なワークフローの使用を許可するように構成する必要があります。「リポジトリの GitHub Actions の設定を管理する」を参照してください。

内部またはプライベートリポジトリの場合、呼び出されたワークフローのリポジトリの [Actions settings] ページの [Access] ポリシーは、呼び出し元ワークフローを含むリポジトリからのアクセスを許可するように明示的に構成する必要があります。「リポジトリの GitHub Actions の設定を管理する」を参照してください。

メモ

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

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

最大 4 つのレベルのワークフローに接続できます。詳細については、「再利用可能なワークフローを入れ子にする」を参照してください。
1 つのワークフローファイルから最大 20 個の一意の再利用可能なワークフローを呼び出すことができます。この制限には、最上位の呼び出し元ワークフローファイルから始まる、呼び出される可能性がある入れ子になった再利用可能なワークフローのツリーが含まれます。

たとえば、top-level-caller-workflow.yml → called-workflow-1.yml → called-workflow-2.yml は、2 つの再利用可能なワークフローとしてカウントされます。
呼び出し元ワークフローのワークフローレベルで定義され、env コンテキストで設定されている環境変数は、呼び出し先ワークフローには反映されません。詳細については、「変数に情報を格納する」および「コンテキストリファレンス」を参照してください。
同様に、呼び出されたワークフローで定義されている env コンテキストで設定された環境変数は、呼び出し元ワークフローの env コンテキストではアクセスできません。代わりに、再利用可能なワークフローの出力を使用する必要があります。詳細については、「再利用可能なワークフローからの出力の使用」を参照してください。
複数のワークフローで変数を再利用するには、これを Organization レベル、リポジトリレベル、または環境レベルで設定し、vars コンテキストを使って参照します。詳細については、「変数に情報を格納する」と「コンテキストリファレンス」を参照してください。
再利用可能なワークフローは、ジョブステップ内からではなく、ジョブ内で直接呼び出されます。したがって、GITHUB_ENV を使用して、呼び出し元ワークフローのジョブステップに値を渡すことはできません。

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

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

jobs.<job_id>.name
jobs.<job_id>.uses
jobs.<job_id>.with
jobs.<job_id>.with.<input_id>
jobs.<job_id>.secrets
jobs.<job_id>.secrets.<secret_id>
jobs.<job_id>.secrets.inherit
jobs.<job_id>.strategy
jobs.<job_id>.needs
jobs.<job_id>.if
jobs.<job_id>.concurrency
jobs.<job_id>.permissions
メモ
- 呼び出し元のジョブで jobs.<job_id>.permissions が指定されていない場合は、呼び出し先ワークフローには GITHUB_TOKEN に対する既定のアクセス許可が与えられます。詳しくは、「GitHub Actions　のワークフロー構文」をご覧ください。
- 呼び出し元ワークフローから渡された 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 ホステッドランナー」をご覧ください。

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

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

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

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

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

GITHUB_TOKEN アクセス許可は、入れ子になったワークフローでのみ同じまたはより制限的にすることができます。たとえば、ワークフローチェーン A > B > C では、ワークフロー A に package: read トークンアクセス許可がある場合、B と C は package: write アクセス許可を持つことができません。詳しくは、「ワークフローでの認証に GITHUB_TOKEN を使用する」をご覧ください。

API を使って、特定のワークフロー実行に関係していたワークフローファイルを特定する方法については、「ワークフローを再利用する」をご覧ください。

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

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

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

ワークフロー内のすべてのジョブを再実行すると、指定した参照の再利用可能なワークフローが使われます。ワークフロー内のすべてのジョブの再実行の詳細については、「ワークフローとジョブの再実行」を参照してください。
失敗したジョブまたはワークフロー内の特定のジョブを再実行すると、最初の試行と同じコミット SHA の再利用可能なワークフローが使われます。ワークフローで失敗したジョブを再実行する方法の詳細については、「ワークフローとジョブの再実行」を参照してください。ワークフロー内の特定のジョブの再実行の詳細については、「ワークフローとジョブの再実行」を参照してください。

`github` コンテキスト

再利用可能なワークフローが呼び出し元ワークフローによってトリガーされると、 github コンテキストが必ず呼び出し元ワークフローに関連付けられます。呼び出し先ワークフローには、github.token と secrets.GITHUB_TOKEN へのアクセス権が自動的に付与されます。 github コンテキストの詳細については、「コンテキストリファレンス」を参照してください。

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

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

ワークフローテンプレートの使用可否

テンプレートリポジトリと一致するリポジトリ、またはテンプレートリポジトリよりも可視性が制限されているリポジトリでテンプレートを使用できます。

パブリック .github リポジトリ内のワークフローテンプレートは、すべてのリポジトリの種類で使用できます。
内部 .github リポジトリ内のワークフローテンプレートは、内部リポジトリとプライベートリポジトリでのみ使用できます。
プライベート .github リポジトリ内のワークフローテンプレートは、プライベートリポジトリでのみ使用できます。

プライベートまたは内部リポジトリへのアクセス権を付与する

プライベートまたは内部 .github リポジトリを使っている場合は、テンプレートを使用できるユーザーまたはチームに読み取りアクセス権を付与する必要があります。

`$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

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

name: Octo Organization CI
on:
  push:
    branches: [ $default-branch ]
  pull_request:
    branches: [ $default-branch ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - 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

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

{
    "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 セットからのアイコン。 octicon を参照するには、値を octicon <icon name> にする必要があります。たとえば、「 octicon smiley 」のように入力します。
categories - 省略可能。 ワークフローが表示されるカテゴリを定義します。次の一覧からのカテゴリ名を使用できます。
- starter-workflows リポジトリの一般的なカテゴリ名。
- linguist リポジトリの一覧からの Linguist 言語。
- starter-workflows リポジトリの一覧からのサポートされている技術スタック。
filePatterns - 省略可能。 ユーザーのリポジトリのルートディレクトリに、定義された正規表現に一致するファイルがある場合、そのワークフローを使用できるようにします。

この記事の内容