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

ワークフローを作成するときに、既存のワークフローを再利用するか、YAML アンカーとエイリアスを使用して重複を回避する方法について説明します。

この記事の内容

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

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

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

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

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

呼び出し元リポジトリアクセス可能なワークフロー リポジトリ
privateprivate および public
publicpublic

呼び出し元リポジトリの [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 を使用して、呼び出し元ワークフローのジョブ ステップに値を渡すことはできません。

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

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

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

GitHub ホステッド ランナー

GitHub ホステッド ランナーの割り当ては、常に呼び出し元のコンテキストのみを使用して評価されます。 GitHub ホステッド ランナーの支払いは、常に呼び出し元に関連付けられます。 呼び出し元ワークフローは、呼び出し先リポジトリの GitHub ホステッド ランナーを使用できません。 詳しくは、「GitHub ホステッド ランナー」をご覧ください。

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

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

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

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

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

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 プレースホルダーを使用できます。 ワークフローが作成されるとき、プレースホルダーはリポジトリの既定のブランチの名前に自動的に置き換えられます。

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

この 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

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

メタデータ ファイルは、ワークフロー ファイルと同じ名前にする必要がありますが、.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 - 必須。 ワークフローの名前。 これは、使用可能なワークフローの一覧に表示されます。

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

YAML のアンカーとエイリアス

YAML のアンカーとエイリアスを使うと、ワークフローの繰り返しを減らすことができます。 アンカー (& でマーク) を使うと、再利用するコンテンツを特定できます。また、エイリアス (* でマーク) を使うと、別の場所でそのコンテンツを繰り返すことができます。

アンカーとエイリアスの詳細については、YAML 仕様に記載されているノードのアンカーとエイリアスに関する記事を参照してください。

YAML のアンカーとエイリアスを環境変数と共に使う例を次に示します。

jobs:
  job1:
    env: &env_vars # Define the anchor on first use
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Using production settings"

  job2:
    env: *env_vars # Reuse the environment variables
    steps:
      - run: echo "Same environment variables here"

これは、アンカーとエイリアスを使わずに次の YAML を記述することと同じです。

jobs:
  job1:
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Using production settings"

  job2:
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
    steps:
      - run: echo "Same environment variables here"

ジョブ構成全体を再利用するなど、より複雑な構成にもアンカーを使用できます。

jobs:
  test: &base_job # Define the anchor on first use
    runs-on: ubuntu-latest
    timeout-minutes: 30
    env:
      NODE_VERSION: '18'
    steps:
      - uses: actions/checkout@v5
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - run: npm test

  alt-test: *base_job # Reuse the entire job configuration