GitHub Actions　のワークフロー構文

ワークフロー用のYAML構文について

ワークフロー ファイルでは YAML 構文が使用され、ファイル拡張子 .yml または .yaml が必要です。 YAML の初心者で詳しく学びたい場合は、「Learn YAML in Y minutes」(YAML を Y 分で学ぶ) を参照してください。

ワークフロー ファイルは、リポジトリの .github/workflows ディレクトリに保存する必要があります。

name

ワークフローの名前です。 GitHub では、ワークフローの名前がリポジトリの [アクション] タブに表示されます。name を省略すると、GitHub は、リポジトリのルートに対して相対的なワークフロー ファイル パスを表示します。

run-name

ワークフローから生成されたワークフロー実行の名前。 GitHub は、リポジトリの [アクション] タブにあるワークフロー実行の一覧にワークフロー実行名を表示します。 run-name を省略した場合、または空白のみである場合、実行名はワークフロー実行のイベント固有の情報に設定されます。 たとえば、push または pull_request イベントによってトリガーされるワークフローの場合、コミット メッセージまたは pull request のタイトルとして設定されます。

この値には式を含めることができ、github および inputs コンテキストを参照することもできます。

run-name の例

run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}

on

ワークフローを自動的にトリガーするには、on を使用してワークフローを実行する原因となるイベントを定義します。 使用できるイベントの一覧については、「ワークフローをトリガーするイベント」を参照してください。

ワークフローをトリガーできる 1 つまたは複数のイベントを定義することも、時間スケジュールを設定することもできます。 また、特定のファイル、タグ、またはブランチの変更に対してのみワークフローが実行されるよう制限することもできます。 以降のセクションでは、これらのオプションについて説明します。

単一のイベントを使用する

たとえば、次の on の値を持つワークフローは、ワークフローのリポジトリ内の任意のブランチにプッシュが行われるときに実行されます。

on: push

複数のイベントを使用する

1 つのイベントまたは複数のイベントを指定できます。 たとえば、次の on の値を持つワークフローは、ワークフローのリポジトリ内の任意のブランチにプッシュが行われるとき、または誰かがリポジトリをフォークしたときに実行されます。

on: [push, fork]

複数のイベントを指定する場合、ワークフローをトリガーするために必要なイベントは 1 つだけです。 ワークフローの複数のトリガー イベントが同時に発生した場合、複数のワークフロー実行がトリガーされます。

アクティビティの種類を使用する

一部のイベントには、ワークフローを実行するタイミングをより細かく制御できるアクティビティの種類があります。 on.<event_name>.types を使用して、ワークフロー実行をトリガーするイベント アクティビティの種類を定義します。

たとえば、issue_comment イベントには、created、edited、deleted のアクティビティの種類があります。 label イベントでワークフローがトリガーされる場合、ラベルが作成、編集、または削除されるたびにワークフローが実行されます。 created イベントに label アクティビティの種類を指定すると、ワークフローはラベルの作成時に実行されますが、ラベルの編集または削除時には実行されません。

on:
  label:
    types:
      - created

複数のアクティビティの種類を指定した場合、ワークフローをトリガーするために発生する必要があるのは、それらのイベント アクティビティの種類のうちの 1 つだけです。 ワークフローの複数のトリガー イベント アクティビティの種類が同時に発生した場合、複数のワークフロー実行がトリガーされます。 たとえば、次のワークフローは、issue が開かれたとき、またはラベルが付けられたときに実行されます。 2 つのラベルを持つ Issue がオープンされると、3 つのワークフロー実行 (1 つは Issue がオープンされたイベント用、2 つは Issue のラベルが付いたイベント用) が開始されます。

on:
  issues:
    types:
      - opened
      - labeled

各イベントとそのアクティビティの種類の詳細については、「ワークフローをトリガーするイベント」を参照してください。

フィルターを使用する

一部のイベントには、ワークフローを実行するタイミングをより細かく制御できるフィルターがあります。

たとえば、push イベントの branches フィルターでは、プッシュが発生したときではなく、branches フィルターと同じブランチに対してプッシュが発生したときのみ、ワークフローを実行できます。

on:
  push:
    branches:
      - main
      - 'releases/**'

アクティビティの種類とフィルターを複数のイベントと共に使用する

イベントにアクティビティの種類やフィルターを指定し、ワークフローが複数のイベントでトリガーされる場合、各イベントを個別に構成する必要があります。 構成しないイベントも含め、すべてのイベントにはコロン (:) を追加する必要があります。

たとえば、以下の on の値を持つワークフローは、次のような場合に実行されます。

• ラベルが作成されたとき
• リポジトリ内の main ブランチにプッシュされたとき
• GitHub Pages 対応のブランチにプッシュされたとき

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

on.<event_name>.types を使用して、ワークフロー実行をトリガーするアクティビティの種類を定義します。 ほとんどの GitHub イベントは、2 つ以上のアクティビティタイプからトリガーされます。 たとえば、label は、ラベルが created、edited、または deletedにトリガーされます。 types キーワードを使用すると、ワークフローを実行させるアクティビティの範囲を狭くすることができます。 Webhook イベントをトリガーするアクティビティの種類が 1 つのみの場合、types キーワードは不要です。

イベント types の配列を使用できます。 各イベントとそのアクティビティの種類の詳細については、「ワークフローをトリガーするイベント」を参照してください。

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

pull_request イベントと pull_request_target イベントを使用する場合は、特定のブランチを対象とする pull request に対してのみ実行するようにワークフローを構成できます。

ブランチ名パターンを包含する場合、またはブランチ名パターンの包含と除外の両方を行う場合は、branches フィルターを使用します。 ブランチ名パターンの除外のみを行う場合は、branches-ignore フィルターを使用します。 branches と branches-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

branches / branches-ignore と paths/paths-ignore の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

branches と branches-ignore のキーワードは、複数のブランチ名に一致する文字 (*、**、+、?、! など) を使用する glob パターンを受け入れます。 名前にこれらの文字のいずれかが含まれていて、文字どおりに一致させたい場合は、これらの特殊文字をそれぞれ \ でエスケープする必要があります。 glob パターンの詳細については、GitHub Actions　のワークフロー構文 を参照してください。

例: ブランチの包含

branches で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、pull request の対象となる pull_request イベントが発生するたびに実行されます。

• main という名前のブランチ (refs/heads/main)
• mona/octocat という名前のブランチ (refs/heads/mona/octocat)
• releases/ のように名前が releases/10 で始まるブランチ (refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'

ブランチ フィルター、パス フィルター、または コミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

例: ブランチの除外

パターンが branches-ignore パターンと一致する場合、ワークフローは実行されません。 branches-ignore で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、pull request の対象とならない限り、pull_request イベントが発生するたびに実行されます。

• mona/octocat という名前のブランチ (refs/heads/mona/octocat)
• 名前が releases/**-alpha のように releases/beta/3-alpha と一致する ブランチ (refs/heads/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'

例: パスの包含および除外

1 つのワークフローで同じイベントのフィルター処理をするために branches と branches-ignore を使用することはできません。 1 つのイベントに対して分岐パターンの適用と除外の両方を行う場合は、branches フィルターと ! 文字を使用して、除外する分岐を指定します。

! 文字を含むブランチを定義する場合は、! 文字を含まないブランチも 1 つ以上定義する必要があります。 ブランチの除外のみを行いたい場合は、代わりに branches-ignore を使用します。

パターンを定義する順序により、結果に違いが生じます。

• 肯定のマッチング パターンの後に否定のマッチング パターン (! のプレフィックスが付く) を定義すると、Git ref が除外されます。
• 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。

次のワークフローは、否定のパターン pull_request が肯定のパターンの後に続くため、releases/10 または releases/beta/mona を対象とする pull request の releases/10-alpha イベントで実行されますが、releases/beta/3-alpha または !releases/**-alpha を対象とする pull request では実行されません。

on:
  pull_request:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

push イベントを使用する場合は、特定のブランチまたはタグで実行するワークフローを構成できます。

ブランチ名パターンを含める場合、またはブランチ名パターンを含める/除外の両方を行う場合は、branches フィルターを使用します。 ブランチ名パターンの除外のみを行う場合は、branches-ignore フィルターを使用します。 branches と branches-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

タグ名パターンを含める場合、またはタグ名パターンを含める/除外の両方を行う場合は、tags フィルターを使用します。 タグ名パターンの除外のみを行う場合は、tags-ignore フィルターを使用します。 tags と tags-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

tags / tags-ignore のみ、または branches/branches-ignore のみを定義した場合、定義されていない Git ref に影響を与えるイベントに対してワークフローは実行されません。tags/tags-ignore も branches/branches-ignore も定義していない場合、ワークフローはブランチまたはタグに影響を与えるイベントに対して実行されます。 branches / branches-ignore と paths/paths-ignore の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

branches、branches-ignore、tags、および tags-ignore のキーワードは、複数のブランチまたはタグ名に一致する文字 (*、**、+、?、! など) を使用する glob パターンを許容します。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な場合は、__ でこれらの各特殊文字を\する必要があります。 glob パターンの詳細については、GitHub Actions　のワークフロー構文 を参照してください。

ブランチとタグを含める例

branches と tags で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、push イベントが発生するたびに実行されます。

• main という名前のブランチ (refs/heads/main)
• mona/octocat という名前のブランチ (refs/heads/mona/octocat)
• releases/10 のように名前が releases/ で始まるブランチ (refs/heads/releases/10)
• v2 という名前のタグ (refs/tags/v2)
• v1.9.1 のように名前が v1. で始まるタグ (refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:
      - v2
      - v1.*

ブランチやタグを除外する例

パターンが branches-ignore または tags-ignore パターンと一致する場合、ワークフローは実行されません。 branches と tags で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、push イベントがない限り、push イベントが発生するたびに実行されます。

• mona/octocat という名前のブランチ (refs/heads/mona/octocat)
• releases/**-alpha のように名前が releases/beta/3-alpha と一致する ブランチ (refs/heads/releases/beta/3-alpha)
• v2 という名前のタグ (refs/tags/v2)
• v1. のように名前が v1.9 で始まるタグ (refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:
      - v2
      - v1.*

ブランチやタグを含めたり除外したりする例

1 つのワークフローで同じイベントをフィルターするために branches と branches-ignore を使用することはできません。 同様に、1 つのワークフローで同じイベントをフィルターするために tags と tags-ignore を使用することはできません。 1 つのイベントに対してブランチまたはタグ パターンを含める/除外の両方を行う場合は、branches または tags フィルターと ! 文字を使用して、除外するブランチまたはタグを指定します。

! 文字を含むブランチを定義する場合は、! 文字を含まないブランチも 1 つ以上定義する必要があります。 ブランチの除外のみを行いたい場合は、代わりに branches-ignore を使用します。 同様に、! 文字を含むタグを定義する場合は、! 文字を含まないタグも 1 つ以上定義する必要があります。 タグの除外のみを行いたい場合は、代わりに tags-ignore を使用します。

パターンを定義する順序により、結果に違いが生じます。

• 肯定のマッチング パターンの後に否定のマッチング パターン (! のプレフィックスが付く) を定義すると、Git ref が除外されます。
• 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。

次のワークフローは、否定パターン releases/10 が肯定パターンに従うため、releases/beta/mona または releases/10-alpha へのプッシュで実行され、releases/beta/3-alpha または !releases/**-alpha では実行されません。

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

push と pull_request のイベントを使用すると、変更されるファイル パスに基づいて実行するワークフローを構成できます。 タグのプッシュでは、パス フィルターは評価されません。

ファイル パス パターンを包含する場合、またはファイル パス パターンの包含と除外の両方を行う場合は、paths フィルターを使用します。 ファイル パス パターンの除外のみを行う場合は、paths-ignore フィルターを使用します。 paths と paths-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。 1 つのイベントに対してパス パターンの包含と除外の両方を行う場合は、除外するパスを示すためにpaths 文字を接頭辞にした!フィルタを使用します。

branches / branches-ignore と paths/paths-ignore の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

paths と paths-ignore のキーワードは、複数のパス名と一致するために * と ** のワイルドカード文字を使用する glob パターンを受け入れます。 詳細については、「GitHub Actions　のワークフロー構文」を参照してください。

例: パスの包含

paths フィルターにパターンにマッチするパスが 1 つでもあれば、ワークフローは実行されます。 たとえば、次のワークフローは、JavaScript ファイル (.js) をプッシュするたびに実行されます。

on:
  push:
    paths:
      - '**.js'

パス フィルター、ブランチ フィルター、またはコミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

例: パスの除外

すべてのパス名が paths-ignore のパターンと一致する場合、ワークフローは実行されません。 パス名が paths-ignore のパターンと一致しない場合は、一部のパス名がパターンと一致する場合でも、ワークフローが実行されます。

以下のパスのフィルターを持つワークフローは、リポジトリのルートにある docs ディレクトリ外のファイルを少なくとも 1 つ含む push イベントでのみ実行されます。

on:
  push:
    paths-ignore:
      - 'docs/**'

例: パスの包含および除外

1 つのワークフローで同じイベントのフィルター処理をするために paths と paths-ignore を使用することはできません。 1 つのイベントに対してパス パターンの包含と除外の両方を行う場合は、除外するパスを示すために! 文字を接頭辞にしたpathsフィルタを使用します。

! 文字を含むパスを定義する場合は、! 文字を含まないパスも 1 つ以上定義する必要があります。 パスの除外のみを行いたい場合は、代わりに paths-ignore を使用します。

pathsパターンを定義する順序により、結果に違いが生じます:

• 肯定のマッチング パターンの後に否定のマッチング パターン（! のプレフィックスが付く） を定義すると、パスを除外します。
• 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、パスを再び含めます。

ファイルが sub-project/docs ディレクトリに存在しない限り、push イベントが sub-project ディレクトリまたはそのサブディレクトリのファイルを含む場合は、この例はいつでも実行されます。 たとえば、sub-project/index.js または sub-project/src/index.js を変更するプッシュはワークフローの実行をトリガーしますが、sub-project/docs/readme.md のみを変更するプッシュはワークフローの実行をトリガーしません。

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Git diffの比較

フィルターは、変更されたファイルを評価し、paths-ignore または paths のリストに対してファイルを実行することで、ワークフローを実行すべきか判断します。 ファイルが変更されていない場合、ワークフローは実行されません。

GitHub では、プッシュの場合は 2 ドットの差分を使用し、pull requestは 3 ドットの差分を使用して、変更されたファイルの一覧が生成されます。

• プル リクエスト: 3 点差分は、トピック ブランチの最新バージョンと、トピック ブランチが最後にベース ブランチと同期された時点のコミットを比較したものです。
• 既存のブランチへのプッシュ: ツードット diff は、ヘッド SHA とベース SHA を互いに直接比較します。
• 新しいブランチへのプッシュ: プッシュされた最も古い祖先コミットの親を基準にした 2 ドット差分です。

状況によっては、フィルター処理されたワークフローの実行方法を変更する制限 GitHub Actions 適用されます。

• プッシュに 1,000 を超えるコミットが含まれている場合、ワークフローは 常に 実行されます。
• 差分の生成がタイムアウトすると、ワークフローは 常に 実行されます。
• 生成された差分に 3,000 を超えるファイルが含まれておりワークフロー フィルターが一致するファイルがフィルターによって返される最初の 3,000 にない場合、ワークフローは実行 されません 。

これらの動作を観察する場合は、フィルターをより具体的にするか、プッシュ要求とプル要求の操作方法を変更して、より簡単な相違を生成することが必要になる場合があります。

詳しくは、「支店」をご覧ください。

on.schedule

on.schedule を使用すると、ワークフローの時間スケジュールを定義できます。

POSIX cron 構文を使用して、特定の時刻に実行するようにワークフローをスケジュールします。 既定では、スケジュールされたワークフローは UTC で実行されます。 必要に応じて、タイムゾーン対応のスケジュール設定のために IANA タイムゾーン文字列 を使用してタイムゾーンを指定できます。 スケジュールされたワークフローは、既定のブランチの最新のコミットに対して実行されます。 スケジュールされたワークフローを実行できる最短の間隔は、5 分ごとに 1 回です。

クーロン構文では、スペースで分けられた 5 つのフィールドがあり、各フィールドは時間の単位を表わします。

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
* * * * *

5 つのフィールドいずれにおいても、以下の演算子を使用できます:

この例では、毎週月曜日から金曜日のアメリカ/New_Yorkタイムゾーンで午前 5 時 30 分にワークフローを実行するようにトリガーします。

on:
  schedule:
    - cron: '30 5 * * 1-5'
      timezone: "America/New_York"

1 つのワークフローを、複数の schedule イベントでトリガーできます。 schedule コンテキストを通じて、ワークフローをトリガーした github.event.schedule イベントにアクセスします。 この例では、月曜日から木曜日までの 5:30 UTC および火曜日と木曜日の 17:30 UTC にワークフローの実行がトリガーされますが、月曜日と水曜日には Not on Monday or Wednesday ステップはスキップされます。

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5,17 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

schedule イベントについて詳しくは、「ワークフローをトリガーするイベント」を参照してください。

on.workflow_call

on.workflow_call は、再利用可能なワークフローの入力と出力を定義するために使います。 呼び出し対象のワークフローで使用できるシークレットをマップすることもできます。 再利用可能なワークフローについて詳しくは、「ワークフローを再利用する」をご覧ください。

on.workflow_call.inputs

workflow_call キーワードを使う場合は、必要に応じて、呼び出し元ワークフローから呼び出し対象のワークフローに渡される入力を指定できます。 workflow_call キーワードについて詳しくは、「ワークフローをトリガーするイベント」をご覧ください。

on.workflow_call.inputs には、使用可能な標準入力パラメーターに加えて type パラメーターが必要です。 詳細については、「on.workflow_call.inputs.<input_id>.type」を参照してください。

default パラメーターが設定されていない場合、入力の既定値は false (ブール値の場合)、0 (数値の場合)、"" (文字列の場合) です。

呼び出し対象のワークフロー内で inputs コンテキストを使って入力を参照できます。 詳しくは、「コンテキスト リファレンス」をご覧ください。

呼び出し対象のワークフローで指定されていない入力が呼び出し元ワークフローによって渡されると、エラーが発生します。

on.workflow_call.inputs の例

on:
  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

jobs:
  print-username:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input name to STDOUT
        run: echo The username is ${{ inputs.username }}

詳しくは、「ワークフローを再利用する」をご覧ください。

on.workflow_call.inputs.<input_id>.type

on.workflow_call キーワードに対して入力が定義されている場合は必須です。 このパラメーターの値は、入力のデータ型を指定する文字列です。 これは、boolean、number、または string のいずれかである必要があります。

on.workflow_call.outputs

呼び出し対象のワークフローの出力のマップ。 呼び出し対象のワークフロー出力は、呼び出し元ワークフロー内のすべてのダウンストリーム ジョブで使用できます。 各出力には、識別子、省略可能な description,、value. があります。呼び出し対象のワークフロー内のジョブからの出力の値には value を設定する必要があります。

次の例では、この再利用可能なワークフローに対して 2 つの出力 workflow_output1 と workflow_output2 が定義されています。 これらは、どちらも job_output1 というジョブから job_output2 と my_job という出力にマップされます。

on.workflow_call.outputs の例

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}

ジョブ出力を参照する方法については、jobs.<job_id>.outputs を参照してください。 詳しくは、「ワークフローを再利用する」をご覧ください。

on.workflow_call.secrets

呼び出し対象のワークフローで使用できるシークレットのマップ。

呼び出し対象のワークフロー内で secrets コンテキストを使ってシークレットを参照できます。

呼び出し対象のワークフローで指定されていないシークレットが呼び出し元ワークフローによって渡されると、エラーが発生します。

on.workflow_call.secrets の例

on:
  workflow_call:
    secrets:
      access-token:
        description: 'A token passed from the caller workflow'
        required: false

jobs:

  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
    # passing the secret to an action
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

  # passing the secret to a nested reusable workflow
  pass-secret-to-workflow:
    uses: ./.github/workflows/my-workflow
    secrets:
       token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

シークレットに関連付ける文字列識別子。

on.workflow_call.secrets.<secret_id>.required

シークレットを指定する必要があるかどうかを指定するブール値。

on.workflow_run.<branches|branches-ignore>

workflow_run イベントを使用する場合は、ワークフローをトリガーするためにトリガーするワークフローが稼働する必要があるブランチを指定できます。

branches フィルターと branches-ignore フィルターは、複数のブランチ名に一致する文字 (*、**、+、? など) を使用する glob パターンを受け入れます。! 名前にこれらの文字のいずれかが含まれていて、文字どおりに一致させたい場合は、これらの各特殊文字を__ で\する必要があります。 glob パターンの詳細については、GitHub Actions　のワークフロー構文 を参照してください。

たとえば、次のトリガーを持つワークフローは、名前が Build で始まるブランチで releases/ という名前のワークフローが稼働している場合にのみ実行されます。

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

次のトリガーを持つワークフローは、名前が Build でないブランチで canary という名前のワークフローが稼働している場合にのみ実行されます。

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

branches と branches-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。 1 つのイベントに対して分岐パターンの適用と除外の両方を行う場合は、branches フィルターと ! 文字を使用して、除外する分岐を指定します。

パターンを定義する順序により、結果に違いが生じます。

• 肯定のマッチング パターンの後に否定のマッチング パターン（! のプレフィックスが付く） を定義すると、ブランチを除外します。
• 否定のマッチング パターンの後に肯定のマッチング パターンを定義すると、ブランチを再び含めます。

たとえば、次のトリガーを持つワークフローは、名前が Build または releases/10 で始まるブランチで releases/beta/mona という名前のワークフローが稼働している場合にのみ実行されますが、releases/10-alpha、releases/beta/3-alpha または main という名前のブランチでは実行されません。

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch

workflow_dispatch イベントを使用すると、必要に応じてワークフローに渡される入力を指定できます。

このトリガーは、ワークフロー ファイルが既定のブランチにある場合に限りイベントを受信します。

on.workflow_dispatch.inputs

トリガーされたワークフローは、inputs コンテキスト内の入力を受け取ります。 詳細については、「コンテキスト」を参照してください。

inputsの最上位のプロパティの最大数は、25 です。

* inputs のペイロードの最大数は 65,535 文字です。

on.workflow_dispatch.inputs の例

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
          - info
          - warning
          - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if: ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

on.workflow_dispatch.inputs.<input_id>.required

入力を指定する必要があるかどうかを指定するブール値。

on.workflow_dispatch.inputs.<input_id>.type

このパラメーターの値は、入力のデータ型を指定する文字列です。 これは、boolean、choice、number、environmentまたはstring. のいずれかである必要があります。

permissions

permissions を使用して GITHUB_TOKEN に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追加または削除することで、必要最小限のアクセスのみを許可することができます。 詳しくは、「ワークフローでの認証に GITHUB_TOKEN を使用する」をご覧ください。

permissions は、最上位のキーとして、ワークフロー内のすべてのジョブに適用するか、または特定のジョブ内で使用できます。 特定のジョブ内に permissions キーを追加すると、GITHUB_TOKEN を使用するそのジョブ内のすべてのアクションと実行コマンドが、指定したアクセス権を取得します。 詳細については、「jobs.<job_id>.permissions」を参照してください。

組織 の所有者は、リポジトリ レベルで GITHUB_TOKEN の書き込みアクセスを制限できます。 詳細については、「 組織のGitHub Actionsの無効化または制限」を参照してください。

pull_request_target イベントによってワークフローがトリガーされると、パブリック フォークからトリガーされた場合でも、GITHUB_TOKEN にはリポジトリの読み取り/書き込みアクセス許可が付与されます。 詳しくは、「ワークフローをトリガーするイベント」をご覧ください。

以下の表に示すように、使用可能なアクセス許可ごとに、read (該当する場合)、write、または none のいずれかのアクセス レベルを割り当てることができます。 write には read が含まれます。 これらのアクセス許可のいずれかにアクセスを指定すると、指定されていないすべてのアクセス許可が none に設定されます。

使用可能なアクセス許可と、それぞれがアクションに実行を許可する内容の詳細:

| 権限 | GITHUB_TOKEN を使用してアクションを実行することを許可します。 | | --- | --- | | actions | GitHub Actions を操作します。 たとえば、actions: write は、アクションによるワークフロー実行の取り消しを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | artifact-metadata | 成果物メタデータを操作します。 たとえば、 artifact-metadata: write は、ビルド成果物に代わってストレージ レコードを作成するアクションを許可します。 詳しくは、「アーティファクト メタデータの REST API エンドポイント」をご覧ください。 | | | | | | attestations | アーティファクト証明書に関連した作業 たとえば、attestations: write を使用すると、ビルドに対するアーティファクト認証を生成するアクションを実行できます。 詳細については、「アーティファクトの構成証明を使用してビルドの出所を確立する」を参照してください | | | | checks | チェックランとチェックスイートを操作します。 たとえば、checks: write は、アクションによるチェック実行の作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | code-quality | コードの品質を管理します。 たとえば、 code-quality: write は、コード カバレッジ レポートをアップロードするアクションを許可します。 詳しくは、「GitHub のコード品質」をご覧ください。 | | | | contents | リポジトリの内容を操作します。 たとえば、contents: read はアクションによるコミットの一覧表示を許可し、contents: write はアクションによるリリースの作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | deployments | デプロイメントを扱います。 たとえば、deployments: write は、新しいデプロイの作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | discussions | GitHub ディスカッションで作業します。 たとえば、discussions: write は、アクションがディスカッションを閉じるか削除することを許可します。 詳しくは、「ディスカッションでのGraphQL APIの利用」をご覧ください。 | | | | id-token | OpenID Connect (OIDC) トークンを取得します。 これには id-token: write が必要です。 詳細については、「OpenID Connect」を参照してください | | | | issues | 問題に対応する。 たとえば、issues: write は、アクションがイシューにコメントを追加することを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | packages | GitHub Packages を操作します。 たとえば、packages: write は、アクションによる GitHub Packages でのパッケージのアップロードと発行を許可します。 詳しくは、「GitHub Packagesの権限について」をご覧ください。 | | pages | GitHub Pages を操作します。 たとえば、pages: write は、アクションによる GitHub Pages のビルドの要求を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | pull-requests | プルリクエストを扱います。 たとえば、pull-requests: write は、アクションによる pull request へのラベルの追加を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | security-events | GitHub のコード スキャン アラートを操作します。 たとえば、security-events: read を指定すると、アクションでリポジトリ内のコード スキャン アラートを一覧表示できるようになります。また、security-events: write を指定すると、アクションでコード スキャン アラートの状態を更新できるようになります。 詳細については、「 コード スキャン アラート」のリポジトリのアクセス許可を参照してください。

Dependabot アラートの場合は、 vulnerability-alerts アクセス許可を使用します。 シークレット スキャン アラートは、このアクセス許可で読み取ることができず、GitHub アプリまたは personal access tokenが必要です。 詳細については、「GitHub Apps に必要な アクセス許可」の「シークレット スキャン アラート」のリポジトリのアクセス許可 を参照してください | | statuses | コミットの状態を操作します。 たとえば、statuses:read は、アクションが特定の参照のコミット状態を一覧表示することを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | vulnerability-alerts | Dependabot アラートを読み取ります。 たとえば、 vulnerability-alerts: read は、リポジトリの Dependabot アラートを一覧表示するアクションを許可します。 readとnoneのみがサポートされています。writeは無効です。 write-allまたはread-allを使用すると、vulnerability-alertsは自動的にreadとして含まれます。 詳細については、「 Dependabot アラート」のリポジトリのアクセス許可を参照してください。 | | |

GITHUB_TOKEN スコープのアクセスの定義

GITHUB_TOKEN キー内で使用可能なアクセス許可の値として read、write、または none を指定することで、permissions が許可するアクセスを定義できます。

permissions:
  actions: read|write|none
  artifact-metadata: read|write|none
  attestations: read|write|none
  checks: read|write|none
  code-quality: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none

  security-events: read|write|none
  statuses: read|write|none
  vulnerability-alerts: read|none

これらのアクセス許可のいずれかにアクセスを指定すると、指定されていないすべてのアクセス許可が none に設定されます。

利用可能なすべてのアクセス許可に対して read-all または write-all どちらかのアクセスを定義するには、以下の構文が使えます。

permissions: read-all

permissions: write-all

次の構文を使用して、使用可能なすべてのアクセス許可を無効にすることができます。

permissions: {}

フォークされたリポジトリのアクセス許可を変更する

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外は、管理者ユーザーが**** 設定の GitHub Actionsするオプションを選択している場合です。 詳しくは、「リポジトリのGitHub Actions設定の管理」をご覧ください。

ワークフロー ジョブのアクセス許可の計算方法

GITHUB_TOKEN のアクセス許可は最初に、エンタープライズ、組織、またはリポジトリの既定値に設定されます。 デフォルトがこれらのレベルのいずれかで制限付きの権限に設定されている場合、これは関連するリポジトリに適用されます。 たとえば、Organization レベルで制限付きのデフォルトを選択した場合、その Organization 内のすべてのリポジトリは、制限付きの権限をデフォルトとして使用します。 次に、ワークフローファイル内の構成に基づいて、最初にワークフローレベルで、次にジョブレベルで権限が調整されます。 最後に、フォークされたリポジトリからの pull_request_target 以外のプル要求イベントによってワークフローがトリガーされ、[ pull requests からワークフローに書き込みトークンを送信 する] 設定が選択されていない場合、読み取り専用の書き込みアクセス許可を変更するようにアクセス許可が調整されます。

ワークフロー内のすべてのジョブの GITHUB_TOKEN アクセス許可の設定

設定がワークフロー内のすべてのジョブに適用されるように、ワークフローの最上位レベルで permissions を指定できます。

例: ワークフロー全体の GITHUB_TOKEN アクセス許可の設定

この例では、ワークフロー内のすべてのジョブに適用される GITHUB_TOKEN に設定されているアクセス許可を示しています。 すべての権限に読み取りアクセスが付与されます。

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

フォークされたリポジトリに対する permissions キーの使用

permissions キーを使って、フォークされたリポジトリの read アクセス許可を追加および削除できますが、通常、write アクセス権を付与することはできません。 この動作の例外は、管理者ユーザーが**** 設定の GitHub Actionsするオプションを選択している場合です。 詳しくは、「リポジトリのGitHub Actions設定の管理」をご覧ください。

Dependabot によってトリガーされるワークフロー実行のアクセス権

プル要求 Dependabot トリガーされるワークフロー実行は、フォークされたリポジトリからの場合と同様に実行されるため、読み取り専用の GITHUB_TOKENを使用します。 それらのワークフローの実行は、シークレットにはアクセスできません。 これらのワークフローをセキュリティで保護するための戦略については、「セキュリティで保護された使用に関するリファレンス」を参照してください。

env

ワークフロー中のすべてのジョブのステップで使うことができる変数の map です。 1 つのジョブのステップか 1 つのステップでしか使うことができない変数を設定することもできます。 詳細については、jobs.<job_id>.env および jobs.<job_id>.steps[*].env を参照してください。

env マップ内の変数は、マップ内の他の変数の観点からは定義できません。

同じ名前で複数の環境変数が定義されている場合、GitHub では最も具体的な変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の環境変数をステップの実行の間オーバーライドします。 ジョブで定義された環境変数は、そのジョブの実行の間はワークフローの同じ名前の変数をオーバーライドします。

env の例

env:
  SERVER: production

defaults

defaults を使用して、デフォルト設定の map を作成します。これは、ワークフロー内のすべてのジョブに適用されます。 1つのジョブだけで利用できるデフォルト設定を設定することもできます。 詳細については、「jobs.<job_id>.defaults」を参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

defaults.run

defaults.run を使用すると、ワークフロー内のすべての shell ステップに、デフォルトの working-directory オプションと run オプションを指定できます。 1 つのジョブにのみ利用できる run に対して、デフォルト設定を設定することもできます。 詳細については、「jobs.<job_id>.defaults.run」を参照してください。 このキーワード中では、コンテキストや式を使うことはできません。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

例: デフォルトのシェルと作業ディレクトリを設定する

defaults:
  run:
    shell: bash
    working-directory: ./scripts

defaults.run.shell

shell を使用してステップの shell を定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

defaults.run.working-directory

working-directory を使用してステップの shell の作業ディレクトリを定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

concurrency

同じコンカレンシー グループを使うジョブまたはワークフローを一度に 1 つだけ実行するには、concurrency を使います。 並行処理グループには、任意の文字列または式を使用できます。 この式に使用できるコンテキストは、github、inputs、vars のみです。 式の詳細については、「ワークフロー内とアクション内で式を評価する」を参照してください。

ジョブ レベルで concurrency を指定することもできます。 詳細については、「jobs.<job_id>.concurrency」を参照してください。

つまり、コンカレンシー グループ内に実行されているジョブまたはワークフローは、いつでも 1 つまで存在できます。 並行ジョブかワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中だと、キューイングされたジョブかワークフローは pending になります。 既定では、同じコンカレンシー グループ内の既存の pending ジョブまたはワークフローが取り消され、キューに登録された新しいジョブまたはワークフローが実行されます。

同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、cancel-in-progress: true を指定します。 同じコンカレンシー グループ内で現在実行中のジョブまたはワークフローを条件付きで取り消すには、許可されている式コンテキストのいずれかを含む式として cancel-in-progress を指定 できます。

複数の pending ジョブまたはワークフロー実行が同じコンカレンシー グループ内で待機できるようにするには、オプションの queue プロパティを使用します。 queue プロパティは、次の値を受け入れます。

• single (既定値): 最大 1 つのジョブまたはワークフロー実行をコンカレンシー グループに含めることができます。 新しいジョブまたはワークフローの実行がキューに登録されると、同じグループ内の既存の pending ジョブまたはワークフローの実行が取り消され、置き換えられます。
• max: コンカレンシー グループには、最大 100 個のジョブまたはワークフロー実行を pending できます。 キューがいっぱいになると、追加のジョブまたはワークフローの実行が取り消されます。

queue: maxとcancel-in-progress: trueの組み合わせは許可されず、ワークフロー検証エラーが発生します。

例：コンカレンシーとデフォルト動作の使用

GitHub Actionsの既定の動作は、複数のジョブまたはワークフローの実行を同時に実行できるようにすることです。 concurrency キーワード を使用すると、ワークフロー実行のコンカレンシーを制御できます。

たとえば、トリガー条件が定義された直後にconcurrencyキーワード を使用して、特定のブランチに対するワークフロー実行全体のコンカレンシーを制限できます：

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

ジョブ レベルでconcurrencyキーワード を使用して、ワークフロー内のジョブのコンカレンシーを制限することもできます：

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

例: 同時実行グループ

コンカレンシー グループは、同じコンカレンシー 鍵を共有するワークフロー実行またはジョブの実行を管理および制限する方法を提供します。

concurrency 鍵は、ワークフローまたはジョブをまとめてコンカレンシー グループにグループ化するために使用されます。 concurrency キーを定義すると、GitHub Actionsは、そのキーを持つワークフローまたはジョブが常に 1 つだけ実行されるようにします。 新しいワークフローの実行またはジョブが同じ concurrency キーで開始された場合、 GitHub Actions は、そのキーで既に実行されているワークフローまたはジョブを取り消します。 concurrency鍵は 、ハードコーディングされた文字列にすることも、コンテキスト変数を含む動的な式にすることもできます。

ワークフローまたはジョブがコンカレンシー グループの一部になるように、ワークフローでコンカレンシー条件を定義できます。

つまり、ワークフローの実行またはジョブが開始されると、GitHub は、同じコンカレンシー グループで既に進行状況にあるワークフローの実行またはジョブをキャンセルします。 これは、競合を引き起こしたり、必要以上に多くのリソースを消費したりする可能性のある処置を防ぐために、ステージング環境への展開に使用されるワークフローやジョブの特定のセットに対する並列実行を防ぐ場合に便利です。

この例では、 job-1は、staging_environmentと名付けられたコンカレンシー グループの一部です。 つまり、新しいjob-1 の実行がトリガーされると、既に進行状況の staging_environmentコンカレンシー グループ内の同じジョブの実行はすべてキャンセルされます。

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

または、ワークフロー内などの concurrency: ci-${{ github.ref }}のような 動的な式を使用すると、ワークフローまたはジョブは、ワークフローをトリガーしたブランチまたはタグのリファレンスに続く ci-と名付けられたコンカレンシー グループの一部になります。 この例では、前の実行の進行中に新しいコミットが メイン ブランチにプッシュされた場合、前の実行はキャンセルされ、新しいコミットが開始されます：

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

例: 複数の保留中の実行をキューする

既定では、同時実行グループに一度に pending できるジョブまたはワークフローの実行は 1 つだけです。 取り消されずに複数の実行をキューに入れるようにするには、 queue: max設定します。 queue: maxでは、最大 100 個のジョブまたはワークフロー実行がコンカレンシー グループで待機できます。キューがいっぱいになると、追加の実行はすべて取り消されます。

たとえば、次のワークフローは、 production 環境へのデプロイをキューに入れ、各実行がコンカレンシー グループの待機を開始したタイミングに基づいて順番に 1 つずつ処理します。

on:
  push:
    branches:
      - main

concurrency:
  group: production-deploy
  queue: max

queue: max cancel-in-progress: trueと組み合わせることはできません。2 つのオプションでは、進行中の実行を処理するための競合する動作が記述されているためです。

並行性を使って進行中のジョブもしくは実行をキャンセルする例

コンカレンシーを使用して進行中のジョブを取り消したり、 GitHub Actionsで実行したりするには、 concurrency キーを使用し、 cancel-in-progress オプションを trueに設定します。

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

この例では、特定のコンカレンシー グループを定義せずに、 GitHub Actions はジョブまたはワークフローの進行中の実行 を 取り消します。

例: フォールバック値の使用

特定のイベントにのみ定義されるプロパティでグループ名を作成する場合、フォールバック値を使用できます。 たとえば、github.head_ref は pull_request イベントにのみ定義されます。 ワークフローが pull_request イベントに加えて他のイベントにも応答する場合、構文エラーを回避するためにフォールバックを指定する必要があります。 次のコンカレンシー グループは、pull_request イベントで進行中のジョブか実行のみを取り消します。github.head_ref が未定義の場合、コンカレンシー グループは実行 ID にフォールバックします。これは、一意であり、実行に対して定義されていることが保証されています。

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

例: 現在のワークフローで進行中のジョブまたは実行のみを取り消します

同じリポジトリに複数のワークフローがある場合、他のワークフローの進行中のジョブまたは実行が取り消されないように、コンカレンシー グループ名はワークフロー間で一意である必要があります。 そうでない場合、ワークフローに関係なく、以前に進行中または保留中のジョブが取り消されます。

同じワークフローの進行中の実行だけを取り消すには、github.workflow プロパティを使ってコンカレンシー グループを構築します。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

例: 具体的なブランチで進行中のジョブのみをキャンセルする

特定のブランチで進行中のジョブを取り消したいが、他のブランチでは取り消さない場合は、cancel-in-progress で条件式を使用できます。 たとえば、開発ブランチでは進行中のジョブを取り消したいが、リリース ブランチでは取り消さない場合に、これを実行できます。

リリース ブランチで実行されていない場合に、同じワークフローの進行中の実行のみを取り消すには、cancel-in-progress を次のような式に設定します。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

この例では、release/1.2.3 ブランチへの複数のプッシュは進行中の実行を取り消しません。 main などの別のブランチにプッシュすると、進行中の実行が取り消されます。

cache-mode

cache-modeを使用して、ワークフロー内のジョブに付与GitHub Actionsキャッシュ アクセスのレベルを制御します。 最上位レベルでの cache-mode の設定は、ジョブが jobs.<job_id>.cache-modeでオーバーライドしない限り、ワークフロー内のすべてのジョブに適用されます。

アクセスはスコープ付きキャッシュ トークンで適用されるため、ジョブは許可されているモードを超えてキャッシュを復元または保存できません。 cache-mode は、次の値を受け取ります。

cache-modeを省略すると、トリガーの種類に基づいてreadまたは既定write使用されます。 トリガー依存の有効な既定値については、 依存関係キャッシュのリファレンス を参照してください。

キャッシュ操作が有効モードで許可されていない場合、キャッシュ ステップは情報メッセージをログに記録して続行します。 ジョブとワークフローが失敗することはありません。 スキップされた復元はキャッシュ ミスとして扱われます。スキップされた保存は、単に実行されません。 詳しくは、「依存関係キャッシュのリファレンス」をご覧ください。

cache-mode の例

cache-mode: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/cache@v4
        with:
          path: ~/.npm
          key: npm-${{ hashFiles('**/package-lock.json') }}

jobs

ワークフロー実行は、既定で並列実行される 1 つ以上の jobs で構成されます。 ジョブを順番に実行するには、jobs.<job_id>.needs キーワードを使用して他のジョブへの依存関係を定義できます。

各ジョブは、runs-on で指定されたランナー環境で実行されます。

ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳細については、ホストランナーの GitHub とセルフホステッド ランナーの使用制限に関する アクションの制限 を参照してください。

ワークフロー実行で実行されているジョブの一意識別子を検索する必要がある場合は、 GitHub API を使用できます。 詳しくは、「GitHub Actionsの REST API エンドポイント」をご覧ください。

jobs.<job_id>

ジョブへの一意の識別子の指定には、jobs.<job_id> を使います。 job_id キーは文字列で、その値はジョブの設定データのマップです。 <job_id> は、jobs オブジェクトに固有の文字列に置き換える必要があります。 <job_id> は文字または _ で始まり、英数字、-、あるいは _ のみを含める必要があります。

例: ジョブを作成する

この例では、job_id 値が my_first_job と my_second_job の 2 つのジョブが作成されました。

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

GitHub UI に表示されるジョブの名前の設定に jobs.<job_id>.name を使用します。

jobs.<job_id>.permissions

特定のジョブについて、jobs.<job_id>.permissions を使用して GITHUB_TOKEN に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追加または削除することで、必要最小限のアクセスのみを許可することができます。 詳しくは、「ワークフローでの認証に GITHUB_TOKEN を使用する」をご覧ください。

ジョブ定義内で権限を指定することで、必要に応じて、ジョブごとに GITHUB_TOKEN に異なる権限のセットを構成できます。 または、ワークフロー内のすべてのジョブの権限を指定することもできます。 ワークフロー レベルでのアクセス許可の定義については、permissions を参照してください。

以下の表に示すように、使用可能なアクセス許可ごとに、read (該当する場合)、write、または none のいずれかのアクセス レベルを割り当てることができます。 write には read が含まれます。 これらのアクセス許可のいずれかにアクセスを指定すると、指定されていないすべてのアクセス許可が none に設定されます。

使用可能なアクセス許可と、それぞれがアクションに実行を許可する内容の詳細:

| 権限 | GITHUB_TOKEN を使用してアクションを実行することを許可します。 | | --- | --- | | actions | GitHub Actions を操作します。 たとえば、actions: write は、アクションによるワークフロー実行の取り消しを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | artifact-metadata | 成果物メタデータを操作します。 たとえば、 artifact-metadata: write は、ビルド成果物に代わってストレージ レコードを作成するアクションを許可します。 詳しくは、「アーティファクト メタデータの REST API エンドポイント」をご覧ください。 | | | | | | attestations | アーティファクト証明書に関連した作業 たとえば、attestations: write を使用すると、ビルドに対するアーティファクト認証を生成するアクションを実行できます。 詳細については、「アーティファクトの構成証明を使用してビルドの出所を確立する」を参照してください | | | | checks | チェックランとチェックスイートを操作します。 たとえば、checks: write は、アクションによるチェック実行の作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | code-quality | コードの品質を管理します。 たとえば、 code-quality: write は、コード カバレッジ レポートをアップロードするアクションを許可します。 詳しくは、「GitHub のコード品質」をご覧ください。 | | | | contents | リポジトリの内容を操作します。 たとえば、contents: read はアクションによるコミットの一覧表示を許可し、contents: write はアクションによるリリースの作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | deployments | デプロイメントを扱います。 たとえば、deployments: write は、新しいデプロイの作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | discussions | GitHub ディスカッションで作業します。 たとえば、discussions: write は、アクションがディスカッションを閉じるか削除することを許可します。 詳しくは、「ディスカッションでのGraphQL APIの利用」をご覧ください。 | | | | id-token | OpenID Connect (OIDC) トークンを取得します。 これには id-token: write が必要です。 詳細については、「OpenID Connect」を参照してください | | | | issues | 問題に対応する。 たとえば、issues: write は、アクションがイシューにコメントを追加することを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | packages | GitHub Packages を操作します。 たとえば、packages: write は、アクションによる GitHub Packages でのパッケージのアップロードと発行を許可します。 詳しくは、「GitHub Packagesの権限について」をご覧ください。 | | pages | GitHub Pages を操作します。 たとえば、pages: write は、アクションによる GitHub Pages のビルドの要求を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | pull-requests | プルリクエストを扱います。 たとえば、pull-requests: write は、アクションによる pull request へのラベルの追加を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | security-events | GitHub のコード スキャン アラートを操作します。 たとえば、security-events: read を指定すると、アクションでリポジトリ内のコード スキャン アラートを一覧表示できるようになります。また、security-events: write を指定すると、アクションでコード スキャン アラートの状態を更新できるようになります。 詳細については、「 コード スキャン アラート」のリポジトリのアクセス許可を参照してください。

Dependabot アラートの場合は、 vulnerability-alerts アクセス許可を使用します。 シークレット スキャン アラートは、このアクセス許可で読み取ることができず、GitHub アプリまたは personal access tokenが必要です。 詳細については、「GitHub Apps に必要な アクセス許可」の「シークレット スキャン アラート」のリポジトリのアクセス許可 を参照してください | | statuses | コミットの状態を操作します。 たとえば、statuses:read は、アクションが特定の参照のコミット状態を一覧表示することを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | vulnerability-alerts | Dependabot アラートを読み取ります。 たとえば、 vulnerability-alerts: read は、リポジトリの Dependabot アラートを一覧表示するアクションを許可します。 readとnoneのみがサポートされています。writeは無効です。 write-allまたはread-allを使用すると、vulnerability-alertsは自動的にreadとして含まれます。 詳細については、「 Dependabot アラート」のリポジトリのアクセス許可を参照してください。 | | |

GITHUB_TOKEN スコープのアクセスの定義

GITHUB_TOKEN キー内で使用可能なアクセス許可の値として read、write、または none を指定することで、permissions が許可するアクセスを定義できます。

permissions:
  actions: read|write|none
  artifact-metadata: read|write|none
  attestations: read|write|none
  checks: read|write|none
  code-quality: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none

  security-events: read|write|none
  statuses: read|write|none
  vulnerability-alerts: read|none

これらのアクセス許可のいずれかにアクセスを指定すると、指定されていないすべてのアクセス許可が none に設定されます。

利用可能なすべてのアクセス許可に対して read-all または write-all どちらかのアクセスを定義するには、以下の構文が使えます。

permissions: read-all

permissions: write-all

次の構文を使用して、使用可能なすべてのアクセス許可を無効にすることができます。

permissions: {}

フォークされたリポジトリのアクセス許可を変更する

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外は、管理者ユーザーが**** 設定の GitHub Actionsするオプションを選択している場合です。 詳しくは、「リポジトリのGitHub Actions設定の管理」をご覧ください。

例: ワークフロー内の 1 つのジョブに対する GITHUB_TOKEN アクセス許可の設定

この例は、stale という名前のジョブにのみ適用される GITHUB_TOKEN に設定されているアクセス許可を示しています。 書き込みアクセス権限は、issues アクセス許可と pull-requests アクセス許可に対して付与されます。 その他のすべてのアクセス許可にはアクセスが付与されません。

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v10

jobs.<job_id>.needs

jobs.<job_id>.needs を使って、このジョブの実行前に正常に完了する必要があるジョブを示します。 文字列型または文字列の配列です。 ジョブが失敗した場合、またはスキップされた場合、そのジョブに依存するすべてのジョブは、それらのジョブが実行を継続する条件式を使用していない限り、スキップされます。 互いに必要とする一連のジョブが実行に含まれている場合、失敗またはスキップの時点から、依存関係チェーン内のすべてのジョブに失敗またはスキップが適用されます。 依存しているジョブが成功しなかった場合でもジョブを実行する場合は、always() のjobs.<job_id>.if 条件式を使用します。

例: 依存ジョブの成功を必須にする

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

この例では、job1 が正常に完了してから job2 が始まる必要があり、job3 では job1 と job2 の両方が完了するまで待機します。

つまり、この例のジョブは逐次実行されるということです。

1. job1
2. job2
3. job3

例: 依存ジョブが正常に完了していることを必要としない

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

この例では、job3 では条件式 always() を使っているので、job1 と job2 が成功したかどうかに関係なく、完了後に常に実行されます。 詳しくは、「ワークフロー内とアクション内で式を評価する」をご覧ください。

jobs.<job_id>.if

jobs.<job_id>.if 条件文を使って、条件が満たされなければジョブを実行しないようにできます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。 このキーでサポートされているコンテキストの詳細については、「コンテキスト リファレンス」を参照してください。

if 条件の中で式を使う際には、任意で式構文 ${{ }} を省略できます。これは、GitHub Actions が if 条件を式として自動的に評価するためです。 ただし、この例外はどこでも適用されるわけではありません。

! は YAML 形式で予約された表記であるため、必ず${{ }} 構文の式を使用するか、式が ! で始まる場合は ''、""、または () でエスケープする必要があります。 次に例を示します。

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

詳細については、 AUTOTITLE を参照してください。

例: 特定のリポジトリに対してのみジョブを実行する

この例では if を使って production-deploy ジョブを実行できるタイミングを制御しています。 リポジトリが octo-repo-prod という名前で、octo-org という組織内にある場合のみ実行されます。 それ以外の場合、ジョブはスキップ済みとしてマーク されます。

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: '14'
      - run: npm install -g bats

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

jobs.<job_id>.runs-on を使って、ジョブを実行するマシンの種類を定義します。

• 宛先マシンは、GitHub　がホストするランナー、より大きなランナー、またはセルフホステッド 型ランナーにすることができます。

• ランナーに割り当てられたラベル、グループ メンバーシップ、またはこれらの組み合わせに基づいてランナーをターゲットにすることができます。

• runs-on は次として指定できます。

  • 1 つの文字列
  • 文字列を含む 1 つの変数
  • 文字列の配列、文字列を含む変数、または両方の組み合わせ
  • key: value または group キーを使用する labels ペア

• 文字列または変数の配列を指定すると、指定された runs-on 値の全部に一致するランナー上でワークフローが実行されます。 たとえば、ここでは、ラベル linux、x64、gpu が付いているセルフホステッド ランナー上でのみジョブが実行されます。

  runs-on: [self-hosted, linux, x64, gpu]
  

  詳細については、自己ホストランナーの選択に関する記事を参照してください。

• 配列内で文字列と変数を混在させることができます。 次に例を示します。

  on:
    workflow_dispatch:
      inputs:
        chosen-os:
          required: true
          type: choice
          options:
          - Ubuntu
          - macOS
  
  jobs:
    test:
      runs-on: [self-hosted, "${{ inputs.chosen-os }}"]
      steps:
      - run: echo Hello world!
  

• 複数のマシンでワークフローを実行する場合は、jobs.<job_id>.strategy を使います。

GitHubホストランナーの選択

GitHubホストランナーを使用する場合、各ジョブは、runs-onで指定されたランナー イメージの新しいインスタンスで実行されます。

GitHub ホスト型ランナーを使用している場合、runs-on に指定する値は、ワークフロー ラベルまたはランナー グループの名前です。 標準の GitHubホストランナーのラベルを次の表に示します。

詳しくは、「GitHub ホステッド ランナー」をご覧ください。

パブリック リポジトリ向けの標準 GitHub ホスト型ランナー

パブリック リポジトリの場合、次の表に示すワークフロー ラベルを使用するジョブは、関連する仕様で実行されます。 単一CPUランナーを除き、各GitHubホストランナーは、GitHub によってホストされる新しい仮想マシン（VM）です。 Single-CPUランナーは、共有VM上のコンテナー内でホストされます。GitHub ホステッド ランナー リファレンスを参照してください。 標準の GitHubホストランナーの使用は無料で、パブリック リポジトリでは無制限です。

    <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md">ubuntu-latest</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md">ubuntu-24.04</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md">ubuntu-22.04</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Readme.md">ubuntu-26.04</a></code> (パブリック プレビュー) </td>
</tr>
<tr>
  <td>Windows</td>
  <td>4</td>
  <td>16 GB</td>
  <td>14 GB</td>
  <td> x64 </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md">windows-latest</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md">windows-2025</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-VS2026-Readme.md">windows-2025-vs2026</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md">windows-2022</a></code></td>
</tr>
<tr>
  <td>Linux</td>
  <td>4</td>
  <td>16 GB</td>
  <td>14 GB</td>
  <td> arm64 </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Arm64-Readme.md">ubuntu-24.04-arm</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Arm64-Readme.md">ubuntu-22.04-arm</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Arm64-Readme.md">ubuntu-26.04-arm</a></code> (パブリック プレビュー) </td>
</tr>
<tr>
  <td>Windows</td>
  <td>4</td>
  <td>16 GB</td>
  <td>14 GB</td>
  <td>arm64</td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows11-Arm64-Readme.md">windows-11-arm</a></code>, <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows11-VS2026-Arm64-Readme.md">windows-11-vs2026-arm</a></code></td>
</tr>
<tr>
  <td>macOS</td>
  <td>4</td>
  <td>14 GB</td>
  <td>14 GB</td>
  <td> Intel </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md">macos-15-intel</a></code>, <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-26-Readme.md">macos-26-intel</a></code></td>
</tr>
<tr>
  <td>macOS</td>
  <td>3 (M1)</td>
  <td>7 GB</td>
  <td>14 GB</td>
  <td> arm64 </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md">macos-latest</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md">macos-14</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-15-arm64-Readme.md">macos-15</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md">macos-26</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/xcode-27-arm64-Readme.md">xcode-27</a></code> (パブリック プレビュー) </td>
</tr>

標準 GitHub ホスト型ランナーによる プライベート リポジトリ

プライベート リポジトリの場合、次の表に示すワークフロー ラベルを使用するジョブは、関連する仕様を持つ仮想マシンで実行されます。 これらの通話には、GitHub アカウントに割り当てられた無料通話分が使用され、その後は分あたりの料金が課金されます。 「アクションズ ランナーの価格」を参照してください。

    <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md">ubuntu-latest</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md">ubuntu-24.04</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md">ubuntu-22.04</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Readme.md">ubuntu-26.04</a></code> (パブリック プレビュー) </td>
</tr>
<tr>
  <td>Windows</td>
  <td>2</td>
  <td>8GB</td>
  <td>14 GB</td>
  <td> x64 </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md">windows-latest</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md">windows-2025</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md">windows-2022</a></code></td>
</tr>
<tr>
  <td>Linux</td>
  <td>2</td>
  <td>8GB</td>
  <td>14 GB</td>
  <td> arm64 </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Arm64-Readme.md">ubuntu-24.04-arm</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Arm64-Readme.md">ubuntu-22.04-arm</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Arm64-Readme.md">ubuntu-26.04-arm</a></code> (パブリック プレビュー) </td>
</tr>
<tr>
  <td>Windows</td>
  <td>2</td>
  <td>8GB</td>
  <td>14 GB</td>
  <td> arm64 </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows11-Arm64-Readme.md">windows-11-arm</a></code>, <code><a href="https://github.com/actions/runner-images/blob/main/images/windows/Windows11-Arm64-VS2026-Readme.md">windows-11-vs2026-arm</a></code></td>
</tr>
<tr>
  <td>macOS</td>
  <td>4</td>
  <td>14 GB</td>
  <td>14 GB</td>
  <td> Intel </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md">macos-15-intel</a></code>, <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-26-Readme.md">macos-26-intel</a></code></td>
</tr>
<tr>
  <td>macOS</td>
  <td>3 (M1)</td>
  <td>7 GB</td>
  <td>14 GB</td>
  <td> arm64 </td>
  <td>
          
    <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md">macos-latest</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md">macos-14</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-15-arm64-Readme.md">macos-15</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md">macos-26</a></code>、 <code><a href="https://github.com/actions/runner-images/blob/main/images/macos/xcode-27-arm64-Readme.md">xcode-27</a></code> (パブリック プレビュー) </td>
</tr>

GitHubは、標準のGitHubホストランナーに加えて、GitHub TeamおよびGitHub Enterprise Cloudのお客様に、高度な機能を備えたさまざまなマネージド仮想マシン (コアとディスク領域、GPU 搭載マシン、ARM 搭載マシンなど) を計画しています。 詳しくは、「より大きなランナー」をご覧ください。

例: オペレーティング システムの指定

runs-on: ubuntu-latest

詳しくは、「GitHub ホステッド ランナー」をご覧ください。

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

ジョブにセルフホステッド ランナーを指定するには、ワークフロー ファイルでセルフホステッド ランナーのラベルを使って runs-on を設定します。

セルフホステッド ランナーには self-hosted ラベルが付いている場合があります。 セルフホステッド ランナーを設定すると、既定では self-hosted ラベルが付与されます。 --no-default-labels フラグを渡すことでセルフホステッド ラベルが適用されないように設定できます。 ラベルを使用すると、オペレーティング システムやアーキテクチャなど、特定のランナーを探すオプションを作成できます。self-hosted で始まり (リストの最初にこれを示す必要があります)、必要に応じて追加のラベルを含むラベルの配列を指定することをお勧めします。 ラベルの配列を指定すると、指定したラベルをすべて持つランナーのキューにジョブが配置されます。

例: ランナー選択のためのラベルの使用

runs-on: [self-hosted, linux]

詳細については、「セルフホステッド ランナー」および「ワークフローでのセルフホステッド ランナーの利用」を参照してください。

グループ内のランナーを選ぶ

runs-on を使用してランナー グループをターゲットにして、そのグループのメンバーである任意のランナーでジョブが実行されるようにすることができます。 よりきめ細かく制御するには、ランナー グループとラベルを組み合わせることもできます。

ランナー グループは、より大きなランナーまたはセルフホステッド ランナーのみをメンバーとして持つことができます。

例: グループを使用してジョブの実行場所を制御する

この例では、ランナーが build-runners というグループに追加されています。 runs-on キーは、build-runners グループ内の使用可能なランナーにジョブを送信します。

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: 
      group: build-runners
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

例: グループとラベルの組み合わせ

グループとラベルを組み合わせる場合、ランナーはジョブを実行する資格を得るために両方の要件を満たす必要があります。

この例では、 runs-on キーは group と labels を組み合わせて、同じラベルを持つグループ内の使用可能なランナーにジョブがルーティングされるようにします。

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-24.04-16core
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

jobs.<job_id>.snapshot

jobs.<job_id>.snapshotを使用してカスタム イメージを生成できます。

「カスタム イメージの生成」に示すように、文字列構文またはマッピング構文を使用して、スナップショット キーワードをジョブに追加します。

スナップショット キーワードを含む各ジョブは、個別のイメージを作成します。 1 つのイメージまたはイメージ バージョンのみを生成するには、すべてのワークフロー ステップを 1 つのジョブに含めます。 スナップショット キーワードを含むジョブが正常に実行されるたびに、そのイメージの新しいバージョンが作成されます。

詳しくは、「カスタム イメージの使用」をご覧ください。

jobs.<job_id>.environment

ジョブが参照する環境を定義するには、jobs.<job_id>.environment を使います。

環境 name のみ、または name と url を含む環境オブジェクトという形式で環境を指定できます。 URL はデプロイ API の environment_url にマップされます。 配置 API の詳細については、「リポジトリの REST API エンドポイント」を参照してください。

例: 1 つの環境名を使う

environment: staging_environment

例: 環境名と URL を使う

environment:
  name: production_environment
  url: https://github.com

url の値には式を指定できます。 使用できる式コンテキスト: github、inputs、vars、needs、strategy、matrix、job、runner、env、および steps。 式の詳細については、「ワークフロー内とアクション内で式を評価する」を参照してください。

例: 出力を URL として使う

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

name の値には式を指定できます。 使用できる式コンテキスト: github、inputs、vars、needs、strategy、matrix。 式の詳細については、「ワークフロー内とアクション内で式を評価する」を参照してください。

例: 環境名として式を使用する

environment:
  name: ${{ github.ref_name }}

例: デプロイを作成せずに環境を使用する

デプロイ オブジェクトを作成せずに環境のシークレットと変数を使用するには、 deployment を false に設定します。

environment:
  name: testing
  deployment: false

deployment: falseの設定は、カスタム展開保護規則と互換性がありません。 詳しくは、「GitHub Actionsを使用したデプロイ」をご覧ください。

jobs.<job_id>.concurrency

同じコンカレンシー グループを使うジョブまたはワークフローを一度に 1 つだけ実行するには、jobs.<job_id>.concurrency を使います。 並行処理グループには、任意の文字列または式を使用できます。 使用できる式コンテキスト: github、inputs、vars、needs、strategy、matrix。 式の詳細については、「ワークフロー内とアクション内で式を評価する」を参照してください。

ワークフロー レベルで concurrency を指定することもできます。 詳細については、「concurrency」を参照してください。

つまり、コンカレンシー グループ内に実行されているジョブまたはワークフローは、いつでも 1 つまで存在できます。 並行ジョブかワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中だと、キューイングされたジョブかワークフローは pending になります。 既定では、同じコンカレンシー グループ内の既存の pending ジョブまたはワークフローが取り消され、キューに登録された新しいジョブまたはワークフローが実行されます。

同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、cancel-in-progress: true を指定します。 同じコンカレンシー グループ内で現在実行中のジョブまたはワークフローを条件付きで取り消すには、許可されている式コンテキストのいずれかを含む式として cancel-in-progress を指定 できます。

複数の pending ジョブまたはワークフロー実行が同じコンカレンシー グループ内で待機できるようにするには、オプションの queue プロパティを使用します。 queue プロパティは、次の値を受け入れます。

• single (既定値): 最大 1 つのジョブまたはワークフロー実行をコンカレンシー グループに含めることができます。 新しいジョブまたはワークフローの実行がキューに登録されると、同じグループ内の既存の pending ジョブまたはワークフローの実行が取り消され、置き換えられます。
• max: コンカレンシー グループには、最大 100 個のジョブまたはワークフロー実行を pending できます。 キューがいっぱいになると、追加のジョブまたはワークフローの実行が取り消されます。

queue: maxとcancel-in-progress: trueの組み合わせは許可されず、ワークフロー検証エラーが発生します。

例：コンカレンシーとデフォルト動作の使用

GitHub Actionsの既定の動作は、複数のジョブまたはワークフローの実行を同時に実行できるようにすることです。 concurrency キーワード を使用すると、ワークフロー実行のコンカレンシーを制御できます。

たとえば、トリガー条件が定義された直後にconcurrencyキーワード を使用して、特定のブランチに対するワークフロー実行全体のコンカレンシーを制限できます：

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

ジョブ レベルでconcurrencyキーワード を使用して、ワークフロー内のジョブのコンカレンシーを制限することもできます：

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

例: 同時実行グループ

コンカレンシー グループは、同じコンカレンシー 鍵を共有するワークフロー実行またはジョブの実行を管理および制限する方法を提供します。

concurrency 鍵は、ワークフローまたはジョブをまとめてコンカレンシー グループにグループ化するために使用されます。 concurrency キーを定義すると、GitHub Actionsは、そのキーを持つワークフローまたはジョブが常に 1 つだけ実行されるようにします。 新しいワークフローの実行またはジョブが同じ concurrency キーで開始された場合、 GitHub Actions は、そのキーで既に実行されているワークフローまたはジョブを取り消します。 concurrency鍵は 、ハードコーディングされた文字列にすることも、コンテキスト変数を含む動的な式にすることもできます。

ワークフローまたはジョブがコンカレンシー グループの一部になるように、ワークフローでコンカレンシー条件を定義できます。

つまり、ワークフローの実行またはジョブが開始されると、GitHub は、同じコンカレンシー グループで既に進行状況にあるワークフローの実行またはジョブをキャンセルします。 これは、競合を引き起こしたり、必要以上に多くのリソースを消費したりする可能性のある処置を防ぐために、ステージング環境への展開に使用されるワークフローやジョブの特定のセットに対する並列実行を防ぐ場合に便利です。

この例では、 job-1は、staging_environmentと名付けられたコンカレンシー グループの一部です。 つまり、新しいjob-1 の実行がトリガーされると、既に進行状況の staging_environmentコンカレンシー グループ内の同じジョブの実行はすべてキャンセルされます。

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

または、ワークフロー内などの concurrency: ci-${{ github.ref }}のような 動的な式を使用すると、ワークフローまたはジョブは、ワークフローをトリガーしたブランチまたはタグのリファレンスに続く ci-と名付けられたコンカレンシー グループの一部になります。 この例では、前の実行の進行中に新しいコミットが メイン ブランチにプッシュされた場合、前の実行はキャンセルされ、新しいコミットが開始されます：

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

例: 複数の保留中の実行をキューする

既定では、同時実行グループに一度に pending できるジョブまたはワークフローの実行は 1 つだけです。 取り消されずに複数の実行をキューに入れるようにするには、 queue: max設定します。 queue: maxでは、最大 100 個のジョブまたはワークフロー実行がコンカレンシー グループで待機できます。キューがいっぱいになると、追加の実行はすべて取り消されます。

たとえば、次のワークフローは、 production 環境へのデプロイをキューに入れ、各実行がコンカレンシー グループの待機を開始したタイミングに基づいて順番に 1 つずつ処理します。

on:
  push:
    branches:
      - main

concurrency:
  group: production-deploy
  queue: max

queue: max cancel-in-progress: trueと組み合わせることはできません。2 つのオプションでは、進行中の実行を処理するための競合する動作が記述されているためです。

並行性を使って進行中のジョブもしくは実行をキャンセルする例

コンカレンシーを使用して進行中のジョブを取り消したり、 GitHub Actionsで実行したりするには、 concurrency キーを使用し、 cancel-in-progress オプションを trueに設定します。

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

この例では、特定のコンカレンシー グループを定義せずに、 GitHub Actions はジョブまたはワークフローの進行中の実行 を 取り消します。

例: フォールバック値の使用

特定のイベントにのみ定義されるプロパティでグループ名を作成する場合、フォールバック値を使用できます。 たとえば、github.head_ref は pull_request イベントにのみ定義されます。 ワークフローが pull_request イベントに加えて他のイベントにも応答する場合、構文エラーを回避するためにフォールバックを指定する必要があります。 次のコンカレンシー グループは、pull_request イベントで進行中のジョブか実行のみを取り消します。github.head_ref が未定義の場合、コンカレンシー グループは実行 ID にフォールバックします。これは、一意であり、実行に対して定義されていることが保証されています。

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

例: 現在のワークフローで進行中のジョブまたは実行のみを取り消します

同じリポジトリに複数のワークフローがある場合、他のワークフローの進行中のジョブまたは実行が取り消されないように、コンカレンシー グループ名はワークフロー間で一意である必要があります。 そうでない場合、ワークフローに関係なく、以前に進行中または保留中のジョブが取り消されます。

同じワークフローの進行中の実行だけを取り消すには、github.workflow プロパティを使ってコンカレンシー グループを構築します。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

例: 具体的なブランチで進行中のジョブのみをキャンセルする

特定のブランチで進行中のジョブを取り消したいが、他のブランチでは取り消さない場合は、cancel-in-progress で条件式を使用できます。 たとえば、開発ブランチでは進行中のジョブを取り消したいが、リリース ブランチでは取り消さない場合に、これを実行できます。

リリース ブランチで実行されていない場合に、同じワークフローの進行中の実行のみを取り消すには、cancel-in-progress を次のような式に設定します。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

この例では、release/1.2.3 ブランチへの複数のプッシュは進行中の実行を取り消しません。 main などの別のブランチにプッシュすると、進行中の実行が取り消されます。

jobs.<job_id>.cache-mode

jobs.<job_id>.cache-modeを使用して、1 つのジョブGitHub Actionsキャッシュ アクセスのレベルを設定します。 ここで設定した値は、このジョブのワークフロー レベルの cache-mode のみをオーバーライドします。

使用できる値は、最上位のキーと同じ意味で read、 write、 write-only、および noneです。 ジョブもワークフローも cache-mode設定しない場合は、トリガーベースの既定値が適用されます。 各値の詳細については、「 cache-mode および 依存関係キャッシュのリファレンス」を参照してください。

また、再利用可能なワークフローを呼び出すジョブに cache-mode を設定して、呼び出されたワークフローに付与されるキャッシュ アクセスを制限することもできます。 詳細については、「ワークフロー構成の再利用」および「ワークフローを再利用する」を参照してください。

jobs.<job_id>.cache-mode の例

jobs:
  build:
    runs-on: ubuntu-latest
    cache-mode: write
  test:
    runs-on: ubuntu-latest
    cache-mode: read

jobs.<job_id>.outputs

jobs.<job_id>.outputs を使用して、ジョブ用の出力mapを作成できます。 ジョブの出力は、このジョブに依存するすべての下流ジョブで利用できます。 ジョブ依存関係の定義の詳細については、「jobs.<job_id>.needs」を参照してください。

出力は、1 つのジョブにつき最大 1 MB です。 ワークフロー実行内のすべての出力の合計は、最大 50 MB です。 サイズは UTF-16 エンコードに基づいて概算されます。

表現が含まれているジョブの出力は、各ジョブの終了時にランナー上で評価されます。 シークレットを含む出力はランナーで編集され、 GitHub Actionsに送信されません。

出力に秘密情報が含まれる可能性があるためスキップされた場合、「秘密情報が含まれる可能性があるため出力{output.Key}をスキップする」という警告メッセージが表示されます。 秘密情報の取り扱い方法の詳細については、「例:ジョブまたはワークフロー間で秘密情報をマスクおよび受け渡しする方法」を参照してください。

依存するジョブでジョブ出力を使うには、needs コンテキストを使用できます。 詳しくは、「コンテキスト リファレンス」をご覧ください。

例: ジョブの出力の定義

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "test=hello" >> "$GITHUB_OUTPUT"
      - id: step2
        run: echo "test=world" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - env:
          OUTPUT1: ${{needs.job1.outputs.output1}}
          OUTPUT2: ${{needs.job1.outputs.output2}}
        run: echo "$OUTPUT1 $OUTPUT2"

マトリックス ジョブでのジョブ出力の使用

マトリックスを使用して、異なる名前の複数の出力を生成できます。 マトリックスを使用する場合、ジョブ出力はマトリックス内のすべてのジョブから結合されます。

jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      output_1: ${{ steps.gen_output.outputs.output_1 }}
      output_2: ${{ steps.gen_output.outputs.output_2 }}
      output_3: ${{ steps.gen_output.outputs.output_3 }}
    strategy:
      matrix:
        version: [1, 2, 3]
    steps:
      - name: Generate output
        id: gen_output
        run: |
          version="${{ matrix.version }}"
          echo "output_${version}=${version}" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: [job1]
    steps:
      # Will show
      # {
      #   "output_1": "1",
      #   "output_2": "2",
      #   "output_3": "3"
      # }
      - run: echo '${{ toJSON(needs.job1.outputs) }}'

jobs.<job_id>.env

ジョブ中のすべてのステップで使うことができる変数の map です。 ワークフロー全体または個々のステップの変数を設定できます。 詳細については、env および jobs.<job_id>.steps[*].env を参照してください。

同じ名前で複数の環境変数が定義されている場合、GitHub では最も具体的な変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の環境変数をステップの実行の間オーバーライドします。 ジョブで定義された環境変数は、そのジョブの実行の間はワークフローの同じ名前の変数をオーバーライドします。

jobs.<job_id>.env の例

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

jobs.<job_id>.defaults を使用して、デフォルト設定の map を作成します。これは、ジョブ内のすべてのシェルに適用されます。 ワークフロー全体に対してデフォルト設定を設定することもできます。 詳細については、「defaults」を参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

jobs.<job_id>.defaults.run

jobs.<job_id>.defaults.run を使用して、ジョブ内のすべての shell ステップに既定の working-directory と run を指定します。

ジョブ内のすべての working-directory ステップに対して、既定の run オプションと オプションを指定できます。 また、ワークフロー全体の run に既定の設定を設定することもできます。 詳細については、「defaults.run」を参照してください。

これらは、jobs.<job_id>.defaults.run と jobs.<job_id>.steps[*].run のレベルでオーバーライドできます。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

jobs.<job_id>.defaults.run.shell

shell を使用してステップの shell を定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

jobs.<job_id>.defaults.run.working-directory

working-directory を使用してステップの shell の作業ディレクトリを定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

例: ジョブの既定の run ステップ オプションの設定

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: ./scripts

jobs.<job_id>.steps

1 つのジョブには、steps と呼ばれる一連のタスクがあります。 ステップでは、コマンドを実行する、設定タスクを実行する、あるいはリポジトリやパブリックリポジトリ、Dockerレジストリで公開されたアクションを実行することができます。 すべてのステップでアクションを実行するとは限りませんが、すべてのアクションはステップとして実行されます。 各ステップは、ランナー環境のそれ自体のプロセスで実行され、ワークスペースとファイルシステムにアクセスします。 ステップはそれ自体のプロセスで実行されるため、環境変数を変更しても、ステップ間では反映されません。 GitHub には、ジョブを設定して完了するための組み込みの手順が用意されています。

GitHub 最初の 1,000 個のチェックのみが表示されますが、ワークフローの使用制限内であれば、無制限の数のステップを実行できます。 詳細については、ホストランナーの GitHub とセルフホステッド ランナーの使用制限に関する アクションの制限 を参照してください。

jobs.<job_id>.steps の例

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

ステップの一意の識別子。 id を使って、コンテキストのステップを参照することができます。 詳しくは、「コンテキスト リファレンス」をご覧ください。

jobs.<job_id>.steps[*].if

if 条件文を使って、条件が満たされなければ、ステップを実行しないようにすることができます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。 このキーでサポートされているコンテキストの詳細については、「コンテキスト リファレンス」を参照してください。

if 条件の中で式を使う際には、任意で式構文 ${{ }} を省略できます。これは、GitHub Actions が if 条件を式として自動的に評価するためです。 ただし、この例外はどこでも適用されるわけではありません。

! は YAML 形式で予約された表記であるため、必ず${{ }} 構文の式を使用するか、式が ! で始まる場合は ''、""、または () でエスケープする必要があります。 次に例を示します。

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

詳細については、 AUTOTITLE を参照してください。

例: コンテキストの使用

このステップは、イベントの種類が pull_request で、イベント アクションが unassigned である場合にのみ実行されます。

steps:
  - name: My first step
    if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
    run: echo This event is a pull request that had an assignee removed.

例: ステータス チェック関数の使用

my backup step は、ジョブの前のステップが失敗した場合にのみ実行されます。 詳しくは、「ワークフロー内とアクション内で式を評価する」をご覧ください。

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

例: シークレットの使用

if: 条件文でシークレットを直接参照することはできません。 代わりに、シークレットをジョブ レベルの環境変数として設定し、ジョブのステップを条件付きで実行するために環境変数を参照することを検討してください。

シークレットが設定されていない場合、シークレットを参照する式の戻り値 (例では ${{ secrets.SuperSecret }} など) は空の文字列になります。

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

詳細については、「コンテキスト リファレンス」および「GitHub Actions でのシークレットの使用」を参照してください。

jobs.<job_id>.steps[*].name

GitHubに表示されるステップの名前。

jobs.<job_id>.steps[*].uses

ジョブでステップの一部として実行されるアクションを選択します。 アクションとは、再利用可能なコードの単位です。 ワークフローと同じリポジトリ、パブリック リポジトリ、または公開されている Docker コンテナー イメージで定義されているアクションを使用できます。

Git ref、SHA、または Docker タグを指定することで、使っているアクションのバージョンを含めることを、強く推奨しています。 バージョンを指定しないと、アクションのオーナーがアップデートを公開したときに、ワークフローが中断したり、予期せぬ動作をしたりすることがあります。

• リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
• アクションでメジャー バージョン タグが発行される場合は、互換性を維持しながら、重要な修正プログラムとセキュリティ パッチを受け取ることを予期する必要があります。 この動作は、アクションの作成者が判断するものであることに注意してください。
• アクションのデフォルトブランチを使用すると便利なこともありますが、別のユーザが破壊的変更を加えた新しいメジャーバージョンをリリースすると、ワークフローが動作しなくなる場合があります。

一部のアクションでは、with キーワードを使用して設定する必要がある入力が必要です。 必要な入力を判断するには、アクションのREADMEファイルをお読みください。

アクションは、JavaScriptのファイルもしくはDockerコンテナです。 使用するアクションがDockerコンテナの場合、ジョブはLinux環境で実行する必要があります。 詳細については、runs-on を参照してください。

例: バージョン管理されたアクションの使用

steps:
  # Reference a specific commit
  - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
  # Reference the major version of a release
  - uses: actions/checkout@v6
  # Reference a specific version
  - uses: actions/checkout@v6.2.0
  # Reference a branch
  - uses: actions/checkout@main

例: パブリック アクションの使用

{owner}/{repo}@{ref}

パブリック GitHub リポジトリには、ブランチ、ref、または SHA を指定できます。

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

例: サブディレクトリのパブリック アクションの使用

{owner}/{repo}/{path}@{ref}

特定のブランチ、ref、または SHA にあるパブリック GitHub リポジトリ内のサブディレクトリ。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

例: 実行中のコミットでワークフローと同じリポジトリ内のアクションを使用する (推奨)

$/path/to/action

$/ プレフィックスは自己リポジトリ参照です。 現在実行中のワークフローまたはアクションと同じリポジトリに格納されているアクションを参照し、実行中のコミット (実行中のワークフローまたはアクションと同じ SHA) でそのリポジトリに解決されます。 最初にリポジトリをチェックアウトする必要がないため、独自のリポジトリ内のアクションを参照することをお勧めします。

$/構文は、GitHub Enterprise Serverでは使用できません。

$/参照には、@{ref}サフィックスを含めてはなりません。 ref は常に実行中のワークフローまたはアクションが使用しているコミットであるため、 $/actions/my-action@v1 などの参照は無効です。

$/ は常に、呼び出し元のリポジトリではなく、その記述があるファイルのリポジトリを基準に解決されます。 たとえば、あるリポジトリの再利用可能なワークフローが別のリポジトリのワークフローによって呼び出された場合、呼び出されたワークフローの $/ 参照は、呼び出し元のワークフローのリポジトリではなく、呼び出されたワークフローのリポジトリに解決されます。 そのため、アクションを組み合わせても $/ の参照先は安定します。一方、相対パス ./ は、呼び出し元のワークスペースでチェックアウトされている内容を基準に解決されます。 複合アクションの手順で $/ を使用する方法については、「 メタデータ構文リファレンス」を参照してください。

次の表は、アクションを参照する方法を比較したものです。

on: [push]

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # References an action in the same repository at the running commit
      - uses: $/.github/actions/hello-world-action

例: ワークフローと同じリポジトリにあるアクションの使用

./path/to/dir

ワークフローのリポジトリにあるアクションを含むディレクトリのパス。 アクションを使用する前にリポジトリをチェックアウトする必要があります。 ./ パスは、実行中のワークフローのリポジトリではなくランナーのワークスペースに対して解決されます。 ほとんどの場合、代わりに上記の $/ 構文を使用してください。

リポジトリ ファイル構造の例:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

パスはデフォルトの作業ディレクトリ (github.workspace、$GITHUB_WORKSPACE) に対する相対パス (./) です。 アクションがワークフローとは異なる場所にリポジトリをチェックアウトする場合は、ローカル アクションに使用される相対パスを更新する必要があります。

ワークフロー ファイルの例:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v6
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

例: Docker Hub アクションの使用

docker://{image}:{tag}

Docker Hub で公開されている Docker イメージ。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

例: GitHub PackagesContainer registry

docker://{host}/{image}:{tag}

GitHub Packages Container registry内のパブリック Docker イメージ。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://ghcr.io/OWNER/IMAGE_NAME

例: Docker パブリック レジストリ アクションの使用

docker://{host}/{image}:{tag}

パブリックレジストリのDockerイメージ。 この例では、gcr.io にある Google Container Registry を使っています。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

例: ワークフローとは異なるプライベート リポジトリ内でのアクションの使用

アクションが内部リポジトリ内にある場合、またはワークフローのリポジトリからのアクセスを許可するように構成されたプライベート リポジトリ内にある場合は、アクションを直接参照できます。 詳細については、「 リポジトリのGitHub Actions設定の管理 および リポジトリのGitHub Actions設定の管理」を参照してください。

アクセスを許可するように構成されたリポジトリにアクションがない場合は、リポジトリをチェックアウトし、アクションをローカルで参照する必要があります。 personal access tokenを生成し、シークレットとしてトークンを追加します。 次の例は、アクションを参照するためのこのメソッドを示しています。 詳細については、「個人用アクセス トークンを管理する」および「GitHub Actions でのシークレットの使用」を参照してください。

この例の PERSONAL_ACCESS_TOKEN をシークレットの名前に置き換えます。

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v6
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

または、GitHub Appではなくpersonal access tokenを使用して、personal access token所有者が離れる場合でもワークフローが引き続き実行されるようにします。 詳しくは、「GitHub Actions ワークフローでGitHub アプリを使用して認証済み API 要求を作成する」をご覧ください。

jobs.<job_id>.steps[*].run

オペレーティング システムのシェルを使用して、21,000 文字を超えないコマンド ライン プログラムを実行します。 name を指定しない場合、ステップ名は既定では run コマンドで指定されたテキストになります。

コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 詳細については、「jobs.<job_id>.steps[*].shell」を参照してください。

run キーワードは、それぞれがランナー環境での新しいプロセスとシェルを表します。 複数行のコマンドを指定すると、各行が同じシェルで実行されます。 次に例を示します。

• 1行のコマンド：

  - name: Install Dependencies
    run: npm install
  

• 複数行のコマンド：

  - name: Clean install dependencies and build
    run: |
      npm ci
      npm run build
  

jobs.<job_id>.steps[*].working-directory

working-directory キーワードを使えば、コマンドが実行される作業ディレクトリを指定できます。

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

または、ジョブ内のすべてのrunステップまたはワークフロー全体のすべてのrunステップに既定の作業ディレクトリを指定することもできます。 詳細については、defaults.run.working-directory および jobs.<job_id>.defaults.run.working-directory を参照してください。

runステップを使用してスクリプトを実行することもできます。 詳しくは、「ワークフローにスクリプトを追加する」をご覧ください。

jobs.<job_id>.steps[*].shell

shell キーワードを使用して、ランナーのオペレーティング システムのデフォルト シェル設定とジョブのデフォルトをオーバーライドできます。 組み込みの shell キーワードを使いことも、カスタム セットのシェル オプションを定義することもできます。 内部で実行されるシェル コマンドによって、run キーワードで指定されたコマンドを含む一時ファイルが実行されます。

または、ジョブのすべての run ステップまたはワークフロー全体のすべての run ステップにデフォルト シェルを指定することもできます。 詳細については、defaults.run.shell および jobs.<job_id>.defaults.run.shell を参照してください。

例: Bash を使ったコマンドの実行

steps:
  - name: Display the path
    shell: bash
    run: echo $PATH

例: Windows cmd を使ったコマンドの実行

steps:
  - name: Display the path
    shell: cmd
    run: echo %PATH%

例: PowerShell Core を使ったコマンドの実行

steps:
  - name: Display the path
    shell: pwsh
    run: echo ${env:PATH}

PowerShell Desktopを使用してコマンドを実行する例

steps:
  - name: Display the path
    shell: powershell
    run: echo ${env:PATH}

例: インライン Python スクリプトの実行

steps:
  - name: Display the path
    shell: python
    run: |
      import os
      print(os.environ['PATH'])

カスタムシェル

shell を使って、テンプレート文字列に command [options] {0} [more_options] 値を設定できます。 GitHub は、文字列の最初の空白で区切られた単語をコマンドとして解釈し、一時スクリプトのファイル名を {0}に挿入します。

次に例を示します。

steps:
  - name: Display the environment variables and their values
    shell: perl {0}
    run: |
      print %ENV

使われるコマンド (この例では perl) は、ランナーにインストールされている必要があります。

GitHub でホストされるランナーに含まれるソフトウェアの詳細については、 GitHub ホステッド ランナー を参照してください。

終了コードとエラーアクションの環境設定

組み込みのシェル キーワードの場合、 GitHubホストランナーによって実行される次の既定値が提供されます。 シェルスクリプトを実行する際には、以下のガイドラインを使ってください。

• bash / sh:

  • 既定では、フェイルファスト動作は、set -e と sh の両方に bash を使用して強制されます。 shell: bash が指定されている場合、ゼロ以外の終了ステータスを生成するパイプラインからの早期終了を強制するために -o pipefail も適用されます。
  • シェル オプションにテンプレート文字列を指定することで、シェル パラメーターを完全に制御できます。 たとえば、bash {0} のようにします。
  • sh ライクのシェルは、スクリプトで実行された最後のコマンドの終了コードで終了します。これは、アクションの既定の動作でもあります。 runnerは、この終了コードに基づいてステップのステータスを失敗/成功としてレポートします。

• powershell/pwsh

  • 可能な場合のフェイルファースト動作。 pwsh と powershell の組み込みのシェルでは、スクリプトの内容の前に $ErrorActionPreference = 'stop' を追加します。
  • PowerShell スクリプトに if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } を追加して、アクションの状態にスクリプトの最後の終了コードが反映されるようにします。
  • ユーザーは、組み込みのシェルを使わずに、必要に応じて pwsh -File {0} や powershell -Command "& '{0}'" のようなカスタム シェル オプションを指定するといつでもオプトアウトできます。

• cmd

  • 各エラーコードをチェックしてそれぞれに対応するスクリプトを書く以外、フェイルファースト動作を完全にオプトインする方法はないようです。 デフォルトでその動作を指定することはできないため、この動作はスクリプトに記述する必要があります。
  • cmd.exe は実行した最後のプログラムのエラー レベルで終了し、ランナーにエラー コードが返されます。 この動作は、内部的には前の sh と pwsh の既定の動作と一致しており、cmd.exe の既定であるため、この動作は変更されません。

jobs.<job_id>.steps[*].with

入力パラメーターのmap はアクションによって定義されています。 各入力パラメータはキー/値ペアです。 入力パラメータは環境変数として設定されます。 変数の前には INPUT_ が付けられ、大文字に変換されます。

Docker コンテナーに定義された入力パラメーターは args を使用する必要があります。 詳細については、「jobs.<job_id>.steps[*].with.args」を参照してください。

jobs.<job_id>.steps[*].with の例

first_name アクションによって定義される 3 つの入力パラメーター (middle_name、last_name、hello_world) を定義します。 これらの入力変数には、hello-world、INPUT_FIRST_NAME、INPUT_MIDDLE_NAME の環境変数として INPUT_LAST_NAME アクションからアクセスできます。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

Docker コンテナーの入力を定義する string。 GitHubは、コンテナーの起動時にコンテナーのargsにENTRYPOINTを渡します。 array of strings はこのパラメーターではサポートされていません。 スペースを含む 1 つの引数は、二重引用符 "" で囲む必要があります。

jobs.<job_id>.steps[*].with.args の例

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

args は、CMD 内の Dockerfile 命令の代わりに使用されます。 ご自分の CMD で Dockerfile を使用する場合は、以下の優先順のガイドラインを使用してください。

1. アクションの README 中で必須の引数をドキュメント化し、CMD 命令から除外します。
2. args を指定せずにアクションを利用できるよう、既定値を使用します。
3. アクションによって --help フラグなどが公開される場合、アクションを自己文書化するための既定としてこれを使います。

jobs.<job_id>.steps[*].with.entrypoint

ENTRYPOINT 内の Docker の Dockerfile をオーバーライドするか、まだ指定されていない場合は設定します。 shell や exec 形式を持つ Docker の ENTRYPOINT 命令とは異なり、entrypoint キーワードでは、実行する実行可能ファイルを定義する単一の文字列だけを受け付けます。

jobs.<job_id>.steps[*].with.entrypoint の例

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

entrypoint キーワードは Docker コンテナー アクションで使われることを意図したものですが、入力を定義しない JavaScript のアクションでも使うことができます。

jobs.<job_id>.steps[*].env

ランナー環境で使うステップの変数を設定します。 ワークフロー全体またはジョブの変数を設定することもできます。 詳細については、env および jobs.<job_id>.env を参照してください。

同じ名前で複数の環境変数が定義されている場合、GitHub では最も具体的な変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の環境変数をステップの実行の間オーバーライドします。 ジョブで定義された環境変数は、そのジョブの実行の間はワークフローの同じ名前の変数をオーバーライドします。

パブリックなアクションを実行すると、README ファイル内で想定されている変数が指定されることがあります。 シークレットまたは機密性の高い値 (パスワードやトークンなど) を設定している場合は、secrets コンテキストを使ってシークレットを設定する必要があります。 詳しくは、「コンテキスト リファレンス」をご覧ください。

jobs.<job_id>.steps[*].env の例

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

ステップが失敗してもジョブが失敗にならないようにします。 true に設定すれば、このステップが失敗した場合にジョブを成功させることができます。

jobs.<job_id>.steps[*].timeout-minutes

プロセスがkillされるまでにステップが実行できる最大の分数。 最大: GitHubホストランナーとセルフホステッド ランナーの両方に対して 360。

小数値はサポートされていません。 timeout-minutes は、正の整数にする必要があります。

jobs.<job_id>.steps[*].background

ステップを非同期的に実行して、ジョブが完了するのを待たずに次のステップに進みます。 background: trueは、他の手順と共に実行する必要がある、データベース、サーバー、監視タスクなどの実行時間の長いプロセスに使用します。 バックグラウンドステップは、後で wait または wait-all を使用して同期するか、 cancelで停止します。

backgroundまたはrunを使用する手順では、usesを使用できます。 wait またはcancelからバックグラウンド ステップを参照するには、idを指定します。 1 つのジョブで同時に実行できるバックグラウンド ステップは最大 10 個です。追加のバックグラウンドステップは、スロットが空きになるまでキューに入れられます。

バックグラウンド ステップからの出力と環境の変更は、 wait またはそれを含む wait-all ステップを実行した後にのみ使用できます。 バックグラウンド ステップが失敗した場合、ジョブは次の wait またはそれを含む wait-all で失敗します (そのステップで continue-on-error が設定されていない場合)。 wait-all は、ジョブ後のクリーンアップ処理の前に暗黙的に実行されます。

詳細な制御が必要な場合は、 background を使用します。後の手順の実行中に実行時間の長いプロセス (サーバーやデータベースなど) を開始したり、 wait または cancelを使用して特定のステップを参照したり、バックグラウンド作業を他のステップとインターリーブしたりできます。 代わりに、ジョブが続行する前にすべて完了する必要がある自己完結型のステップ グループがある場合は、 parallel の方が簡単です。

例: バックグラウンドでのステップの実行

steps:
  - name: Start server
    id: server
    run: npm start
    background: true

  - name: Run tests against the server
    run: npm test

  - name: Wait for the server step to finish
    wait: server

jobs.<job_id>.steps[*].wait

1 つ以上のバックグラウンド ステップが完了するまでジョブを一時停止します。 waitステップでは、それ自体は実行されません。参照されるバックグラウンド ステップが完了するまでブロックされます。 1 つのステップ id を文字列として指定するか、配列として複数のステップ idを指定します。

waitステップが完了すると、参照されるバックグラウンド ステップの出力が後続のステップで使用できるようになります。 参照先のバックグラウンド ステップが失敗した場合、 wait ステップも失敗します。

例: 特定のバックグラウンド ステップを待機しています

steps:
  - name: Build frontend
    id: build-frontend
    run: npm run build:frontend
    background: true

  - name: Build backend
    id: build-backend
    run: npm run build:backend
    background: true

  - name: Run linter while builds run
    run: npm run lint

  - name: Wait for both builds to finish
    wait: [build-frontend, build-backend]

  - name: Run tests
    run: npm test

jobs.<job_id>.steps[*].wait-all

すべてのアクティブなバックグラウンド ステップが完了するまでジョブを一時停止します。 これは、いくつかのバックグラウンドステップが実行されていて、続行する前にそれらすべてを終了したい場合に便利です。 wait と同様に、wait-all を continue-on-error に設定している場合を除き、 ステップは、そのステップが待機しているバックグラウンド ステップのいずれかが失敗すると失敗します。

wait-all キーワードは引数を受け取っていません。

例: すべてのバックグラウンド ステップの完了を待機する

steps:
  - name: Start database
    id: db
    run: docker run -d postgres:15
    background: true

  - name: Start cache
    id: cache
    run: docker run -d redis:7
    background: true

  - name: Run integration tests
    run: npm run test:integration

  - name: Wait for all services to stop
    wait-all:

jobs.<job_id>.steps[*].cancel

実行中のバックグラウンド ステップを正常に終了します。 ランナーは、ステップのプロセスを終了シグナル (SIGTERM) を送信してクリーンアップし、短い猶予期間で終了しない場合は強制的に停止 (SIGKILL) します。 cancel キーワードは、idによって 1 つのバックグラウンド ステップを対象とします。

例: バックグラウンド ステップの取り消し

steps:
  - name: Start long-running monitor
    id: monitor
    run: ./scripts/monitor.sh
    background: true

  - name: Run the main task
    run: npm test

  - name: Stop the monitor
    cancel: monitor

jobs.<job_id>.steps[*].parallel

ステップのグループを同時に実行し、すべてのステップが完了するのを待ってから続行します。 parallel キーワードは省略形です。グループ内のすべてのステップはバックグラウンド ステップとして実行され、グループの末尾に暗黙的なwaitが含まれます。 同時に実行できる独立したステップ グループがあり、個別に参照する必要がない場合に使用します。

一度に複数のコンポーネントをビルドするなど、ジョブが開始される前にすべて完了する必要がある自己完結型のステップ グループがある場合は、 parallel を使用します。 より細かい制御が必要な場合は、 background を使用します。後の手順の実行中に実行時間の長いプロセス (サーバーやデータベースなど) を開始したり、 wait または cancelで特定のステップを参照したり、バックグラウンド作業を他の手順とインターリーブしたりできます。 要するに、 parallel は制限されていますが、"このグループを一度に実行する" ケースではより便利ですが、 background は汎用プリミティブです。

グループ内の各ステップには、他のバックグラウンド ステップと同じ 10 ステップのコンカレンシー制限が適用されます。

例: ステップを並列で実行する

steps:
  - uses: actions/checkout@v6

  - parallel:
      - name: Build frontend
        run: npm run build:frontend

      - name: Build backend
        run: npm run build:backend

      - name: Build docs
        run: npm run build:docs

  - name: Run tests after all builds complete
    run: npm test

上記のグループは、各ステップを background: true 後に wait ステップで宣言することと同じです。

jobs.<job_id>.timeout-minutes

実行したジョブがGitHub自動的に取り消されるまでの最大分数を設定します。 デフォルト: 360

タイムアウトがランナーのジョブ実行の制限時間を超えた場合、代わりに、実行の制限時間に達したときにジョブが取り消されます。 ジョブの実行時間制限の詳細については、ホストランナーの GitHub とセルフホステッド ランナーの使用制限に関する アクションの制限 を参照してください。

jobs.<job_id>.strategy

ジョブにマトリックス戦略を使うには、jobs.<job_id>.strategy を使用します。 マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。 たとえば、マトリックス戦略を使用して、複数バージョンの言語または複数のオペレーティング システムでコードをテストできます。 詳細については、 AUTOTITLE を参照してください。

jobs.<job_id>.strategy.matrix

jobs.<job_id>.strategy.matrix を使用して、さまざまなジョブの設定のマトリックスを定義します。 詳しくは、「ワークフローでのジョブのバリエーションの実行」をご覧ください。

このマトリックスでは、ワークフローの実行ごとに最大で 256 のジョブが生成されます。 この制限は、 GitHubホストランナーとセルフホステッド ランナーの両方に適用されます。

定義した変数は、matrix のコンテキストでのプロパティとなり、ワークフロー ファイルの他のエリア内のプロパティを参照できます。 この例では、matrix.version および matrix.os を使用して、ジョブが使用している version および os の現在の値にアクセスできます。 詳しくは、「コンテキスト リファレンス」をご覧ください。

既定では、 GitHub はランナーの可用性に応じて、並列で実行されるジョブの数を最大化します。 マトリックス内の変数の順序によって、ジョブが作成される順序が決まります。 定義する最初の変数は、ワークフローの実行で最初に作成されるジョブになります。

1 次元マトリックスの使用

次のワークフローでは、変数 version に値 [10, 12, 14] を定義しています。 このワークフローでは、変数の値ごとに 1 つずつ、3 つのジョブが実行されます。 各ジョブは、version コンテキストを通して matrix.version 値にアクセスし、node-version として actions/setup-node アクションにその値を渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.version }}

多次元マトリックスの使用

多次元マトリックスを作成するには、複数の変数を指定します。 ジョブは、変数の可能な組み合わせごとに実行されます。

たとえば、次のワークフローでは 2 つの変数を指定しています。

• os 変数で指定された 2 つのオペレーティング システム
• version 変数で指定された 3 つの Node.js バージョン

このワークフローでは、os と version 変数の組み合わせごとに 1 つずつ、計 6 つのジョブが実行されます。 各ジョブは、runs-on の値を現在の os の値に設定し、現在の version の値を actions/setup-node アクションに渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-24.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.version }}

マトリックス内の変数構成は、array の object として表現されることがあります。 たとえば、次のマトリックスでは、対応するコンテキストで 4 つのジョブが生成されます。

matrix:
  os:
    - ubuntu-latest
    - macos-latest
  node:
    - version: 14
    - version: 20
      env: NODE_OPTIONS=--openssl-legacy-provider

次に示すように、マトリックス内の各ジョブは、os と node の値の独自の組み合わせを持ちます。

- matrix.os: ubuntu-latest
  matrix.node.version: 14
- matrix.os: ubuntu-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
  matrix.node.version: 14
- matrix.os: macos-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider

jobs.<job_id>.strategy.matrix.include

include リスト内の各オブジェクトに対して、キーと値のペアのいずれも元のマトリックス値を上書きしない場合、オブジェクト内のキーと値のペアが各マトリックスの組み合わせに追加されます。 オブジェクトをどのマトリックスの組み合わせにも追加できない場合は、代わりに新しいマトリックスの組み合わせが作成されます。 元のマトリックス値は上書きされませんが、追加されたマトリックス値は上書きできます。

例: 構成の展開

たとえば、次のワークフローでは、os と node の組み合わせごとに 1 つずつ、計 4 つのジョブが実行されます。 os の値が windows-latest で node の値が 16 のジョブが実行されると、6 の値を持つ npm という追加の変数がジョブに含まれます。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

例: 構成の追加

たとえば、このマトリックスでは 10 個のジョブが実行されます。マトリックス内の os と version の組み合わせごとに 1 つと、windows-latest の os 値と 17 の version 値のジョブです。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

マトリックス変数を指定しない場合は、include の下のすべての構成が実行されます。 たとえば、次のワークフローでは、include エントリごとに 1 つずつ、2 つのジョブが実行されます。 これにより、マトリックスを完全に設定しなくても、マトリックス戦略を利用できます。

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

除外対象とするには、構成が部分一致していれば十分です。

include のすべての組み合わせが、exclude の後で処理されます。 このため、include を使って以前に除外された組み合わせを追加し直すことができます。

jobs.<job_id>.strategy.fail-fast

jobs.<job_id>.strategy.fail-fast と jobs.<job_id>.continue-on-error を使用して、ジョブ エラーの処理方法制御できます。

jobs.<job_id>.strategy.fail-fast はマトリックス全体に適用されます。 jobs.<job_id>.strategy.fail-fast が true に設定されているか、その式が true と評価されている場合、マトリックス内のいずれかのジョブが失敗すると、進行中およびキューに入れられたすべてのジョブは GitHub によって取り消されます。 このプロパティでは、既定値が true に設定されます。

jobs.<job_id>.continue-on-error は 1 つのジョブに適用されます。 jobs.<job_id>.continue-on-error が true、jobs.<job_id>.continue-on-error: true が失敗するジョブであっても、マトリックス内の他のジョブは引き続き実行されます。

jobs.<job_id>.strategy.fail-fast と jobs.<job_id>.continue-on-error は一緒に使用できます。 たとえば、次のワークフローは 4 つのジョブを開始します。 ジョブごとに、continue-on-error は matrix.experimental の値によって決定されます。 continue-on-error: false のいずれかのジョブが失敗すると、進行中またはキューに入っているすべてのジョブがキャンセルされます。 continue-on-error: true のジョブが失敗した場合、他のジョブは影響を受けません。

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

既定では、 GitHub はランナーの可用性に応じて、並列で実行されるジョブの数を最大化します。

jobs.<job_id>.continue-on-error

jobs.<job_id>.continue-on-error は 1 つのジョブに適用されます。 jobs.<job_id>.continue-on-error が true、jobs.<job_id>.continue-on-error: true が失敗するジョブであっても、マトリックス内の他のジョブは引き続き実行されます。

ジョブが失敗しても、ワークフローの実行が失敗とならないようにします。 true に設定すれば、このジョブが失敗したときにワークフローの実行を成功させることができます。

例: 失敗した特定のマトリックス ジョブがワークフローの実行を失敗させないようにする

ジョブマトリックス中の特定のジョブが失敗しても、ワークフローの実行が失敗にならないようにすることができます。 たとえば、node が 15 に設定された実験的なジョブが失敗しても、ワークフローの実行を失敗させないようにしたいとしましょう。

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-latest]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-latest
        experimental: true

jobs.<job_id>.container

jobs.<job_id>.container を使用して、コンテナーを作成し、コンテナーをまだ指定していないジョブのステップを実行します。 スクリプトアクションとコンテナアクションの両方を使うステップがある場合、コンテナアクションは同じボリュームマウントを使用して、同じネットワーク上にある兄弟コンテナとして実行されます。

container を設定しない場合、ステップがコンテナーで実行するように構成されたアクションを参照しない限り、すべてのステップは runs-on で指定されたホスト上で直接実行されます。

例: コンテナー内でジョブを実行する

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

コンテナー イメージのみを指定する場合は、image キーワードを省略できます。

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:18

jobs.<job_id>.container.image

jobs.<job_id>.container.image を使用して、アクションを実行するコンテナーとして使用する Docker イメージを定義します。 値には、Docker Hub イメージ名またはレジストリ名を指定できます。

jobs.<job_id>.container.credentials

イメージのコンテナー レジストリでイメージをプルするための認証が必要な場合は、jobs.<job_id>.container.credentials を使って username と password の map を設定できます。 資格情報は、docker login コマンドに指定するのと同じ値です。

例: コンテナー レジストリの資格情報の定義

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

jobs.<job_id>.container.env を使用して、コンテナー内の環境変数の map を設定します。

jobs.<job_id>.container.ports

jobs.<job_id>.container.ports を使用して、コンテナーで公開するポートの array を設定します。

jobs.<job_id>.container.volumes

jobs.<job_id>.container.volumes を使用して、コンテナーで使用するボリュームの array を設定します。 volumes (ボリューム) を使用すると、サービス間で、または1つのジョブのステップ間でデータを共有できます。 指定できるのは、名前付きDockerボリューム、匿名Dockerボリューム、またはホスト上のバインドマウントです。

ボリュームを指定するには、次のソースパスとターゲットパスを指定してください。

<source>:<destinationPath>.

<source> は、ホスト マシン上のボリューム名または絶対パスであり、<destinationPath> は、コンテナー内の絶対パスです。

例: コンテナーにボリュームをマウントする

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

jobs.<job_id>.container.options を使用して、追加の Docker コンテナー リソース オプションを構成します。 オプションの一覧については、docker create のオプションに関するページを参照してください。

jobs.<job_id>.services

ワークフロー中のジョブのためのサービスコンテナをホストするために使われます。 サービスコンテナは、データベースやRedisのようなキャッシュサービスの作成に役立ちます。 ランナーは自動的にDockerネットワークを作成し、サービスコンテナのライフサイクルを管理します。

コンテナを実行するようにジョブを設定した場合、あるいはステップがコンテナアクションを使う場合は、サービスもしくはアクションにアクセスするためにポートをマップする必要はありません。 Dockerは自動的に、同じDockerのユーザ定義ブリッジネットワーク上のコンテナ間のすべてのポートを公開します。 サービスコンテナは、ホスト名で直接参照できます。 ホスト名は自動的に、ワークフロー中のサービスに設定したラベル名にマップされます。

ランナーマシン上で直接実行されるようにジョブを設定し、ステップがコンテナアクションを使わないのであれば、必要なDockerサービスコンテナのポートはDockerホスト（ランナーマシン）にマップしなければなりません サービスコンテナには、localhostとマップされたポートを使ってアクセスできます。

ネットワーク サービス コンテナー間の違いについて詳しくは、「Docker サービス コンテナーとの通信」をご覧ください。

例: localhost の使用

この例では、nginxとredisという2つのサービスを作成します。 コンテナー ポートを指定したがホスト ポートを指定しなかった場合、コンテナー ポートはホスト上の空きポートにランダムに割り当てられます。 GitHub は、 ${{job.services.<service_name>.ports}} コンテキストで割り当てられたホスト ポートを設定します。 この例では、 ${{ job.services.nginx.ports['80'] }} と ${{ job.services.redis.ports['6379'] }} コンテキストを使用して、サービス ホスト ポートにアクセスできます。

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map random free TCP port on Docker host to port 6379 on redis container
    ports:
      - 6379/tcp
steps:
  - run: |
      echo "Redis available on 127.0.0.1:${{ job.services.redis.ports['6379'] }}"
      echo "Nginx available on 127.0.0.1:${{ job.services.nginx.ports['80'] }}"

jobs.<job_id>.services.<service_id>.image

アクションを実行するサービスコンテナとして使用するDockerイメージ。 値には、Docker Hub イメージ名またはレジストリ名を指定できます。

jobs.<job_id>.services.<service_id>.image に空の文字列が割り当てられている場合、サービスが開始されません。 これを使用して次の例と同様な条件付きサービスを設定できます。

services:
  nginx:
    image: ${{ options.nginx == true && 'nginx' || '' }}

jobs.<job_id>.services.<service_id>.credentials

イメージのコンテナー レジストリでイメージをプルするための認証が必要な場合は、jobs.<job_id>.container.credentials を使って username と password の map を設定できます。 資格情報は、docker login コマンドに指定するのと同じ値です。

jobs.<job_id>.services.<service_id>.credentials の例

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

サービス コンテナーで環境変数の map を設定します。

jobs.<job_id>.services.<service_id>.ports

サービス コンテナーで公開するポートの array を設定します。

jobs.<job_id>.services.<service_id>.volumes

使うサービス コンテナーにボリュームの array を設定します。 volumes (ボリューム) を使用すると、サービス間で、または1つのジョブのステップ間でデータを共有できます。 指定できるのは、名前付きDockerボリューム、匿名Dockerボリューム、またはホスト上のバインドマウントです。

ボリュームを指定するには、次のソースパスとターゲットパスを指定してください。

<source>:<destinationPath>。

<source> は、ホスト マシン上のボリューム名または絶対パスであり、<destinationPath> は、コンテナー内の絶対パスです。

jobs.<job_id>.services.<service_id>.volumes の例

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

追加のDockerコンテナリソースのオプション。 オプションの一覧については、docker create のオプションに関するページを参照してください。

jobs.<job_id>.services.<service_id>.command

Docker イメージの既定のコマンド (CMD) をオーバーライドします。 値は、 docker create コマンドのイメージ名の後に引数として渡されます。 entrypointも指定した場合、commandはそのエントリ ポイントに引数を提供します。

jobs.<job_id>.services.<service_id>.command の例

services:
  mysql:
    image: mysql:8
    command: --sql_mode=STRICT_TRANS_TABLES --max_allowed_packet=512M
    env:
      MYSQL_ROOT_PASSWORD: test
    ports:
      - 3306:3306

jobs.<job_id>.services.<service_id>.entrypoint

Docker イメージの既定の ENTRYPOINTをオーバーライドします。 この値は、実行する実行可能ファイルを定義する 1 つの文字列です。 これは、イメージのエントリポイントを完全に置き換える必要がある場合に使用します。 entrypointとcommandを組み合わせて、カスタム エントリポイントに引数を渡すことができます。

jobs.<job_id>.services.<service_id>.entrypoint の例

services:
  etcd:
    image: quay.io/coreos/etcd:v3.5.17
    entrypoint: etcd
    command: >-
      --listen-client-urls http://0.0.0.0:2379
      --advertise-client-urls http://0.0.0.0:2379
    ports:
      - 2379:2379

jobs.<job_id>.uses

ジョブとして実行する再利用可能なワークフロー ファイルの場所とバージョン。 次のいずれかの構文を使用します。

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

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

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

jobs.<job_id>.uses の例

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

詳しくは、「ワークフローを再利用する」をご覧ください。

jobs.<job_id>.with

ジョブを使って再利用可能なワークフローを呼び出す場合は、with を使って、呼び出し対象のワークフローに渡される入力のマップを指定することができます。

渡す入力は、呼び出し対象のワークフローで定義されている入力仕様と一致する必要があります。

jobs.<job_id>.steps[*].with とは異なり、jobs.<job_id>.withで渡した入力は、呼び出されたワークフローでは環境変数として利用できません。 代わりに、inputs コンテキストを使って入力を参照できます。

jobs.<job_id>.with の例

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    with:
      username: mona

jobs.<job_id>.with.<input_id>

入力の文字列識別子と入力の値で構成されるペア。 識別子は、呼び出し対象のワークフローで on.workflow_call.inputs.<inputs_id> によって定義された入力の名前と一致する必要があります。 値のデータ型は、呼び出し対象のワークフローで on.workflow_call.inputs.<input_id>.type によって定義された型と一致する必要があります。

使用できる式コンテキスト: github と needs。

jobs.<job_id>.secrets

ジョブを使って再利用可能なワークフローを呼び出す場合は、secrets を使用して、呼び出し対象のワークフローに渡されるシークレットのマップを指定することができます。

渡すシークレットは、呼び出し対象のワークフローで定義されている名前と一致する必要があります。

jobs.<job_id>.secrets の例

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    secrets:
      access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

jobs.<job_id>.secrets.inherit

inherit キーワードは、呼び出し元ワークフローのすべてのシークレットを呼び出し対象のワークフローに渡すために使います。 これには、呼び出し元ワークフローからアクセスできるすべてのシークレット (つまりOrganization、リポジトリ、環境のシークレット) が含まれます。 inherit キーワードを使って、同じ Organization 内のリポジトリ間、または同じ Enterprise 内の Organization 間でシークレットを渡すことができます。

jobs.<job_id>.secrets.inherit の例

on:
  workflow_dispatch:

jobs:
  pass-secrets-to-workflow:
    uses: ./.github/workflows/called-workflow.yml
    secrets: inherit

on:
  workflow_call:

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
      - name: Use a repo or org secret from the calling workflow.
        run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }}

jobs.<job_id>.secrets.<secret_id>

シークレットの文字列識別子とシークレットの値で構成されるペア。 識別子は、呼び出し対象のワークフローで on.workflow_call.secrets.<secret_id> によって定義されたシークレットの名前と一致する必要があります。

使用できる式コンテキスト: github、needs、secrets。

フィルター パターンの早見表

特別なキャラクタをパス、ブランチ、タグフィルタで利用できます。

• *: 0 個以上の文字と一致しますが、/ 文字とは一致しません。 たとえば、Octo* は Octocat と一致します。
• **: 0 個以上の任意の文字と一致します。
• ?: 直前の文字と0個または1個一致します。
• +: 1 個以上の直前の文字と一致します。
• [] 括弧内に一覧表示されているか、範囲に含まれている 1 つの英数字と一致します。 範囲には、a-z、A-Z、0-9 のみを含めることができます。 たとえば、範囲 [0-9a-z] は任意の数字または小文字と一致します。 たとえば、[CB]at は Cat またはBat と、[1-2]00 は 100 および 200 と一致します。
• !: パターンの先頭に置くと、前の肯定のパターンを否定にします。 先頭のキャラクタではない場合は、特別な意味を持ちません。

文字 *、[、! は YAML の特殊文字です。 パターンを *、[、! で開始する場合は、パターンを引用符で囲む必要があります。 また、使用するフロー シーケンスに [ と ] の一方または両方を含むパターンがある場合は、パターンを引用符で囲む必要があります。

# Valid
paths:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
paths:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]

ブランチ、タグ、パスのフィルター構文について詳しくは、「on.<push>.<branches|tags>」、「on.<pull_request>.<branches|tags>」、「on.<push|pull_request>.paths」をご覧ください。

ブランチやタグにマッチするパターン

ファイルパスにマッチするパターン

パスパターンはパス全体にマッチしなければならず、リポジトリのルートを出発点とします。