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 イベントでワークフローがトリガーされる場合、ラベルが作成、編集、または削除されるたびにワークフローが実行されます。 label イベントに created アクティビティの種類を指定すると、ワークフローはラベルの作成時に実行されますが、ラベルの編集または削除時には実行されません。

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/10 のように名前が releases/ で始まるブランチ (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/beta/3-alpha のように releases/**-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 を再び含めます。

次のワークフローは、否定のパターン !releases/**-alpha が肯定のパターンの後に続くため、releases/10 または releases/beta/mona を対象とする pull request の pull_request イベントで実行されますが、releases/10-alpha または releases/beta/3-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/beta/3-alpha のように名前が releases/**-alpha と一致するブランチ (refs/heads/releases/beta/3-alpha)
v2 という名前のタグ (refs/tags/v2)
v1.9 のように名前が v1. で始まるタグ (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/**-alpha が肯定パターンに従うため、releases/10 または releases/beta/mona へのプッシュで実行され、releases/10-alpha または releases/beta/3-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フィルタを使用します。

Note

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の比較

Note

1,000 以上のコミットをプッシュする場合、あるいは GitHub がタイムアウトのために diff を生成できない場合、そのワークフローは常に実行されます。

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

GitHubはプッシュに対してはツードットdiff、Pull Requestに対してはスリードットdiffを使って変更されたファイルのリストを生成します。

pull request: スリードット diff は、トピックブランチの最新バージョンとトピックブランチがベースブランチと最後に同期されたコミットとの比較です。
既存のブランチへのプッシュ: ツードット diff は、ヘッド SHA とベース SHA を互いに直接比較します。
新しいブランチへのプッシュ: プッシュされた最も深いコミットの先祖の親に対するツードット diff です。

diff は 300 個のファイルに制限されます。フィルターによって返された最初の 300 個のファイルに一致しないファイルが変更された場合、ワークフローは実行されません。ワークフローが自動的に実行されるように、より具体的なフィルターを作成する必要がある場合があります。

詳しくは、「プルリクエスト中でのブランチの比較について」を参照してください。

`on.schedule`

on.schedule を使用すると、ワークフローの時間スケジュールを定義できます。ワークフローを特定の UTC 時刻に実行するように、POSIX cron 構文でスケジュールすることができます。スケジュールしたワークフローは、デフォルトまたはベースブランチの直近のコミットで実行されます。スケジュールされたワークフローを実行できる最短の間隔は、5 分ごとに 1 回です。

この例では、ワークフローは毎日UTCの5:30と17:30にトリガーされます。

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

1 つのワークフローを、複数の schedule イベントでトリガーできます。 github.event.schedule のコンテキストを使用して、ワークフローをトリガーしたスケジュールイベントにアクセスできます。この例では、毎週月曜日から木曜日の 5 時 30 分 (UTC) にワークフローが実行されますが、月曜日と水曜日の Not on Monday or Wednesday 手順はスキップされます。

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 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"

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

`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 が定義されています。これらは、どちらも my_job というジョブから job_output1 と job_output2 という出力にマップされます。

`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 コンテキストを使ってシークレットを参照できます。

Note

入れ子になった再利用可能なワークフローにシークレットを渡している場合、シークレットを渡すには、もう一度 jobs.<job_id>.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　のワークフロー構文」を参照してください。

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

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

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

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

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

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

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

たとえば、次のトリガーを持つワークフローは、名前が releases/10 または releases/beta/mona で始まるブランチで Build という名前のワークフローが稼働している場合にのみ実行されますが、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 コンテキストの入力を受け取ります。詳細については、「コンテキスト」を参照してください。

Note

ワークフローは、github.event.inputs コンテキスト内の入力も受け取ります。 inputs コンテキストと github.event.inputs コンテキストの情報ですが、inputs コンテキストではブール値が文字列に変換されず、ブール値として保持されます。 choice 型は文字列に解決され、1 つの選択可能なオプションです。
inputs の最上位レベルのプロパティの最大数は 10 です。
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 に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追加または削除することで、必要最小限のアクセスのみを許可することができます。詳しくは、「自動トークン認証」を参照してください。

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

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

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

権限	`GITHUB_TOKEN` を使ってアクションに許可する内容
`actions`	GitHub Actions を操作します。たとえば、`actions: write` は、アクションによるワークフロー実行の取り消しを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`attestations`	構成証明の認証作業たとえば、 `attestations: write` ビルドの成果物構成証明を生成するアクションが許可されます。詳細については、「アーティファクトの構成証明を使用して構築の実績を確立する」を参照してください
`checks`	チェック実行とチェックスイートを操作します。たとえば、`checks: write` は、アクションによるチェック実行の作成を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`contents`	リポジトリの内容を操作します。たとえば、`contents: read` はアクションによるコミットの一覧表示を許可し、`contents: write` はアクションによるリリースの作成を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`deployments`	デプロイを操作します。たとえば、`deployments: write` は、アクションによる新しいデプロイの作成アクションを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`discussions`	GitHub ディスカッションで作業します。たとえば、`discussions: write` は、アクションがディスカッションを閉じるか削除することを許可します。詳しくは、「ディスカッションでのGraphQL APIの利用」を参照してください。
`id-token`	OpenID Connect (OIDC) トークンをフェッチします。これには `id-token: write` が必要です。詳細については、「OpenID Connect を使ったセキュリティ強化について」を参照してください
`issues`	問題に取り組みます。たとえば、`issues: write` は、アクションがイシューにコメントを追加することを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`packages`	GitHub Packages を操作します。たとえば、`packages: write` は、アクションによる GitHub Packages でのパッケージのアップロードと発行を許可します。詳しくは、「GitHub Packagesの権限について」を参照してください。
`pages`	GitHub Pages を操作します。たとえば、`pages: write` は、アクションによる GitHub Pages のビルドの要求を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`pull-requests`	pull request を操作します。たとえば、`pull-requests: write` は、アクションによる pull request へのラベルの追加を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`repository-projects`	GitHub プロジェクト (クラシック) を操作します。たとえば、`repository-projects: write` は、アクションによるプロジェクト (クラシック) への列の追加を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`security-events`	GitHub コードスキャンと Dependabot アラートを操作します。たとえば、`security-events: read` はアクションによるリポジトリの Dependabot アラートの一覧表示を許可し、`security-events: write` はアクションによるコードスキャンアラートの状態の更新を許可します。詳しくは、「GitHub Apps に必要なアクセス許可」の「'コードスキャンアラート' のリポジトリのアクセス許可」と「'Dependabot アラート' のリポジトリのアクセス許可」を参照してください。
`statuses`	コミットの状態を操作します。たとえば、`statuses:read` は、アクションが特定の参照のコミット状態を一覧表示することを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。

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

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

permissions:
  actions: read|write|none
  attestations: read|write|none
  checks: 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
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

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

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

permissions: read-all

permissions: write-all

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

permissions: {}

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

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。この動作の例外としては、管理者ユーザーが GitHub Actions の設定で [Send write tokens to workflows from pull requests](pull request からワークフローに書き込みトークンを送信する) を選択している場合があります。詳しくは、「リポジトリの GitHub Actions の設定を管理する」を参照してください。

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

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

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

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

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

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

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

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

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

`defaults.run.shell`

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

サポートされているプラットフォーム	`shell` パラメーター	説明	内部で実行されるコマンド
Linux/macOS	unspecified	Windows 以外のプラットフォームの既定のシェル。これにより、`bash` を明示的に指定した場合とは異なるコマンドが実行されることに注意してください。 `bash` がパスに見つからない場合、これは `sh` のように扱われます。	`bash -e {0}`
すべて	`bash`	`sh` へのフォールバックが設定された、Windows 以外のプラットフォームの既定のシェル。 Windowsでbashシェルを指定すると、Windows用Gitに含まれるbashシェルが使用されます。	`bash --noprofile --norc -eo pipefail {0}`
すべて	`pwsh`	PowerShell Coreです。 GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。	`pwsh -command ". '{0}'"`
すべて	`python`	Pythonのコマンドを実行します。	`python {0}`
Linux/macOS	`sh`	Windows 以外のプラットフォームにおいて、シェルが提供されておらず、パスで `bash` が見つからなかった場合のフォールバック動作。	`sh -e {0}`
Windows	`cmd`	GitHub によってスクリプト名に拡張子 `.cmd` が追加され、`{0}` が置き換えられます。	`%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`。
Windows	`pwsh`	これはWindowsで使われるデフォルトのシェルです。 PowerShell Coreです。 GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。セルフホステッド Windows ランナーに PowerShell Core がインストールされていない場合は、代わりに PowerShell Desktop が使われます。	`pwsh -command ". '{0}'"`。
Windows	`powershell`	PowerShell Desktop. GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。	`powershell -command ". '{0}'"`。

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

`defaults.run.working-directory`

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

ヒント: ランナーにシェルを実行する前に、割り当てる working-directory がランナーに存在することを確認してください。

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

`concurrency`

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

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

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

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

Note

コンカレンシーグループ名では大文字と小文字が区別されません。たとえば、prod と Prod は同じコンカレンシーグループとして扱われます。
コンカレンシーグループを使用したジョブまたはワークフローでは、実行の順序付けは保証されません。同じコンカレンシーグループ内のジョブまたはワークフローは、任意の順序で処理されます。

例：コンカレンシーとデフォルトビヘイビアーの使用

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

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

コンカレンシーを使用して進行状況のジョブをキャンセルするか、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`

ワークフロー実行は、既定で並列実行される 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 に異なる権限のセットを構成できます。または、ワークフロー内のすべてのジョブの権限を指定することもできます。ワークフローレベルでのアクセス許可の定義については、permissions を参照してください。

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

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

権限	`GITHUB_TOKEN` を使ってアクションに許可する内容
`actions`	GitHub Actions を操作します。たとえば、`actions: write` は、アクションによるワークフロー実行の取り消しを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`attestations`	構成証明の認証作業たとえば、 `attestations: write` ビルドの成果物構成証明を生成するアクションが許可されます。詳細については、「アーティファクトの構成証明を使用して構築の実績を確立する」を参照してください
`checks`	チェック実行とチェックスイートを操作します。たとえば、`checks: write` は、アクションによるチェック実行の作成を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`contents`	リポジトリの内容を操作します。たとえば、`contents: read` はアクションによるコミットの一覧表示を許可し、`contents: write` はアクションによるリリースの作成を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`deployments`	デプロイを操作します。たとえば、`deployments: write` は、アクションによる新しいデプロイの作成アクションを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`discussions`	GitHub ディスカッションで作業します。たとえば、`discussions: write` は、アクションがディスカッションを閉じるか削除することを許可します。詳しくは、「ディスカッションでのGraphQL APIの利用」を参照してください。
`id-token`	OpenID Connect (OIDC) トークンをフェッチします。これには `id-token: write` が必要です。詳細については、「OpenID Connect を使ったセキュリティ強化について」を参照してください
`issues`	問題に取り組みます。たとえば、`issues: write` は、アクションがイシューにコメントを追加することを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`packages`	GitHub Packages を操作します。たとえば、`packages: write` は、アクションによる GitHub Packages でのパッケージのアップロードと発行を許可します。詳しくは、「GitHub Packagesの権限について」を参照してください。
`pages`	GitHub Pages を操作します。たとえば、`pages: write` は、アクションによる GitHub Pages のビルドの要求を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`pull-requests`	pull request を操作します。たとえば、`pull-requests: write` は、アクションによる pull request へのラベルの追加を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`repository-projects`	GitHub プロジェクト (クラシック) を操作します。たとえば、`repository-projects: write` は、アクションによるプロジェクト (クラシック) への列の追加を許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。
`security-events`	GitHub コードスキャンと Dependabot アラートを操作します。たとえば、`security-events: read` はアクションによるリポジトリの Dependabot アラートの一覧表示を許可し、`security-events: write` はアクションによるコードスキャンアラートの状態の更新を許可します。詳しくは、「GitHub Apps に必要なアクセス許可」の「'コードスキャンアラート' のリポジトリのアクセス許可」と「'Dependabot アラート' のリポジトリのアクセス許可」を参照してください。
`statuses`	コミットの状態を操作します。たとえば、`statuses:read` は、アクションが特定の参照のコミット状態を一覧表示することを許可します。詳しくは、「GitHub Appに必要な権限」を参照してください。

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

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

permissions:
  actions: read|write|none
  attestations: read|write|none
  checks: 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
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

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

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

permissions: read-all

permissions: write-all

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

permissions: {}

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

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。この動作の例外としては、管理者ユーザーが GitHub Actions の設定で [Send write tokens to workflows from pull requests](pull request からワークフローに書き込みトークンを送信する) を選択している場合があります。詳しくは、「リポジトリの 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@v5

`jobs.<job_id>.needs`

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

例: 依存ジョブの成功が必要である

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

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

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

job1
job2
job3

例: 依存ジョブの成功は必要ではない

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

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

`jobs.<job_id>.if`

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

注: jobs.<job_id>.if 条件は、jobs.<job_id>.strategy.matrix が適用される前に評価されます。

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

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

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

詳しくは、「ワークフローとアクションで式を評価する」をご覧ください。

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

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

YAML

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

`jobs.<job_id>.runs-on`

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

宛先マシンには、GitHubホステッドランナー、より大きなランナー、またはセルフホステッドランナーのいずれかを指定できます。 - ランナーに割り当てられたラベル、またはそのグループメンバーシップ、またはこれらの組み合わせに基づいてランナーをターゲットにすることができます。

runs-on は次として指定できます。
- 1 つの文字列
- 文字列を含む 1 つの変数
- 文字列の配列、文字列を含む変数、または両方の組み合わせ
- group または labels キーを使用する key: value ペア
文字列または変数の配列を指定すると、指定された 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 を使います。

注: 引用符は、self-hosted のような単純な文字列に関しては必須ではありませんが、 "${{ inputs.chosen-os }}" などの表現には必要です。

GitHub ホステッドランナーの選択

GitHub ホステッドランナーを使うと、各ジョブは runs-on で指定したランナーイメージの新しいインスタンスで実行されます。

GitHub ホステッドランナーを使用している場合の runs-on の値は、ランナーラベルまたはランナーグループの名前が指定されます。標準の GitHub ホステッドランナーのラベルを次の表に示します。

詳しくは、「GitHub ホステッドランナーの概要」を参照してください。

パブリックリポジトリの標準の GitHub でホストされたランナー

パブリックリポジトリの場合、次の表に示すワークフローラベルを使用するジョブは、関連付けられた仕様を持つ仮想マシンで実行されます。パブリックリポジトリでのこれらのランナーの使用は無料で無制限です。

仮想マシン	プロセッサ (CPU)	メモリ(RAM)	ストレージ (SSD)	ワークフローラベル
Linux	4	16 GB	14 GB	`ubuntu-latest`、`ubuntu-24.04`、`ubuntu-22.04`、`ubuntu-20.04`
Windows	4	16 GB	14 GB	`windows-latest`、`windows-2022`、`windows-2019`
macOS	3	14 GB	14 GB	`macos-12`
macOS	4	14 GB	14 GB	`macos-13`
macOS	3 (M1)	7 GB	14 GB	`macos-latest`、`macos-14`、`macos-15`［パブリックプレビュー］

プライベートリポジトリの標準の GitHub でホストされたランナー

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

仮想マシン	プロセッサ (CPU)	メモリ(RAM)	ストレージ (SSD)	ワークフローラベル
Linux	2	7 GB	14 GB	`ubuntu-latest`、`ubuntu-24.04`、`ubuntu-22.04`、`ubuntu-20.04`
Windows	2	7 GB	14 GB	`windows-latest`、`windows-2022`、`windows-2019`
macOS	3	14 GB	14 GB	`macos-12`
macOS	4	14 GB	14 GB	`macos-13`
macOS	3 (M1)	7 GB	14 GB	`macos-latest`、`macos-14`、`macos-15`［パブリックプレビュー］

標準の GitHub ホステッドランナーに加えて、GitHub では、GitHub Team プランとGitHub Enterprise Cloud プランのお客様に、より多くのコアとディスク領域、GPU 搭載マシン、ARM 搭載マシンなどの高度な機能を備えたさまざまなマネージド仮想マシンを用意しています。詳しくは、「より大きなランナーの概要」を参照してください。

Note

-latest ランナーイメージは、GitHub が提供する最新の安定したイメージであり、オペレーティングシステムベンダーから入手できるオペレーティングシステムの最新バージョンではない可能性があります。

Warning

ベータ版および非推奨のイメージは、"現状のまま"、"保証なし"、"利用可能な状態" で提供され、サービスレベルアグリーメントと保証から除外されます。ベータ版のイメージは、カスタマーサポートでカバーされない場合があります。

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

runs-on: ubuntu-latest

詳しくは、「GitHub ホステッドランナーの使用」を参照してください。

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

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

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

Action-runner-controller は複数のラベルには対応していません。また、self-hosted ラベルにも対応していない点にご注意ください。

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

runs-on: [self-hosted, linux]

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

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

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

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

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

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

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

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

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

この例では、ubuntu-runners というランナーグループに、ラベル ubuntu-20.04-16core も割り当てられている Ubuntu ランナーが設定されています。 runs-on キーは group と labels を組み合わせて、ラベルが一致するグループ内の使用可能な任意のランナーにジョブがルーティングされるようにします。

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

`jobs.<job_id>.environment`

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

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

Note

環境を参照するジョブがランナーに送られる前に、その環境のすべてのデプロイ保護ルールをパスしなければなりません。詳しくは、「デプロイに環境の使用」を参照してください。

例: 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 }}

`jobs.<job_id>.concurrency`

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

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

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

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

Note

コンカレンシーグループ名では大文字と小文字が区別されません。たとえば、prod と Prod は同じコンカレンシーグループとして扱われます。
コンカレンシーグループを使用したジョブまたはワークフローでは、実行の順序付けは保証されません。同じコンカレンシーグループ内のジョブまたはワークフローは、任意の順序で処理されます。

例：コンカレンシーとデフォルトビヘイビアーの使用

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

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

コンカレンシーを使用して進行状況のジョブをキャンセルするか、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>.outputs`

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

出力は Unicode 文字列であり、最大 1 MB となります。ワークフロー実行内のすべての出力の合計は、最大 50 MB です。

表現が含まれているジョブの出力は、各ジョブの終了時にランナー上で評価されます。シークレットを含む出力はランナー上で編集され、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 を使用して、ジョブ内のすべての run ステップに既定の shell と working-directory を指定します。

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

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

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

`jobs.<job_id>.defaults.run.shell`

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

サポートされているプラットフォーム	`shell` パラメーター	説明	内部で実行されるコマンド
Linux/macOS	unspecified	Windows 以外のプラットフォームの既定のシェル。これにより、`bash` を明示的に指定した場合とは異なるコマンドが実行されることに注意してください。 `bash` がパスに見つからない場合、これは `sh` のように扱われます。	`bash -e {0}`
すべて	`bash`	`sh` へのフォールバックが設定された、Windows 以外のプラットフォームの既定のシェル。 Windowsでbashシェルを指定すると、Windows用Gitに含まれるbashシェルが使用されます。	`bash --noprofile --norc -eo pipefail {0}`
すべて	`pwsh`	PowerShell Coreです。 GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。	`pwsh -command ". '{0}'"`
すべて	`python`	Pythonのコマンドを実行します。	`python {0}`
Linux/macOS	`sh`	Windows 以外のプラットフォームにおいて、シェルが提供されておらず、パスで `bash` が見つからなかった場合のフォールバック動作。	`sh -e {0}`
Windows	`cmd`	GitHub によってスクリプト名に拡張子 `.cmd` が追加され、`{0}` が置き換えられます。	`%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`。
Windows	`pwsh`	これはWindowsで使われるデフォルトのシェルです。 PowerShell Coreです。 GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。セルフホステッド Windows ランナーに PowerShell Core がインストールされていない場合は、代わりに PowerShell Desktop が使われます。	`pwsh -command ". '{0}'"`。
Windows	`powershell`	PowerShell Desktop. GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。	`powershell -command ". '{0}'"`。

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

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

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

ヒント: ランナーにシェルを実行する前に、割り当てる working-directory がランナーに存在することを確認してください。

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

例: ジョブの既定の `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/') }}

詳しくは、「ワークフローとアクションで式を評価する」をご覧ください。

例: コンテキストの使用

このステップは、イベントの種類が 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@v4
  # Reference a specific version
  - uses: actions/checkout@v4.2.0
  # Reference a branch
  - uses: actions/checkout@main

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

{owner}/{repo}@{ref}

パブリック GitHub リポジトリのブランチ、参照、または 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}

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

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

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

./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@v4
      # 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 Packages Container 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

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

ワークフローはプライベートリポジトリをチェックアウトし、アクションをローカルで参照する必要があります。 personal access token を生成し、シークレットとしてトークンを追加します。詳細については、「個人用アクセストークンを管理する」および「GitHub Actions でのシークレットの使用」を参照してください。

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

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        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

あるいは、personal access token の所有者が去った後でもワークフローを実行し続けられるよう、personal access token の代わりに GitHub App を使います。詳しくは、「GitHub Actions ワークフローで GitHub App を使用して認証済み 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 キーワードで指定されたコマンドを含む一時ファイルが実行されます。

サポートされているプラットフォーム	`shell` パラメーター	説明	内部で実行されるコマンド
Linux/macOS	unspecified	Windows 以外のプラットフォームの既定のシェル。これにより、`bash` を明示的に指定した場合とは異なるコマンドが実行されることに注意してください。 `bash` がパスに見つからない場合、これは `sh` のように扱われます。	`bash -e {0}`
すべて	`bash`	`sh` へのフォールバックが設定された、Windows 以外のプラットフォームの既定のシェル。 Windowsでbashシェルを指定すると、Windows用Gitに含まれるbashシェルが使用されます。	`bash --noprofile --norc -eo pipefail {0}`
すべて	`pwsh`	PowerShell Coreです。 GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。	`pwsh -command ". '{0}'"`
すべて	`python`	Pythonのコマンドを実行します。	`python {0}`
Linux/macOS	`sh`	Windows 以外のプラットフォームにおいて、シェルが提供されておらず、パスで `bash` が見つからなかった場合のフォールバック動作。	`sh -e {0}`
Windows	`cmd`	GitHub によってスクリプト名に拡張子 `.cmd` が追加され、`{0}` が置き換えられます。	`%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}""`。
Windows	`pwsh`	これはWindowsで使われるデフォルトのシェルです。 PowerShell Coreです。 GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。セルフホステッド Windows ランナーに PowerShell Core がインストールされていない場合は、代わりに PowerShell Desktop が使われます。	`pwsh -command ". '{0}'"`。
Windows	`powershell`	PowerShell Desktop. GitHub によってスクリプト名に拡張子 `.ps1` が追加されます。	`powershell -command ". '{0}'"`。

または、ジョブのすべての 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'])

カスタムシェル

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

次に例を示します。

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

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

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

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

組み込みのshellキーワードについては、GitHubがホストする実行環境で以下のデフォルトが提供されます。シェルスクリプトを実行する際には、以下のガイドラインを使ってください。

bash/sh:
- 既定では、フェイルファスト動作は、sh と bash の両方に set -e を使用して強制されます。 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` の例

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

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

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

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

Dockerfile 内の Docker の ENTRYPOINT をオーバーライドするか、まだ指定されていない場合は設定します。 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されるまでにステップが実行できる最大の分数。

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

`jobs.<job_id>.timeout-minutes`

GitHubで自動的にキャンセルされるまでジョブを実行する最長時間 (分)。デフォルト: 360

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

Note

ジョブが終了するか最大 24 時間後に、GITHUB_TOKEN の有効期限が切れます。セルフホステッドランナーでは、ジョブのタイムアウトが 24 時間を超える場合、トークンが制限要因になる可能性があります。 GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。

`jobs.<job_id>.strategy`

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

`jobs.<job_id>.strategy.matrix`

jobs.<job_id>.strategy.matrix を使用して、さまざまなジョブの設定のマトリックスを定義します。マトリックス内で、1 つ以上の変数と、それに続く値の配列を定義します。たとえば、次のマトリックスには、値 [10, 12, 14] を伴う version という名前の変数と、値 [ubuntu-latest, windows-latest] を伴う os という名前の変数があります。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

ジョブは、変数の可能な組み合わせごとに実行されます。この例のワークフローでは 6 つのジョブが、os 変数と version 変数の組み合わせごとに 1 つずつ実行されます。

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

{version: 10, os: ubuntu-latest}
{version: 10, os: windows-latest}
{version: 12, os: ubuntu-latest}
{version: 12, os: windows-latest}
{version: 14, os: ubuntu-latest}
{version: 14, os: windows-latest}

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

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

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

単一の変数を指定して、1 次元のマトリックスを作成できます。

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

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v4
        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-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

マトリックス内の変数構成は、object の array になります。

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

このマトリックスでは、対応するコンテキストを持つ 4 つのジョブが生成されます。

- 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

例: コンテキストを使ったマトリックスの作成

コンテキストを使用してマトリックスを作成できます。コンテキストについて詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」をご覧ください。

たとえば、次のワークフローは repository_dispatch イベントをトリガーし、イベントペイロードからの情報を使用してマトリックスを構築します。次のようなペイロードを使用してリポジトリのディスパッチイベントが作成されると、マトリックス version 変数の値は [12, 14, 16] になります。 repository_dispatch トリガーについて詳しくは、「ワークフローをトリガーするイベント」をご覧ください。

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}

on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

`jobs.<job_id>.strategy.matrix.include`

jobs.<job_id>.strategy.matrix.include を使用して、既存のマトリックス構成を展開したり、新しい構成を追加したりします。 include の値は、オブジェクトのリストです。

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

たとえば、次のマトリックスを見てください。

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

これは、次のマトリックスの組み合わせを持つ 6 つのジョブとなります。

{fruit: apple, animal: cat, color: pink, shape: circle}
{fruit: apple, animal: dog, color: green, shape: circle}
{fruit: pear, animal: cat, color: pink}
{fruit: pear, animal: dog, color: green}
{fruit: banana}
{fruit: banana, animal: cat}

このロジックに従うと、次のようになります。

{color: green} は、元の組み合わせの一部を上書きせずに追加できるため、元のマトリックスの組み合わせすべてに追加されます。
{color: pink, animal: cat} は、animal: cat を含む元のマトリックスの組み合わせにのみ color:pink を追加します。これにより、前の include エントリによって追加された color: green が上書きされます。
{fruit: apple, shape: circle} は、fruit: apple を含む元のマトリックスの組み合わせにのみ shape: circle を追加します。
{fruit: banana} は、値を上書きせずに元のマトリックスの組み合わせに追加できないため、追加のマトリックスの組み合わせとして追加されます。
{fruit: banana, animal: cat} は、値を上書きせずに元のマトリックスの組み合わせに追加できないため、追加のマトリックスの組み合わせとして追加されます。この組み合わせは、元のマトリックスの組み合わせの 1 つではないため、{fruit: banana} マトリックスの組み合わせには追加されません。

例: 構成の展開

たとえば、次のワークフローでは、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@v4
        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`

マトリックスで定義されている特定の構成を削除するには、jobs.<job_id>.strategy.matrix.exclude を使用します。除外する構成は、それを除外するために部分一致である必要があるだけです。たとえば、次のワークフローでは 9 つのジョブが実行されます。12 個の構成ごとに 1 つのジョブで、{os: macos-latest, version: 12, environment: production} と一致する 1 つのジョブと、{os: windows-latest, version: 16} と一致する 2 つのジョブが除外されます。

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

注: すべての 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 は、ランナーの可用性に応じて並列実行されるジョブの数を最大化します。 matrix ジョブ戦略を使うとき、同時に実行できるジョブの最大数を設定するには、jobs.<job_id>.strategy.max-parallel を使います。

たとえば、次のワークフローでは、6 つのジョブすべてを一度に実行できるランナーがある場合でも、一度に最大 2 つのジョブを実行します。

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

`jobs.<job_id>.continue-on-error`

ジョブが失敗した時に、ワークフローの実行が失敗にならないようにします。 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`

注: ワークフローが Docker コンテナーアクション、ジョブコンテナーあるいはサービスコンテナーを使うなら、Linux のランナーを使う必要があります。

GitHubホストランナーを使うなら、Ubuntuランナーを使わなければなりません。
セルフホストランナーを使っているなら、ランナーとしてLinuxマシンを使い、Dockerをインストールしておかなければなりません。

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

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

注: コンテナー内の run ステップの既定のシェルは、bash ではなく sh です。これは、jobs.<job_id>.defaults.run でも jobs.<job_id>.steps[*].shell でもオーバーライドできます。

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

YAML

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 オプション」を参照してください。

警告: --network と --entrypoint オプションはサポートされていません。

`jobs.<job_id>.services`

注: ワークフローが Docker コンテナーアクション、ジョブコンテナーあるいはサービスコンテナーを使うなら、Linux のランナーを使う必要があります。

GitHubホストランナーを使うなら、Ubuntuランナーを使わなければなりません。
セルフホストランナーを使っているなら、ランナーとしてLinuxマシンを使い、Dockerをインストールしておかなければなりません。

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

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

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

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

例: 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 オプション」を参照してください。

Warning

--network オプションはサポートされていません。

`jobs.<job_id>.uses`

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

パブリックとプライベートリポジトリの再利用可能ワークフローの{owner}/{repo}/.github/workflows/{filename}@{ref}。
同じリポジトリ内の再利用可能なワークフローの ./.github/workflows/{filename}。

最初のオプションで、{ref} には、SHA、リリースタグ、またはブランチ名を指定できます。リリースタグとブランチの名前が同じ場合は、リリースタグがブランチの名前よりも優先されます。コミット SHA を使用することが、安定性とセキュリティにとって最も安全なオプションです。詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。

2 番目の構文オプションを ({owner}/{repo} および @{ref} なしで) 使用する場合、呼び出されたワークフローは呼び出し元ワークフローと同じコミットから取得されます。 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
  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」を参照してください。

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

パターン	説明	一致の例
`feature/*`	ワイルドカード `*` は任意の文字と一致しますが、スラッシュ (`/`) とは一致しません。	`feature/my-branch` `feature/your-branch`
`feature/**`	ワイルドカード `**` は、ブランチおよびタグ名のスラッシュ (`/`) を含む任意の文字と一致します。	`feature/beta-a/my-branch` `feature/your-branch` `feature/mona/the/octocat`
`main` `releases/mona-the-octocat`	ブランチあるいはタグ名に完全に一致したときにマッチします。	`main` `releases/mona-the-octocat`
`'*'`	スラッシュ (`/`) を含まないすべてのブランチおよびタグ名と一致します。 `` 文字は YAML の特殊文字です。パターンを `` で開始する場合は、引用符を使う必要があります。	`main` `releases`
`'**'`	すべてのブランチ及びタグ名にマッチします。これは、`branches` または `tags` フィルターを使わない場合の既定の動作です。	`all/the/branches` `every/tag`
`'*feature'`	`` 文字は YAML の特殊文字です。パターンを `` で開始する場合は、引用符を使う必要があります。	`mona-feature` `feature` `ver-10-feature`
`v2*`	`v2` で始まるブランチおよびタグ名と一致します。	`v2` `v2.0` `v2.9`
`v[12].[0-9]+.[0-9]+`	メジャーバージョンが 1 または 2 のすべてのセマンティックバージョニングブランチおよびタグと一致します。	`v1.10.1` `v2.0.0`

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

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

パターン	マッチの説明	一致の例
`'*'`	ワイルドカード `` は任意の文字と一致しますが、スラッシュ (`/`) とは一致しません。 `` 文字は YAML の特殊文字です。パターンを `*` で開始する場合は、引用符を使う必要があります。	`README.md` `server.rb`
`'*.jsx?'`	`?` 文字は 0 個または 1 個の直前の文字と一致します。	`page.js` `page.jsx`
`'**'`	ワイルドカード `**` は、スラッシュ (`/`) を含む任意の文字と一致します。これは、`path` フィルターを使わない場合の既定の動作です。	`all/the/files.md`
`'*.js'`	ワイルドカード `*` は任意の文字と一致しますが、スラッシュ (`/`) とは一致しません。リポジトリのルートにあるすべての `.js` ファイルと一致します。	`app.js` `index.js`
`'**.js'`	リポジトリにあるすべての `.js` ファイルと一致します。	`index.js` `js/index.js` `src/js/app.js`
`docs/*`	リポジトリのルートにある `docs` ディレクトリのルート内のすべてのファイル。	`docs/README.md` `docs/file.txt`
`docs/**`	リポジトリのルートにある `/docs` ディレクトリ内の任意のファイル。	`docs/README.md` `docs/mona/octocat.txt`
`docs/*/.md`	`docs` ディレクトリ内の任意の場所にある `.md` サフィックスが付いたファイル。	`docs/README.md` `docs/mona/hello-world.md` `docs/a/markdown/file.md`
`'/docs/'`	リポジトリの任意の場所にある `docs` ディレクトリ内の任意のファイル。	`docs/hello.md` `dir/docs/my-file.txt` `space/docs/plan/space.doc`
`'**/README.md'`	リポジトリ内にあるREADME.mdファイルにマッチします。	`README.md` `js/README.md`
`'*/src/**'`	リポジトリの任意の場所にある `src` サフィックスが付いたフォルダ内の任意のファイル。	`a/src/app.js` `my-src/code/js/app.js`
`'*/-post.md'`	リポジトリの任意の場所にあるサフィックス `-post.md` が付いたファイル。	`my-post.md` `path/their-post.md`
`'*/migrate-.sql'`	リポジトリの任意の場所にあるプレフィックス `migrate-` とサフィックス `.sql` が付いたファイル。	`migrate-10909.sql` `db/migrate-v1.0.sql` `db/sept/migrate-v1.sql`
`'*.md'` `'!README.md'`	感嘆符 (`!`) をパターンの前で使うと否定になります。あるファイルがあるパターンにマッチし、ファイル中でその後に定義されている否定パターンにマッチした場合、そのファイルは含まれません。	`hello.md` ［次の値に一致しない］ `README.md` `docs/hello.md`
`'.md'` `'!README.md'` `README`	パターンは順番にチェックされます。先行するパターンを否定するパターンで、ファイルパスが再度含まれるようになります。	`hello.md` `README.md` `README.doc`

GitHub Actions のワークフロー構文

この記事の内容

GitHub Actions　のワークフロー構文