注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
ワークフロー用の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
コンテキストを使ってシークレットを参照できます。
注意: 入れ子になった再利用可能なワークフローにシークレットを渡している場合、シークレットを渡すには、もう一度 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
コンテキストの入力を受け取ります。 詳細については、「コンテキスト」を参照してください。
注:
- ワークフローは、
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に必要な権限」を参照してください。 |
checks | チェック実行とチェック スイートを操作します。 たとえば、checks: write は、アクションによるチェック実行の作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
contents | リポジトリの内容を操作します。 たとえば、contents: read はアクションによるコミットの一覧表示を許可し、contents: write はアクションによるリリースの作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
deployments | デプロイを操作します。 たとえば、deployments: write は、アクションによる新しいデプロイの作成アクションを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
discussions | GitHub ディスカッションで作業します。 たとえば、discussions: write は、アクションがディスカッションを閉じるか削除することを許可します。 詳しくは、「ディスカッションでのGraphQL APIの利用」を参照してください。 |
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
checks: read|write|none
contents: read|write|none
deployments: read|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}'" 。 |
defaults.run.working-directory
working-directory
を使用してステップの shell
の作業ディレクトリを定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。
ヒント: ランナーにシェルを実行する前に、割り当てる working-directory
がランナーに存在することを確認してください。
concurrency
同じコンカレンシー グループを使うジョブまたはワークフローを一度に 1 つだけ実行するには、concurrency
を使います。 並行処理グループには、任意の文字列または式を使用できます。 この式に使用できるコンテキストは、github
、inputs
、vars
のみです。 式の詳細については、「ワークフローとアクションで式を評価する」を参照してください。
ジョブ レベルで concurrency
を指定することもできます。 詳細については、「jobs.<job_id>.concurrency
」を参照してください。
つまり、コンカレンシー グループには、最大 1 つの実行ジョブと 1 つの保留中のジョブが存在できることを意味します。 並行ジョブかワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中だと、キューイングされたジョブかワークフローは pending
になります。 同じコンカレンシー グループ内の既存の pending
ジョブまたはワークフロー (存在する場合) は取り消され、キューに登録された新規ジョブまたはワークフローがその代わりに使用されます。
同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、cancel-in-progress: true
を指定します。 同じコンカレンシー グループ内で現在実行中のジョブまたはワークフローを条件付きで取り消すには、許可されている式コンテキストのいずれかを含む式として cancel-in-progress
を指定 できます。
注:
- コンカレンシー グループ名では大文字と小文字が区別されません。 たとえば、
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 Enterprise Server 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に必要な権限」を参照してください。 |
checks | チェック実行とチェック スイートを操作します。 たとえば、checks: write は、アクションによるチェック実行の作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
contents | リポジトリの内容を操作します。 たとえば、contents: read はアクションによるコミットの一覧表示を許可し、contents: write はアクションによるリリースの作成を許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
deployments | デプロイを操作します。 たとえば、deployments: write は、アクションによる新しいデプロイの作成アクションを許可します。 詳しくは、「GitHub Appに必要な権限」を参照してください。 |
discussions | GitHub ディスカッションで作業します。 たとえば、discussions: write は、アクションがディスカッションを閉じるか削除することを許可します。 詳しくは、「ディスカッションでのGraphQL APIの利用」を参照してください。 |
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
checks: read|write|none
contents: read|write|none
deployments: read|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
という組織内にある場合のみ実行されます。 それ以外の場合、ジョブはスキップ済みとしてマーク されます。
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
を使って、ジョブを実行するマシンの種類を定義します。
-
宛先マシンは、セルフホステッド ランナーにすることができます。 - ランナーに割り当てられたラベル、またはそのグループ メンバーシップ、またはこれらの組み合わせに基づいてランナーをターゲットにすることができます。
-
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 ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
セルフホステッド ランナーの選択
ジョブにセルフホステッド ランナーを指定するには、ワークフロー ファイルでセルフホステッド ランナーのラベルを使って 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
例: プレフィックスを使用してランナー グループを区別する
たとえば、Organization 内に my-group
という名前のランナー グループがあり、Enterprise 内に my-group
という名前のランナー グループがある場合は、ワークフロー ファイルを更新して、org/my-group
または ent/my-group
を使用して 2 つを区別できます。
org/
の使用
runs-on:
group: org/my-group
labels: [ self-hosted, label-1 ]
ent/
の使用
runs-on:
group: ent/my-group
labels: [ self-hosted, label-1 ]
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
を指定 できます。
注:
- コンカレンシー グループ名では大文字と小文字が区別されません。 たとえば、
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}'" 。 |
jobs.<job_id>.defaults.run.working-directory
working-directory
を使用してステップの shell
の作業ディレクトリを定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。
ヒント: ランナーにシェルを実行する前に、割り当てる working-directory
がランナーに存在することを確認してください。
例: ジョブの既定の 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
例: 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
) は、ランナーにインストールされている必要があります。
終了コードとエラーアクションの環境設定
組み込みの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にホストされたランナーの「使用制限、支払い、管理」と、セルフホストされたランナーの使用制限の「自己ホスト ランナーの概要」を参照してください。
注意: ジョブが終了するか最大 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 Enterprise Server は、ランナーの可用性に応じて並列実行されるジョブの数を最大化します。 マトリックス内の変数の順序によって、ジョブが作成される順序が決まります。 定義する最初の変数は、ワークフローの実行で最初に作成されるジョブになります。 たとえば、上記のマトリックスでは、次の順序でジョブが作成されます。
{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 Enterprise Server ホスト ランナーとセルフホステッド ランナーの両方に適用されます。
定義した変数は、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 Enterprise Server によってキャンセルされます。 このプロパティでは、既定値が 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 Enterprise Server は、ランナーの可用性に応じて並列実行されるジョブの数を最大化します。 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
でもオーバーライドできます。
例: コンテナー内でジョブを実行する
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
オプション」を参照してください。
警告: --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 |