注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
About YAML syntax for workflows
Workflow files use YAML syntax, and must have either a .yml
or .yaml
file extension. YAML を初めて使用する� �合は、「Learn YAML in Y minutes」 (YAML を Y 分で学習する) を参照してく� さい。
You must store workflow files in the .github/workflows
directory of your repository.
name
The name of your workflow. GitHub displays the names of your workflows on your repository's "Actions" tab. If you omit name
, GitHub sets it to the workflow file path relative to the root of the repository.
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
When using the workflow_dispatch
event, you can optionally specify inputs that are passed to the workflow.
The triggered workflow receives the inputs in the github.event.inputs
context. For more information, see "Contexts."
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
A map
of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env
and jobs.<job_id>.steps[*].env
.
Variables in the env
map cannot be defined in terms of other variables in the map.
同じ名前で複数の環境変数が定義されている� �合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。
Example
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
を使って、ジョブを実行するマシンの種類を定義します。 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 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 11 ランナー イメージを使用しています。
|
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
You can use jobs.<job_id>.outputs
to create a map
of outputs for a job. Job outputs are available to all downstream jobs that depend on this job. For more information on defining job dependencies, see jobs.<job_id>.needs
.
出力は Unicode 文字列であり、最大 1 MB となります。 ワークフロー実行内のすべての出力の合計は、最大 50 MB です。
Job outputs containing expressions are evaluated on the runner at the end of each job. Outputs containing secrets are redacted on the runner and not sent to GitHub Actions.
To use job outputs in a dependent job, you can use the needs
context. For more information, see "Contexts."
Example: Defining outputs for a job
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
A map
of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env
and jobs.<job_id>.steps[*].env
.
同じ名前で複数の環境変数が定義されている� �合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。
Example
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
A job contains a sequence of tasks called steps
. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.
You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
Example
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
A unique identifier for the step. You can use the id
to reference the step in contexts. For more information, see "Contexts."
jobs.<job_id>.steps[*].if
You can use the if
conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.
if
条件の中で式を使う際には、式構文 (${{ }}
)を省略できます。これは、GitHub が if
条件を式として自動的に評価するためです。 For more information, see "Expressions."
Example: Using contexts
This step only runs when the event type is a pull_request
and the event action is 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.
Example: Using status check functions
The my backup step
only runs when the previous step of a job fails. For more information, see "Expressions."
steps:
- name: My first step
uses: octo-org/action-name@main
- name: My backup step
if: ${{ failure() }}
uses: actions/heroku@1.0.0
Example: Using secrets
Secrets cannot be directly referenced in if:
conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.
If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }}
in the example) will be an empty string.
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.'
For more information, see "Context availability" and "Encrypted secrets."
jobs.<job_id>.steps[*].name
A name for your step to display on GitHub.
jobs.<job_id>.steps[*].uses
Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.
We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.
- Using the commit SHA of a released action version is the safest for stability and security.
- If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
- Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.
Some actions require inputs that you must set using the with
keyword. Review the action's README file to determine the inputs required.
Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see runs-on
.
Example: Using versioned actions
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
Example: Using a public action
{owner}/{repo}@{ref}
You can specify a branch, ref, or SHA in a public GitHub repository.
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
Example: Using a public action in a subdirectory
{owner}/{repo}/{path}@{ref}
A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/aws/ec2@main
Example: Using an action in the same repository as the workflow
./path/to/dir
The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v2
- name: Use local my-action
uses: ./.github/actions/my-action
Example: Using a Docker Hub action
docker://{image}:{tag}
A Docker image published on Docker Hub.
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://alpine:3.8
Example: Using a Docker public registry action
docker://{host}/{image}:{tag}
A Docker image in a public registry. This example uses the Google Container Registry at gcr.io
.
jobs:
my_first_job:
steps:
- name: My first step
uses: docker://gcr.io/cloud-builders/gradle
Example: Using an action inside a different private repository than the workflow
Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."
Replace PERSONAL_ACCESS_TOKEN
in the example with the name of your secret.
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
Runs command-line programs using the operating system's shell. If you do not provide a name
, the step name will default to the text specified in the run
command.
Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell
.
Each run
keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:
-
A single-line command:
- name: Install Dependencies run: npm install
-
A multi-line command:
- name: Clean install dependencies and build run: | npm ci npm run build
Using the working-directory
keyword, you can specify the working directory of where to run the command.
- name: Clean temp directory
run: rm -rf *
working-directory: ./temp
jobs.<job_id>.steps[*].shell
You can override the default shell settings in the runner's operating system using the shell
keyword. You can use built-in shell
keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the run
keyword.
Supported platform | shell parameter | Description | Command run internally |
---|---|---|---|
Linux / macOS | unspecified | The default shell on non-Windows platforms. Note that this runs a different command to when bash is specified explicitly. If bash is not found in the path, this is treated as sh . | bash -e {0} |
All | bash | The default shell on non-Windows platforms with a fallback to sh . When specifying a bash shell on Windows, the bash shell included with Git for Windows is used. | bash --noprofile --norc -eo pipefail {0} |
All | pwsh | The PowerShell Core. GitHub appends the extension .ps1 to your script name. | pwsh -command ". '{0}'" |
All | python | Executes the python command. | python {0} |
Linux / macOS | sh | The fallback behavior for non-Windows platforms if no shell is provided and bash is not found in the path. | sh -e {0} |
Windows | cmd | GitHub appends the extension .cmd to your script name and substitutes for {0} . | %ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"" . |
Windows | pwsh | This is the default shell used on Windows. The PowerShell Core. GitHub appends the extension .ps1 to your script name. If your self-hosted Windows runner does not have PowerShell Core installed, then PowerShell Desktop is used instead. | pwsh -command ". '{0}'" . |
Windows | powershell | The PowerShell Desktop. GitHub appends the extension .ps1 to your script name. | powershell -command ". '{0}'" . |
Example: Running a script using bash
steps:
- name: Display the path
run: echo $PATH
shell: bash
Example: Running a script using Windows cmd
steps:
- name: Display the path
run: echo %PATH%
shell: cmd
Example: Running a script using PowerShell Core
steps:
- name: Display the path
run: echo ${env:PATH}
shell: pwsh
Example: Using PowerShell Desktop to run a script
steps:
- name: Display the path
run: echo ${env:PATH}
shell: powershell
Example: Running a python script
steps:
- name: Display the path
run: |
import os
print(os.environ['PATH'])
shell: python
Custom shell
You can set the shell
value to a template string using command […options] {0} [..more_options]
. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}
.
For example:
steps:
- name: Display the environment variables and their values
run: |
print %ENV
shell: perl {0}
The command used, perl
in this example, must be installed on the runner.
Exit codes and error action preference
For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.
-
bash
/sh
:- Fail-fast behavior using
set -eo pipefail
: This option is set whenshell: bash
is explicitly specified. It is not applied by default. - You can take full control over shell parameters by providing a template string to the shell options. For example,
bash {0}
. - sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.
- Fail-fast behavior using
-
powershell
/pwsh
- Fail-fast behavior when possible. For
pwsh
andpowershell
built-in shell, we will prepend$ErrorActionPreference = 'stop'
to script contents. - We append
if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }
to powershell scripts so action statuses reflect the script's last exit code. - Users can always opt out by not using the built-in shell, and providing a custom shell option like:
pwsh -File {0}
, orpowershell -Command "& '{0}'"
, depending on need.
- Fail-fast behavior when possible. For
-
cmd
- There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
cmd.exe
will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previoussh
andpwsh
default behavior and is thecmd.exe
default, so this behavior remains intact.
jobs.<job_id>.steps[*].with
A map
of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_
and converted to upper case.
Example
Defines the three input parameters (first_name
, middle_name
, and last_name
) defined by the hello_world
action. These input variables will be accessible to the hello-world
action as INPUT_FIRST_NAME
, INPUT_MIDDLE_NAME
, and INPUT_LAST_NAME
environment variables.
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
A string
that defines the inputs for a Docker container. GitHub passes the args
to the container's ENTRYPOINT
when the container starts up. An array of strings
is not supported by this parameter.
Example
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.
The args
are used in place of the CMD
instruction in a Dockerfile
. If you use CMD
in your Dockerfile
, use the guidelines ordered by preference:
- Document required arguments in the action's README and omit them from the
CMD
instruction. - Use defaults that allow using the action without specifying any
args
. - If the action exposes a
--help
flag, or something similar, use that as the default to make your action self-documenting.
jobs.<job_id>.steps[*].with.entrypoint
Overrides the Docker ENTRYPOINT
in the Dockerfile
, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT
instruction which has a shell and exec form, entrypoint
keyword accepts only a single string defining the executable to be run.
Example
steps:
- name: Run a custom command
uses: octo-org/action-name@main
with:
entrypoint: /a/different/executable
The entrypoint
keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.
jobs.<job_id>.steps[*].env
Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see env
and jobs.<job_id>.env
.
同じ名前で複数の環境変数が定義されている� �合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。
Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets
context. For more information, see "Using environment variables" and "Contexts."
Example
steps:
- name: My first action
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FIRST_NAME: Mona
LAST_NAME: Octocat
jobs.<job_id>.steps[*].continue-on-error
Prevents a job from failing when a step fails. Set to true
to allow a job to pass when this step fails.
jobs.<job_id>.steps[*].timeout-minutes
The maximum number of minutes to run the step before killing the process.
jobs.<job_id>.timeout-minutes
The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360
If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
Note: ジョブが終了するか最大 24 時間後に、GITHUB_TOKEN
の有効期限が切れます。 For self-hosted runners, the token may be the limiting factor if the job timeout is greater than 24 hours. For more information on the GITHUB_TOKEN
, see "About the GITHUB_TOKEN
secret."
jobs.<job_id>.strategy
Use jobs.<job_id>.strategy
to use a matrix strategy for your jobs. マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。 たとえば、マトリックス戦略を使用して、複数バージョンの言語または複数のオペレーティング システ� でコードをテストできます。 For more information, see "Using a matrix for your jobs."
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
の現在の値にアクセスできます。 詳細については、「コンテキスト」を参照してく� さい。
Example: Using a single-dimension matrix
単一の変数を指定して、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 }}
Example: Using a multi-dimension matrix
複数の変数を指定して、多次元マトリックスを作成できます。 ジョブは、変数の可能な組み合わせごとに実行されます。
たとえば、次のワークフローでは 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 }}
Example: Using contexts to create matrices
コンテキストを使用してマトリックスを作成できます。 コンテキストの詳細については、「コンテキスト」を参照してく� さい。
たとえば、次のワークフローは 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}
マトリックスの組み合わせには追� されません。
Example: Expanding configurations
たとえば、次のワークフローでは、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
Example: Adding configurations
たとえば、このマトリックスでは 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
Prevents a workflow run from failing when a job fails. Set to true
to allow a workflow run to pass when this job fails.
Example: Preventing a specific failing matrix job from failing a workflow run
You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with node
set to 15
to fail without failing the workflow run.
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をインストールしておかなければなりません。
Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.
If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.
If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.
For more information about the differences between networking service containers, see "About service containers."
Example: Using localhost
This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. GitHub sets the assigned container port in the ${{job.services.<service_name>.ports}}
context. In this example, you can access the service container ports using the ${{ job.services.nginx.ports['8080'] }}
and ${{ job.services.redis.ports['6379'] }}
contexts.
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
The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.
jobs.<job_id>.services.<service_id>.credentials
イメージのコンテナー レジストリでイメージをプルするための認証が必要な� �合は、jobs.<job_id>.container.credentials
を使って username
と password
の map
を設定できます。 資� �情� �は、docker login
コマンドに指定するのと同じ値です。
Example
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
Sets a map
of environment variables in the service container.
jobs.<job_id>.services.<service_id>.ports
Sets an array
of ports to expose on the service container.
jobs.<job_id>.services.<service_id>.volumes
Sets an array
of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.
To specify a volume, you specify the source and destination path:
<source>:<destinationPath>
.
The <source>
is a volume name or an absolute path on the host machine, and <destinationPath>
is an absolute path in the container.
Example
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.services.<service_id>.options
Additional Docker container resource options. For a list of options, see "docker create
options."
Warning: The --network
option is not supported.
Filter pattern cheat sheet
You can use special characters in path, branch, and tag filters.
*
: Matches zero or more characters, but does not match the/
character. For example,Octo*
matchesOctocat
.**
: Matches zero or more of any character.?
: Matches zero or one of the preceding character.+
: Matches one or more of the preceding character.[]
Matches one character listed in the brackets or included in ranges. Ranges can only includea-z
,A-Z
, and0-9
. For example, the range[0-9a-z]
matches any digit or lowercase letter. For example,[CB]at
matchesCat
orBat
and[1-2]00
matches100
and200
.!
: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.
The characters *
, [
, and !
are special characters in YAML. If you start a pattern with *
, [
, or !
, you must enclose the pattern in quotes. Also, if you use a flow sequence with a pattern containing [
and/or ]
, the pattern must be enclosed in quotes.
# 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] ]
For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>
", "on.<pull_request>.<branches|tags>
", and "on.<push|pull_request>.paths
."
Patterns to match branches and tags
Pattern | Description | Example matches |
---|---|---|
feature/* | The * wildcard matches any character, but does not match slash (/ ). | feature/my-branch feature/your-branch |
feature/** | The ** wildcard matches any character including slash (/ ) in branch and tag names. | feature/beta-a/my-branch feature/your-branch feature/mona/the/octocat |
main releases/mona-the-octocat | Matches the exact name of a branch or tag name. | main releases/mona-the-octocat |
'*' | Matches all branch and tag names that don't contain a slash (/ ). The * character is a special character in YAML. When you start a pattern with * , you must use quotes. | main releases |
'**' | Matches all branch and tag names. This is the default behavior when you don't use a branches or tags filter. | all/the/branches every/tag |
'*feature' | The * character is a special character in YAML. When you start a pattern with * , you must use quotes. | mona-feature feature ver-10-feature |
v2* | Matches branch and tag names that start with v2 . | v2 v2.0 v2.9 |
v[12].[0-9]+.[0-9]+ | Matches all semantic versioning branches and tags with major version 1 or 2. | v1.10.1 v2.0.0 |
Patterns to match file paths
Path patterns must match the whole path, and start from the repository's root.
Pattern | Description of matches | Example matches |
---|---|---|
'*' | The * wildcard matches any character, but does not match slash (/ ). The * character is a special character in YAML. When you start a pattern with * , you must use quotes. | README.md server.rb |
'*.jsx?' | The ? character matches zero or one of the preceding character. | page.js page.jsx |
'**' | The ** wildcard matches any character including slash (/ ). This is the default behavior when you don't use a path filter. | all/the/files.md |
'*.js' | The * wildcard matches any character, but does not match slash (/ ). Matches all .js files at the root of the repository. | app.js index.js |
'**.js' | Matches all .js files in the repository. | index.js js/index.js src/js/app.js |
docs/* | All files within the root of the docs directory, at the root of the repository. | docs/README.md docs/file.txt |
docs/** | Any files in the /docs directory at the root of the repository. | docs/README.md docs/mona/octocat.txt |
docs/**/*.md | A file with a .md suffix anywhere in the docs directory. | docs/README.md docs/mona/hello-world.md docs/a/markdown/file.md |
'**/docs/**' | Any files in a docs directory anywhere in the repository. | docs/hello.md dir/docs/my-file.txt space/docs/plan/space.doc |
'**/README.md' | A README.md file anywhere in the repository. | README.md js/README.md |
'**/*src/**' | Any file in a folder with a src suffix anywhere in the repository. | a/src/app.js my-src/code/js/app.js |
'**/*-post.md' | A file with the suffix -post.md anywhere in the repository. | my-post.md path/their-post.md |
'**/migrate-*.sql' | A file with the prefix migrate- and suffix .sql anywhere in the repository. | migrate-10909.sql db/migrate-v1.0.sql db/sept/migrate-v1.sql |
*.md !README.md | Using an exclamation mark (! ) in front of a pattern negates it. When a file matches a pattern and also matches a negative pattern defined later in the file, the file will not be included. | hello.md Does not match README.md docs/hello.md |
*.md !README.md README* | Patterns are checked sequentially. A pattern that negates a previous pattern will re-include file paths. | hello.md README.md README.doc |