注: 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 により、リポジトリのルートに相対的なワークフロー ファイル パスに設定されます。
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
の両方を定義すると、ワークフローは両方のフィルターが満たされた� �合にのみ実行されます。
branches
と branches-ignore
のキーワードは、複数のブランチ名に一致する文字 (*
、**
、+
、?
、!
など) を使用する glob パターンを受け入れます。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な� �合は、\
でこれらの各特殊文字をエスケープする必要があります。 glob パターンの詳細については、「フィルター パターンのチート シート」を参照してく� さい。
例: ブランチの包含
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/**'
例: ブランチの除外
パターンが branches-ignore
パターンと一致する� �合、ワークフローは実行されません。 branches
で定義されているパターンは、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
の両方を定義すると、ワークフローは両方のフィルターが満たされた� �合にのみ実行されます。
branches
、branches-ignore
、tags
、および tags-ignore
のキーワードは、複数のブランチまたはタグ名に一致する文字 (*
、**
、+
、?
、!
など) を使用する glob パターンを許容します。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な� �合は、\
でこれらの各特殊文字を エスケープ する必要があります。 glob パターンの詳細については、「フィルター パターンのチート シート」を参照してく� さい。
ブランチとタグを含める例
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
)beta/3-alpha
のように名前がreleases/**-alpha
と一致する ブランチ (refs/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
のフィルターの両方をワークフロー内の同じイベントで使うことはできません。
branches
/branches-ignore
と paths
の両方を定義すると、ワークフローは両方のフィルターが満たされた� �合にのみ実行されます。
paths
と paths-ignore
のキーワードは、複数のパス名と一致するために *
と **
のワイルドカード文字を使用する glob パターンを受け入れます。 詳細については、「フィルター パターンのチート シート」を参照してく� さい。
例: パスの包含
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
を使用します。
パターンを定義する� �序により、結果に違いが生じます:
- 肯定のマッチング パターンの後に否定のマッチング パターン(
!
のプレフィックスが付く) を定義すると、パスを除外します。 - 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、パスを再び含めます。
ファイルが 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の比較
注: 1,000 以上のコミットをプッシュする� �合、あるいは GitHub がタイ� アウトのために diff を生成できない� �合、そのワークフローは常に実行されます。
フィルターは、変更されたファイルを評価し、paths-ignore
または paths
のリストに対してファイルを実行することで、ワークフローを実行すべきか判断します。 ファイルが変更されていない� �合、ワークフローは実行されません。
GitHubはプッシュに対してはツードットdiff、Pull Requestに対してはスリードットdiffを使って変更されたファイルのリストを生成します。
- pull request: スリードット diff は、トピック ブランチの最新バージョンとトピック ブランチがベース ブランチと最後に同期されたコミットとの比較です。
- 既存のブランチへのプッシュ: ツードット diff は、ヘッド SHA とベース SHA を互いに直接比較します。
- 新しいブランチへのプッシュ: プッシュされた最も深いコミットの先祖の親に対するツードット diff です。
diff は 300 個のファイルに制限されます。 フィルターによって返された最初の 300 個のファイルに一致しないファイルが変更された� �合、ワークフローは実行されません。 ワークフローが自動的に実行されるように、より具体的なフィルターを作成する必要がある� �合があります。
詳細については、「pull request でのブランチの比較について」を参照してく� さい。
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_run.<branches|branches-ignore>
workflow_run
イベントを使用する� �合は、ワークフローをトリガーするためにトリガーするワークフローが稼働する必要があるブランチを指定できます。
branches
フィルターと branches-ignore
フィルターは、複数のブランチ名に一致する文字 (*
、**
、+
、?
など) を使用する glob パターンを受け入れます。!
名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な� �合は、\
でこれらの各特殊文字を エスケープ する必要があります。 glob パターンの詳細については、「フィルター パターンのチート シート」を参照してく� さい。
たとえば、次のトリガーを持つワークフローは、名前が 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.inputs
workflow_dispatch
イベントを使用すると、必要に応じてワークフローに渡される入力を指定できます。
トリガーされたワークフローは、github.event.inputs
コンテキストの入力を受け取ります。 詳細については、「コンテキスト」を参照してく� さい。
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
print_tags:
description: 'True to print to STDOUT'
required: true
tags:
description: 'Test scenario tags'
required: true
jobs:
print-tag:
runs-on: ubuntu-latest
if: ${{ github.event.inputs.print_tags == 'true' }}
steps:
- name: Print the input tag to STDOUT
run: echo The tags are ${{ github.event.inputs.tags }}
permissions
permissions
を使用して GITHUB_TOKEN
に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追� または削除することで、必要最小限のアクセスのみを許可することができます。 詳細については「ワークフローで認証する」を参照してく� さい。
permissions
は、最上位のキーとして、ワークフロー内のすべてのジョブに適用するか、または特定のジョブ内で使用できます。 特定のジョブ内に permissions
キーを追� すると、GITHUB_TOKEN
を使用するそのジョブ内のすべてのアクションと実行コマンドが、指定したアクセス権を取得します。 詳細については、「jobs.<job_id>.permissions
」を参照してく� さい。
利用できるスコープとアクセスの値は以下のとおりです。
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
に設定されます。
利用可能なすべてのスコープに対する読み取りあるいは書き込みアクセス権を定義するためには、以下の構文が使えます。
permissions: read-all|write-all
次の構文を使用して、使用可能なすべてのスコープのアクセス許可を無効にすることができます。
permissions: {}
``` `permissions` キーを使用して、フォークされたリポジトリの読み取り権限を追� および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で **[Send write tokens to workflows from pull requests]\(pull request からワークフローに書き込みトークンを送信する\)** を選択している� �合があります。 詳細については、「[リポジトリの GitHub Actions 設定の管理](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)」を参照してく� さい。
### 例: GITHUB_TOKEN にアクセス許可を割り当てる
この例では、ワークフロー内のすべてのジョブに適用される `GITHUB_TOKEN` に設定されているアクセス許可を示しています。 すべての権限に読み取りアクセスが付与されます。
```yaml
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:
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
concurrency
同じコンカレンシー グループを使うジョブまたはワークフローを一度に 1 つ� け実行するには、concurrency
を使います。 並行処理グループには、任意の文字列または式を使用できます。 この式には github
コンテキストのみを使用できます。 式の詳細については、「式」を参照してく� さい。
ジョブ レベルで concurrency
を指定することもできます。 詳細については、「jobs.<job_id>.concurrency
」を参照してく� さい。
並行ジョブかワークフローがキューに入っている� �合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中� と、キューイングされたジョブかワークフローは pending
になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、cancel-in-progress: true
を指定します。
並行性とデフォルトの動作の使用例
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
並行性を使って進行中のジョブもしくは実行をキャンセルする例
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
例: フォールバック値の使用
特定のイベントにのみ定義されるプロパティでグループ名を作成する� �合、フォールバック値を使用できます。 たとえば、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
jobs
ワークフロー実行は、既定で並列実行される 1 つ以上の jobs
で構成されます。 ジョブを� �番に実行するには、jobs.<job_id>.needs
キーワードを使用して他のジョブへの依存関係を定義できます。
各ジョブは、runs-on
で指定されたランナー環境で実行されます。
ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳細については、GitHub がホストするランナーの「使用量制限と課金」とセルフホステッド ランナーの使用制限の「セルフホステッド ランナーについて」
ワークフロー実行で実行されているジョブの一意識別子を見つける必要がある� �合は、GitHub Enterprise Server 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
を参照してく� さい。
利用できるスコープとアクセスの値は以下のとおりです。
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
に設定されます。
利用可能なすべてのスコープに対する読み取りあるいは書き込みアクセス権を定義するためには、以下の構文が使えます。
permissions: read-all|write-all
次の構文を使用して、使用可能なすべてのスコープのアクセス許可を無効にすることができます。
permissions: {}
``` `permissions` キーを使用して、フォークされたリポジトリの読み取り権限を追� および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で **[Send write tokens to workflows from pull requests]\(pull request からワークフローに書き込みトークンを送信する\)** を選択している� �合があります。 詳細については、「[リポジトリの GitHub Actions 設定の管理](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)」を参照してく� さい。
#### 例: 特定のジョブのアクセス許可の設定
この例は、`stale` という名前のジョブにのみ適用される `GITHUB_TOKEN` に設定されているアクセス許可を示しています。 書き込みアクセス権は、`issues` スコープと `pull-requests` スコープに対して付与されます。 他のすべてのスコープにはアクセスできません。
```yaml
jobs:
stale:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/stale@v4
jobs.<job_id>.needs
jobs.<job_id>.needs
を使って、このジョブの実行前に正常に完了する必要があるジョブを示します。 文字列型または文字列の配列です。 1つのジョブが失敗した� �合、失敗したジョブを続行するような条件式を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。 互いを必要とするジョブが実行に含まれていると、エラー時点以降、依存関係チェーン内のすべてのジョブにエラーが適用されます。
例: 依存ジョブの成功が必要である
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
条件文を使って、条件が満たされなければジョブを実行しないようにできます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。 このキーでサポートされているコンテキストについて詳しくは、「コンテキストの可用性」を参照してく� さい。
if
条件の中で式を使う際には、式構文 (${{ }}
)を省略できます。これは、GitHub が if
条件を式として自動的に評価するためです。 詳細については、「式」を参照してく� さい。
例: 特定のリポジトリに対してのみジョブを実行する
この例では 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@v2
- uses: actions/setup-node@v2
with:
node-version: '14'
- run: npm install -g bats
jobs.<job_id>.runs-on
jobs.<job_id>.runs-on
を使って、ジョブを実行するマシンの種類を定義します。
-
宛先マシンは、セルフホステッド ランナーにすることができます。
-
ランナーに割り当てられたラベルに基づいてランナーをターゲットにすることができます。
-
1 つの文字列として、または文字列の配列として
runs-on
を指定できます。 -
文字列の配列を指定すると、指定したすべての
runs-on
値に一致するすべてのランナーでワークフローが実行されます。 -
複数のマシンでワークフローを実行する� �合は、
jobs.<job_id>.strategy
を使います。
注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
GitHub ホステッド ランナーの選択
GitHub ホステッド ランナーを使うと、各ジョブは runs-on
で指定したランナー イメージの新しいインスタンスで実行されます。
利用可能なGitHubホストランナーの種類は以下のとおりです。
ランナー イメージ | YAML ワークフロー ラベル | メモ |
---|---|---|
Windows Server 2022 |
windows-latest または windows-2022
|
windows-latest ラベルは現在、Windows Server 2022 ランナー イメージを使用しています。
|
Windows Server 2019 |
windows-2019
|
|
Ubuntu 22.04 |
ubuntu-22.04
|
|
Ubuntu 20.04 |
ubuntu-latest または ubuntu-20.04
|
ubuntu-latest ラベルは現在、Ubuntu 22.04 ランナー イメージに移行中です。 移行中は、ラベルによって Ubuntu 20.04 と 22.04 のいずれかのランナー イメージが参照されることがあります。 詳しくは、こちらの GitHub ブログ記事をご覧く� さい。
|
Ubuntu 18.04 [非推奨] |
ubuntu-18.04
|
ubuntu-20.04 または ubuntu-22.04 に移行。 詳しくは、こちらの GitHub のブログ記事をご覧く� さい。
|
macOS Monterey 12 |
macos-12
|
|
macOS Big Sur 11 |
macos-latest または macos-11
|
macos-latest ラベルは現在、macOS Monterey 12 ランナー イメージに移行中です。 移行中は、ラベルによって macOS 11 と 12 のいずれかのランナー イメージが参照されることがあります。 詳しくは、こちらの GitHub ブログ記事をご覧く� さい。
|
macOS Catalina 10.15 [非推奨] |
macos-10.15
|
macOS-11 または macOS-12 に移行。 詳しくは、こちらの GitHub のブログ記事をご覧く� さい。
|
注: -latest
ランナー イメージは、GitHub が提供する最新の安定したイメージであり、オペレーティング システ� ベンダーから入手できるオペレーティング システ� の最新バージョンではない可能性があります。
警告: ベータ版および非推奨のイメージは、"現状のまま"、"保証なし"、"利用可能な状態" で提供され、サービス レベル アグリーメントと保証から除外されます。 ベータ版のイメージは、カスタマー サポートでカバーされない� �合があります。
例: オペレーティング システ� の指定
runs-on: ubuntu-latest
詳細については、「GitHub ホステッド ランナーの概要」を参照してく� さい。
セルフホステッド ランナーの選択
ジョブにセルフホステッド ランナーを指定するには、ワークフロー ファイルでセルフホステッド ランナーのラベルを使って runs-on
を設定します。
すべてのセルフホステッド ランナーに self-hosted
ラベルが含まれます。 このラベルのみを使うと、セルフホステッド ランナーが選ばれます。 オペレーティング システ� やアーキテクチャなど、特定の条件を満たすランナーを選ぶには、self-hosted
で始まり (リストの最初にこれを示す必要があります)、必要に応じて追� のラベルを含むラベルの配列を指定することをお勧めします。 ラベルの配列を指定すると、指定したラベルをすべて持つランナーのキューにジョブが入れられます。
self-hosted
ラベルは必� �ではありませんが、セルフホステッド ランナーを使う� �合は、自分のジョブから現在または将来の GitHub ホスト ランナーが意図せずに指定されないことを確実にするため、それを指定することを強くお勧めします。
例: ランナー選択のためのラベルの使用
runs-on: [self-hosted, linux]
詳細については、「セルフホステッド ランナーについて」と「ワークフローでのセルフホステッド ランナーの使用」を参照してく� さい。
jobs.<job_id>.environment
ジョブが参照する環境を定義するには、jobs.<job_id>.environment
を使います。 環境を参照するジョブがランナーに送られる前に、その環境のすべて保護ルールはパスしなければなりません。 詳細については、「デプロイに環境を使用する」を参照してく� さい。
環境 name
のみ、または name
と url
を含む環境オブジェクトという形式で環境を指定できます。 URL はデプロイ API の environment_url
にマップされます。 デプロイ API の詳細については、「デプロイ」を参照してく� さい。
例: 1 つの環境名を使う
environment: staging_environment
例: 環境名と URL を使う
environment:
name: production_environment
url: https://github.com
URL は式で指定できます。また、secrets
コンテキストを除く任意のコンテキストを使用できます。 式の詳細については、「式」を参照してく� さい。
例: 出力を URL として使う
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
jobs.<job_id>.concurrency
注: ジョブ レベルでコンカレンシーが指定されている� �合、ジョブの� �序は保証されないか、互いに 5 分以内にそのキューを実行します。
同じコンカレンシー グループを使うジョブまたはワークフローを一度に 1 つ� け実行するには、jobs.<job_id>.concurrency
を使います。 並行処理グループには、任意の文字列または式を使用できます。 式は、secrets
コンテキストを除く任意のコンテキストを使用できます。 式について詳しくは、「式」を参照してく� さい。
ワークフロー レベルで concurrency
を指定することもできます。 詳細については、「concurrency
」を参照してく� さい。
並行ジョブかワークフローがキューに入っている� �合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中� と、キューイングされたジョブかワークフローは pending
になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、cancel-in-progress: true
を指定します。
並行性とデフォルトの動作の使用例
concurrency: staging_environment
concurrency: ci-${{ github.ref }}
並行性を使って進行中のジョブもしくは実行をキャンセルする例
concurrency:
group: ${{ github.ref }}
cancel-in-progress: true
例: フォールバック値の使用
特定のイベントにのみ定義されるプロパティでグループ名を作成する� �合、フォールバック値を使用できます。 たとえば、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
jobs.<job_id>.outputs
jobs.<job_id>.outputs
を使って、ジョブの出力の map
を作成できます。 ジョブの出力は、そのジョブに依存しているすべての下流のジョブから利用できます。 ジョブ依存関係の定義の詳細については、「jobs.<job_id>.needs
」を参照してく� さい。
出力は Unicode 文字列であり、最大 1 MB となります。 ワークフロー実行内のすべての出力の合計は、最大 50 MB です。
表現が含まれているジョブの出力は、各ジョブの終了時にランナー上で評価されます。 シークレットを含む出力はランナー上で編集され、GitHub Actionsには送られません。
依存するジョブでジョブ出力を使うには、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 "::set-output name=test::hello"
- id: step2
run: echo "::set-output name=test::world"
job2:
runs-on: ubuntu-latest
needs: job1
steps:
- run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}
jobs.<job_id>.env
ジョブ中のすべてのステップから利用できる環境変数の map
です。 ワークフロー全体あるいは個別のステップのための環境変数を設定することもできます。 詳細については、env
および jobs.<job_id>.steps[*].env
を参照してく� さい。
同じ名前で複数の環境変数が定義されている� �合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。
例
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
に既定の設定を設定することもできます。 詳細については、「jobs.defaults.run
」を参照してく� さい。 このキーワード中では、コンテキストや式を使うことはできません。
同じ名前で複数のデフォルトの設定が定義されている� �合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。
例: ジョブの既定の run
ステップ オプションの設定
jobs:
job1:
runs-on: ubuntu-latest
defaults:
run:
shell: bash
working-directory: scripts
jobs.<job_id>.steps
1 つのジョブには、steps
と呼ばれる一連のタスクがあります。 ステップでは、コマンドを実行する、設定タスクを実行する、あるいはリポジトリやパブリックリポジトリ、Dockerレジストリで公開されたアクションを実行することができます。 すべてのステップでアクションを実行するとは限りませんが、すべてのアクションはステップとして実行されます。 各ステップは、ランナー環境のそれ自体のプロセスで実行され、ワークスペースとファイルシステ� にアクセスします。 ステップはそれ自体のプロセスで実行されるため、環境変数を変更しても、ステップ間では反� されません。 GitHubには、ジョブを設定して完了するステップが組み込まれています。
ワークフローの利用限度内であれば、実行するステップ数に限度はありません。 詳細については、GitHub がホストするランナーの「使用量制限と課金」とセルフホステッド ランナーの使用制限の「セルフホステッド ランナーについて」
例
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 が if
条件を式として自動的に評価するためです。 詳細については、「式」を参照してく� さい。
例: コンテキストの使用
このステップは、イベントの種類が 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.'
詳細については、「コンテキストの可用性」と「暗号化されたシークレット」を参照してく� さい。
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@a81bbbf8298c0fa03ea29cdc473d45769f953675
# Reference the major version of a release
- uses: actions/checkout@v2
# Reference a specific version
- uses: actions/checkout@v2.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
ワークフローのリポジトリにあるアクションを含むディレクトリのパス。 アクションを使用する前にリポジトリをチェックアウトする必要があります。
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v2
- name: Use local my-action
uses: ./.github/actions/my-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 を生成し、暗号化されたシークレットとしてトークンを追� します。 詳しくは、「personal access token の作成」と「暗号化されたシークレット」を参照してく� さい。
この例の PERSONAL_ACCESS_TOKEN
をシークレットの名前に置き換えます。
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v2
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
jobs.<job_id>.steps[*].run
オペレーティングシステ� のシェルを使用してコマンドラインプログラ� を実行します。 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
working-directory
キーワードを使えば、コマンドが実行される作業ディレクトリを指定できます。
- name: Clean temp directory
run: rm -rf *
working-directory: ./temp
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}'" . |
例: bash を使ったスクリプトの実行
steps:
- name: Display the path
run: echo $PATH
shell: bash
例: Windows cmd
を使ったスクリプトの実行
steps:
- name: Display the path
run: echo %PATH%
shell: cmd
例: PowerShell Core を使ったスクリプトの実行
steps:
- name: Display the path
run: echo ${env:PATH}
shell: pwsh
PowerShell Desktopを使用してスクリプトを実行する例
steps:
- name: Display the path
run: echo ${env:PATH}
shell: powershell
例: Python スクリプトの実行
steps:
- name: Display the path
run: |
import os
print(os.environ['PATH'])
shell: python
カスタ� シェル
command […options] {0} [..more_options]
を使って、テンプレート文字列に shell
値を設定できます。 GitHub では、空白区切りで最初の文字列をコマンドとして解釈し、{0}
にある一時的なスクリプトのファイル名を挿入します。
次に例を示します。
steps:
- name: Display the environment variables and their values
run: |
print %ENV
shell: perl {0}
使われるコマンド (この例では perl
) は、ランナーにインストールされている必要があります。
終了コードとエラーアクションの環境設定
組み込みのshellキーワードについては、GitHubがホストする実行環境で以下のデフォルトが提供されます。 シェルスクリプトを実行する際には、以下のガイドラインを使ってく� さい。
-
bash
/sh
:set -eo pipefail
を使うフェイルファスト動作:shell: bash
が明示的に指定されていると、このオプションが設定されます。 既定では適用されません。- シェル オプションにテンプレート文字列を指定することで、シェル パラメーターを完全に制御できます。 たとえば、
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_
が付けられ、大文字に変換されます。
例
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
はこのパラメーターではサポートされていません。
例
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
キーワードでは、実行する実行可能ファイルを定義する単一の文字列� けを受け付けます。
例
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
コンテキストを使って設定する必要があります。 詳細については、「環境変数の利用」と「コンテキスト」を参照してく� さい。
例
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されるまでにステップが実行できる最大の分数。
jobs.<job_id>.timeout-minutes
GitHubで自動的にキャンセルされるまでジョブを実行する最長時間 (分)。 デフォルト: 360
タイ� アウトがランナーのジョブ実行の制限時間を超えた� �合、代わりに、実行の制限時間に達したときにジョブが取り消されます。 ジョブ実行の制限時間の詳細については、GitHub ホステッド ランナーに関しては「使用量制限と課金」、セルフホステッド ランナーの使用制限に関しては「セルフホステッド ランナーについて」を参照してく� さい。
注: ジョブが終了するか最大 24 時間後に、GITHUB_TOKEN
の有効期限が切れます。 セルフホステッド ランナーでは、ジョブのタイ� アウトが 24 時間を超える� �合、トークンが制限要� になる可能性があります。 GITHUB_TOKEN
の詳細については、「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@v2
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@v2
with:
node-version: ${{ matrix.version }}
例: コンテキストを使ったマトリックスの作成
コンテキストを使用してマトリックスを作成できます。 コンテキストの詳細については、「コンテキスト」を参照してく� さい。
たとえば、次のワークフローは 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@v2
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 つずつ、計 6 つのジョブが実行されます。 os
の値が windows-latest
で node
の値が 16
のジョブが実行されると、6
の値を持つ npm
という追� の変数がジョブに含まれます。
jobs:
example_matrix:
strategy:
matrix:
os: [windows-latest, ubuntu-latest]
node: [12, 14, 16]
include:
- os: windows-latest
node: 16
npm: 6
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v2
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
に設定されている� �合、マトリックス内のいずれかのジョブが失敗すると、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:14.16
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:14.16
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
オプションはサポートされていません。
jobs.<job_id>.services
注: ワークフローが Docker コンテナー アクション、ジョブ コンテナーあるいはサービス コンテナーを使うなら、Linux のランナーを使う必要があります。
- GitHubホストランナーを使うなら、Ubuntuランナーを使わなければなりません。
- セルフホストランナーを使っているなら、ランナーとしてLinuxマシンを使い、Dockerをインストールしておかなければなりません。
ワークフロー中のジョブのためのサービスコンテナをホストするために使われます。 サービスコンテナは、データベースやRedisのようなキャッシュサービスの作成に役立ちます。 ランナーは自動的にDockerネットワークを作成し、サービスコンテナのライフサイクルを管理します。
コンテナを実行するようにジョブを設定した� �合、あるいはステップがコンテナアクションを使う� �合は、サービスもしくはアクションにアクセスするためにポートをマップする必要はありません。 Dockerは自動的に、同じDockerのユーザ定義ブリッジネットワーク上のコンテナ間のすべてのポートを公開します。 サービスコンテナは、ホスト名で直接参照できます。 ホスト名は自動的に、ワークフロー中のサービスに設定したラベル名にマップされます。
ランナーマシン上で直接実行されるようにジョブを設定し、ステップがコンテナアクションを使わないのであれば、必要なDockerサービスコンテナのポートはDockerホスト(ランナーマシン)にマップしなければなりません サービスコンテナには、localhostとマップされたポートを使ってアクセスできます。
ネットワーク サービス コンテナーの違いの詳細については、「サービス コンテナーについて」を参照してく� さい。
例: localhost の使用
この例では、nginxとredisという2つのサービスを作成します。 Dockerホストのポートを指定して、コンテナのポートを指定しなかった� �合、コンテナのポートは空いているポートにランダ� に割り当てられます。 GitHub では、割り当てられたコンテナー ポートを ${{job.services.<service_name>.ports}}
のコンテキストに設定します。 この例では、${{ job.services.nginx.ports['8080'] }}
と ${{ 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 TCP port 6379 on Docker host to a random free port on the Redis container
ports:
- 6379/tcp
jobs.<job_id>.services.<service_id>.image
アクションを実行するサービスコンテナとして使用するDockerイメージ。 値には、Docker Hub イメージ名またはレジストリ名を指定できます。
jobs.<job_id>.services.<service_id>.credentials
イメージのコンテナー レジストリでイメージをプルするための認証が必要な� �合は、jobs.<job_id>.container.credentials
を使って username
と password
の map
を設定できます。 資� �情� �は、docker login
コマンドに指定するのと同じ値です。
例
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>
は、コンテナー内の絶対パスです。
例
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.services.<service_id>.options
追� のDockerコンテナリソースのオプション。 オプションのリストについては、「docker create
オプション」を参照してく� さい。
警告: --network
オプションはサポートされていません。
フィルター パターンのチート シート
特別なキャラクタをパス、ブランチ、タグフィルタで利用できます。
*
: 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
branches:
- '**/README.md'
# Invalid - creates a parse error that
# prevents your workflow from running.
branches:
- **/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 |