再利用可能ワークフロー リファレンス

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

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

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

• 呼び出されたワークフローは、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 の設定を管理する」を参照してください。

制限事項

• 最大 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-hosted runners」をご覧ください。

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

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

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

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

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

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

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

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

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

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

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

github コンテキスト

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