ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。
ワークフロー用のYAML構文について
ワークフローファイルはYAML構文を使用し、ファイル拡張子が.yml
または.yaml
である必要があります。 YAMLについて詳しくなく、学んでいきたい場合は、「Learn YAML in five minutes (Y分で学ぶYAML)」をお読みください。
ワークフローファイルは、リポジトリの.github/workflows
ディレクトリに保存する必要があります。
name
ワークフローの名前。 GitHubでは、リポジトリのアクションページにワークフローの名前が表示されます。 name
を省略すると、GitHubはリポジトリのルートに対するワークフローファイルの相対パスをその値に設定します。
on
ワークフローを自動的にトリガーするには、on
を使ってワークフローの実行を引き起こせるイベントを定義してください。 使用可能なイベントの一覧は、「ワークフローをトリガーするイベント」を参照してください。
ワークフローをトリガーする単一もしくは複数のイベントを定義したり、あるいはタイムスケジュールを設定したりできます。 ワークフローの実行を、特定のファイル、タグ、ブランチが変更されたときにだけ生じるように制限することもできます。 これらのオプションは、以下のセクションで説明されています。
単一イベントの利用
たとえば、以下のon
の値を持つワークフローは、ワークフローのリポジトリの任意のブランチにプッシュが行われたときに実行されます。
on: push
複数イベントの利用
単一のイベントもしくは複数のイベントを指定できます。 たとえば、以下の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がオープンされた場合、Issueのオープンイベントに対して1つ、そして2つのIssueのラベル付けのイベントに対して2つ、合計3つのワークフローの実行が開始されます。
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
を1つのワークフロー内の同じイベントに使うことはできません。
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/**'
例: ブランチの除外
パターンがtags-ignore
とマッチする場合、ワークフローは実行されません。 branches
で定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、次のワークフローは以下をターゲットとしないPull Requestに対するpull_request
イベントがあった場合に実行されます。
mona/octocat
という名前のブランチ(refs/heads/mona/octocat
)releases/beta/3-alpha
のように、releases/**-alpha
にマッチする名前のブランチ(refs/releases/beta/3-alpha
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
例: ブランチを含めるとともに除外
branches
及びbranches-ignore
フィルタを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対して含めるブランチパターンと除外するブランチパターンをどちらも使いたい場合には、branches
フィルタを!
文字と合わせて使い、除外するブランチを示してください。
!
文字を使ってブランチを定義する場合、!
文字なしで少なくとも1つのブランチを定義する必要もあります。 ブランチの除外だけをしたい場合には、代わりにbranches-ignore
を使ってください。
パターンを定義する順序により、結果に違いが生じます。
- 肯定のマッチングパターンの後に否定のマッチングパターン ("
!
" のプレフィクス) を定義すると、Git ref を除外します。 - 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。
以下のワークフローは、releases/10
や releases/beta/mona
へのpull_request
イベントで実行されますが、releases/10-alpha
や releases/beta/3-alpha
に対するPull Requstでは実行されません。肯定のマッチングパターンの後に、否定のマッチングパターン !releases/**-alpha
が続いているからです。
on:
pull_request:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.push.<branches|tags|branches-ignore|tags-ignore>
push
イベントを使う場合、特定のブランチもしくはタグでワークフローを実行するように設定できます。
ブランチ名のパターンを含めたい場合、あるいはブランチ名のパターンを含めるとともに除外もしたい場合に、branches
フィルターを使ってください。 ブランチ名のパターンを除外のみしたい場合には、branches-ignore
フィルターを使ってください。 branches
及びbranches-ignore
フィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。
タグ名のパターンを含めたい場合、あるいはタグ名のパターンを含めるとともに除外もしたい場合に、tags
フィルターを使ってください。 タグ名のパターンを除外のみしたい場合には、tags-ignore
フィルターを使ってください。 tags
及びtags-ignore
フィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。
tags
/tags-ignore
のみ、もしくはbranches
/branches-ignore
だけを定義した場合、ワークフローは未定義のGit refに影響するイベントに対しては実行されません。 tags
/tags-ignore
あるいはbranches
/branches-ignore
のどちらも定義しなかった場合、ブランチもしくはタグに影響するイベントに対して実行されます。 branches
/branches-ignore
及びpaths
をどちらも定義した場合、ワークフローは双方のフィルタを満たす場合にのみ実行されます。
branches
、branches-ignore
、tags
、tags-ignore
のキーワードは、1つ以上ののブランチもしくはタグ名にマッチする*
、**
、+
、?
、!
といった文字を使う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:
# refs/headsに対してマッチするパターンのシーケンス
branches:
- main
- 'mona/octocat'
- 'releases/**'
# 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.*
例: ブランチとタグを含めるとともに除外
branches
及びbranches-ignore
フィルタを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 同様に、tags
及びtags-ignore
を1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対してブランチもしくはタグパターンを含めるとともに除外したい場合には、branches
もしくはtags
フィルタを!
文字とともに使って、除外すべきブランチもしくはタグを示してください。
!
文字を使ってブランチを定義する場合、!
文字なしで少なくとも1つのブランチを定義する必要もあります。 ブランチの除外だけをしたい場合には、代わりにbranches-ignore
を使ってください。 同様に、!
文字でタグを定義する場合には、!
なしで少なくとも1つのタグを定義する必要があります。 タグの除外だけをしたい場合には、代わりにtags-ignore
を使ってください。
パターンを定義する順序により、結果に違いが生じます。
- 肯定のマッチングパターンの後に否定のマッチングパターン ("
!
" のプレフィクス) を定義すると、Git ref を除外します。 - 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。
以下のワークフローは、releases/10
や releases/beta/mona
へのプッシュで実行されますが、releases/10-alpha
や releases/beta/3-alpha
へのプッシュでは実行されません。肯定のマッチングパターンの後に、否定のマッチングパターン !releases/**-alpha
が続いているからです。
on:
push:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.<push|pull_request|pull_request_target>.<paths|paths-ignore>
push
およびpull_request
イベントを使用する場合、変更されたファイルパスに基づいてワークフローを実行するよう設定できます。 パスフィルタは、タグのプッシュに対しては評価されません。
paths
フィルタは、ファイルパスのパターンを含めたい場合や、ファイルパスのパターンを含めるとともに除外もしたい場合に使ってください。 ファイルパスパターンの除外のみをしたい場合には、paths-ignore
を使ってください。 paths
及びpaths-ignore
フィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。
branches
/branches-ignore
とpaths
の両方を定義した場合、ワークフローはどちらのフィルタも満たされた場合にのみ実行されます。
paths
および paths-ignore
キーワードは、*
と **
のワイルドカード文字を使って複数のパス名と一致させる glob パターンを受け付けます。 詳しい情報については、「フィルタパターンのチートシート」を参照してください。
例: パスを含める
paths
フィルタのパターンにマッチするパスが1つでもあれば、ワークフローは実行されます。 たとえば、以下のワークフローはJavaScriptファイル(.js
)をプッシュするたびに実行されます。
on:
push:
paths:
- '**.js'
ノート: path filtering、branch filtering、commit messageによってワークフローがスキップされた場合、そのワークフローに関連づけられたチェックは、"Pending"状態のままになります。 それらのチェックの成功を必要とするPull Requestのマージはブロックされます。 詳しい情報については「スキップされた必須のチェックの処理」を参照してください。
例: パスの除外
すべてのパス名が paths-ignore
のパターンと一致する場合、ワークフローは実行されません。 paths-ignore
内のパターンにマッチしないパス名があった場合、場合、パターンにマッチするパスがあったとしても、ワークフローは実行されます。
以下のパスフィルタを持つワークフローは、リポジトリのルートにある docs
ディレクトリ外のファイルを少なくとも1つ含むpush
イベントでのみ実行されます。
on:
push:
paths-ignore:
- 'docs/**'
例: パスを含めるとともに除外
paths
及びpaths-ignore
を1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対して含めるパスパターンと除外するパスパターンをどちらも使いたい場合には、paths
フィルタを!
文字と合わせて使い、除外するパスを示してください。
!
文字を使ってパスを定義する場合、!
文字なしで少なくとも1つのパスを定義する必要もあります。 パスの除外だけをしたい場合には、代わりにpaths-ignore
を使ってください。
パターンを定義する順序により、結果に違いが生じます:
- 肯定のマッチの後に否定のマッチングパターン(
!
がプレフィックスされている)を置くと、パスが除外されます。 - 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、パスを再び含めます。
この例は、push
イベントにsub-project
ディレクトリあるいはそのサブディレクトリ内のファイルが含まれ、そのファイルがsub-project/docs
ディレクトリ内にはない場合に実行されます。 たとえば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は、headとベースのSHAを互いに直接比較します。
- 新しいブランチへのプッシュ: 最も深いプッシュの先祖の親に対するツードットdiffです。
Diffは300ファイルに制限されています。 フィルタが返す先頭の300ファイル内にマッチしない変更されたファイルがある場合、ワークフローは実行されません。 ワークフローが自動的に実行されるよう、さらに具体的なフィルタを作成する必要があるかもしれません。
詳しい情報については「Pull Request中のブランチの比較について」を参照してください。
on.schedule
on.schedule
を使って、ワークフローのタイムスケジュールを定義できます。 POSIX クーロン構文を使用して、特定の UTC 時間にワークフローを実行できるようスケジュール設定できます。 スケジュールしたワークフローは、デフォルトまたはベースブランチの直近のコミットで実行されます。 スケジュールされたワークフローを実行できる最短の間隔は、5 分ごとに 1 回です。
この例では、ワークフローは毎日UTCの5:30と17:30にトリガーされます。
on:
schedule:
# *はYAMLにおける特殊文字なので、この文字列はクオートしなければならない
- cron: '30 5,17 * * *'
A single workflow can be triggered by multiple schedule
events. You can access the schedule event that triggered the workflow through the github.event.schedule
context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the Not on Monday or Wednesday
step on Monday and Wednesday.
on:
schedule:
- cron: '30 5 * * 1,3'
- cron: '30 5 * * 2,4'
jobs:
test_schedule:
runs-on: ubuntu-latest
steps:
- name: Not on Monday or Wednesday
if: github.event.schedule != '30 5 * * 1,3'
run: echo "This step will be skipped on Monday and Wednesday"
- name: Every time
run: echo "This step will always run"
cron構文に関する詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。
on.workflow_call
Use on.workflow_call
to define the inputs and outputs for a reusable workflow. You can also map the secrets that are available to the called workflow. For more information on reusable workflows, see "Reusing workflows."
on.workflow_call.inputs
When using the workflow_call
keyword, you can optionally specify inputs that are passed to the called workflow from the caller workflow. For more information about the workflow_call
keyword, see "Events that trigger workflows."
In addition to the standard input parameters that are available, on.workflow_call.inputs
requires a type
parameter. 詳しい情報についてはon.workflow_call.inputs.<input_id>.type
を参照してください。
If a default
parameter is not set, the default value of the input is false
for a boolean, 0
for a number, and ""
for a string.
Within the called workflow, you can use the inputs
context to refer to an input.
If a caller workflow passes an input that is not specified in the called workflow, this results in an error.
サンプル
on:
workflow_call:
inputs:
username:
description: 'A username passed from the caller workflow'
default: 'john-doe'
required: false
type: string
jobs:
print-username:
runs-on: ubuntu-latest
steps:
- name: Print the input name to STDOUT
run: echo The username is ${{ inputs.username }}
詳しい情報については「ワークフローの再利用」を参照してください。
on.workflow_call.inputs.<input_id>.type
Required if input is defined for the on.workflow_call
keyword. The value of this parameter is a string specifying the data type of the input. This must be one of: boolean
, number
, or string
.
on.workflow_call.outputs
A map of outputs for a called workflow. Called workflow outputs are available to all downstream jobs in the caller workflow. Each output has an identifier, an optional description,
and a value.
The value
must be set to the value of an output from a job within the called workflow.
In the example below, two outputs are defined for this reusable workflow: workflow_output1
and workflow_output2
. These are mapped to outputs called job_output1
and job_output2
, both from a job called my_job
.
サンプル
on:
workflow_call:
# Map the workflow outputs to job outputs
outputs:
workflow_output1:
description: "The first job output"
value: ${{ jobs.my_job.outputs.job_output1 }}
workflow_output2:
description: "The second job output"
value: ${{ jobs.my_job.outputs.job_output2 }}
For information on how to reference a job output, see jobs.<job_id>.outputs
. 詳しい情報については「ワークフローの再利用」を参照してください。
on.workflow_call.secrets
A map of the secrets that can be used in the called workflow.
Within the called workflow, you can use the secrets
context to refer to a secret.
If a caller workflow passes a secret that is not specified in the called workflow, this results in an error.
サンプル
on:
workflow_call:
secrets:
access-token:
description: 'A token passed from the caller workflow'
required: false
jobs:
pass-secret-to-action:
runs-on: ubuntu-latest
steps:
- name: Pass the received secret to an action
uses: ./.github/actions/my-action
with:
token: ${{ secrets.access-token }}
on.workflow_call.secrets.<secret_id>
A string identifier to associate with the secret.
on.workflow_call.secrets.<secret_id>.required
A boolean specifying whether the secret must be supplied.
on.workflow_run.<branches|branches-ignore>
workflow_run
を使う場合、ワークフローがトリガーされるためには、どのブランチでトリガーされたワークフローが実行されなければならないかを指定できます。
branches
及びbranches-ignore
フィルタは、複数のブランチ名にマッチさせるために*
、**
、+
、?
、!
などの文字を使うglobパターンを受け付けます。 これらの文字のいずれかを含む名前に対してリテラルの一致をさせたい場合には、これらの特殊文字を\
でエスケープしなければなりません。 globパターンに関する詳しい情報については「フィルタパターンのチートシート」を参照してください。
たとえば、以下のトリガーを持つワークフローは、Build
という名前のワークフローがreleases/
で始まる名前のブランチで実行される場合にのみ実行されます。
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
以下のトリガーを持つワークフローは、Build
という名前のワークフローがcanary
という名前ではないブランチ上で実行される場合にのみ実行されます。
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
branches
とbranches-ignore
を1つのワークフロー内の同じイベントに使うことはできません。 1つのイベントに対して含めるブランチパターンと除外するブランチパターンをどちらも使いたい場合には、branches
フィルタを!
文字と合わせて使い、除外するブランチを示してください。
パターンを定義する順序により、結果に違いが生じます。
- 肯定のマッチの後に否定のマッチングパターン(
!
がプレフィックスされている)を置くと、ブランチが除外されます。 - 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、ブランチは再び含められます。
たとえば、以下のトリガーを持つワークフローは、Build
というナメのワークフローがreleases/10
もしくはreleases/beta/mona
という名前のブランチ上で実行されている場合に実行されますが、releases/10-alpha
、releases/beta/3-alpha
、main
といった名前のブランチ上で実行されている場合には実行されません。
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
- '!releases/**-alpha'
on.workflow_dispatch.inputs
workflow_dispatch
イベントを使う場合、ワークフローに渡す入力を指定することもできます。
トリガーされたワークフローは、入力をgithub.event.inputs
コンテキストで受け取ります。 詳しい情報については「コンテキスト」を参照してください。
on:
workflow_dispatch:
inputs:
logLevel:
description: 'Log level'
required: true
default: 'warning'
type: choice
options:
- info
- warning
- debug
print_tags:
description: 'True to print to STDOUT'
required: true
type: boolean
tags:
description: 'Test scenario tags'
required: true
type: string
environment:
description: 'Environment to run tests against'
type: environment
required: true
jobs:
print-tag:
runs-on: ubuntu-latest
if: ${{ 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 設定の管理」を参照してください。
例: GITHUB_TOKENへの権限の割り当て
この例は、ワークフロー内のすべてのジョブに適用される GITHUB_TOKEN
に設定されている権限を示しています。 すべての権限に読み取りアクセスが付与されます。
name: "My workflow"
on: [ push ]
permissions: read-all
jobs:
...
env
ワークフロー中のすべてのジョブのステップから利用できる環境変数のmap
です。 1つのジョブのステップ、あるいは1つのステップからだけ利用できる環境変数を設定することもできます。 詳しい情報については「jobs.<job_id>.env
」及び「jobs.<job_id>.steps[*].env
を参照してください。
Variables in the env
map cannot be defined in terms of other variables in the map.
同じ名前で複数の環境変数が定義されている場合、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
concurrency
を使って、同じ並行処理グループを使うジョブもしくはワークフローが一度に1つだけ実行されることを保証できます。 並行処理グループには、任意の文字列または式を使用できます。 この式はgithub
contextだけを使用します。 式に関する詳しい情報については「式」を参照してください。
ジョブレベルで concurrency
を指定することもできます。 詳しい情報については、jobs.<job_id>.concurrency
を参照してください。
並行ジョブもしくはワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブもしくはワークフローが進行中だと、キューイングされたジョブもしくはワークフローは保留中
になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じ並行グループ内にある実行中のジョブもしくはワークフローもキャンセルするには、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.<job_id>.needs
キーワードを使用して他のジョブに対する依存関係を定義します。
それぞれのジョブは、runs-on
で指定されたランナー環境で実行されます。
ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳しい情報についてはGitHubホストランナーの「使用制限と支払い」及びセルフホストランナーの使用制限に関する「セルフホストランナーについて」を参照してください。
ワークフローの実行中で動作しているジョブの一意の識別子を知る必要がある場合は、GitHub Enterprise Server APIが利用できます。 詳しい情報については、「ワークフロージョブ」を参照してください。
jobs.<job_id>
jobs.<job_id>
を使い、ジョブに一意の識別子を与えてください。 job_id
キーは文字列型で、その値はジョブの設定データのマップとなるものです。 <job_id>
は、jobs
オブジェクトごとに一意の文字列に置き換える必要があります。 <job_id>
は、英字または_
で始める必要があり、英数字と-
、_
しか使用できません。
例: ジョブの作成
この例では2つのジョブが作成されており、そのjob_id
の値はmy_first_job
とmy_second_job
です。
jobs:
my_first_job:
name: My first job
my_second_job:
name: My second job
jobs.<job_id>.name
jobs.<job_id>.name
を使ってジョブの名前を設定してください。この名前はGitHubのUIに表示されます。
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 設定の管理」を参照してください。
例: 特定のジョブに対する権限の設定
この例では、stale
という名前のジョブにのみ適用される GITHUB_TOKEN
に設定されている権限を示しています。 issues
および pull-requests
のスコープに対して書き込みアクセスが許可されます。 他のすべてのスコープにはアクセスできません。
jobs:
stale:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
steps:
- uses: actions/stale@v5
jobs.<job_id>.needs
jobs.<job_id>.needs
を使って、このジョブを実行する前に成功して完了していなければならないジョブを特定してください。 これは文字列型または文字列の配列です。 1つのジョブが失敗した場合、失敗したジョブを続行するような条件式を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。 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
というOrganization内にあるときだけ実行されます。 そうでない場合、このジョブはskippedとマークされます。
name: example-workflow
on: [push]
jobs:
production-deploy:
if: github.repository == 'octo-org/octo-repo-prod'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
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パブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。
GitHubホストランナーの選択
If you use a GitHub-hosted runner, each job runs in a fresh instance of a runner image specified by runs-on
.
利用可能なGitHubホストランナーの種類は以下のとおりです。
Runner image | 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 22.04は現在パブリックベータです。 |
Ubuntu 20.04 | ubuntu-latest またはubuntu-20.04 |
|
Ubuntu 18.04 | ubuntu-18.04 |
|
macOS Monterey 12 | macos-12 |
|
macOS Big Sur 11 | macos-latest もしくはmacos-11 |
現在macos-latest ラベルはmacOS 11のランナーイメージを使用しています。
|
macOS Catalina 10.15 [deprecated] | macos-10.15 |
macOS-11 もしくはmacOS-12 に移行してください。 詳しい情報についてはGitHubブログのポストを参照してください。
|
Note: The -latest
runner images are the latest stable images that GitHub provides, and might not be the most recent version of the operating system available from the operating system vendor.
ノート: ベータ及び非推奨のイメージは"as-is"、"with all faults"、"as available"で提供されており、サービスレベルアグリーメント及び保証の対象外です。 ベータのイメージは、カスタマーサポートの対象外になっていることがあります。
例: オペレーティングシステムの指定
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
and url
を持つenvironmentオブジェクトとして渡すことができます。 デプロイメントAPIでは、このURLはenvironment_url
にマップされます。 デプロイメントAPIに関する詳しい情報については「デプロイメント」を参照してください。
例: 単一の環境名の使用
environment: staging_environment
例: 環境名とURLの使用
environment:
name: production_environment
url: https://github.com
URLには式を指定でき、secrets
context以外の任意のコンテキストを利用できます。 式に関する詳しい情報については「式」を参照してください。
例: URLとしての出力の使用
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
jobs.<job_id>.concurrency
注釈: ジョブレベルで並行処理が指定されている場合、ジョブの順序は保証されないか、互いに 5 分以内にそのキューを実行します。
jobs.<job_id>.concurrency
を使って、同じ並行処理グループを使う1つのジョブもしくはワークフローだけが実行されることを保証できます。 並行処理グループには、任意の文字列または式を使用できます。 式は、secrets
コンテキストを除く任意のコンテキストを使用できます。 式に関する詳しい情報については「式」を参照してください。
ワークフローレベルで concurrency
を指定することもできます。 詳しい情報については、concurrency
を参照してください。
並行ジョブもしくはワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブもしくはワークフローが進行中だと、キューイングされたジョブもしくはワークフローは保留中
になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じ並行グループ内にある実行中のジョブもしくはワークフローもキャンセルするには、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文字列であり、最大1MBです。 ワークフローの実行中のすべての出力の合計は、最大で50MBです。
式を含むジョブの出力は、それぞれのジョブの終わりにランナー上で評価されます。 シークレットを含む出力はランナー上で編集され、GitHub Actionsには送られません。
依存するジョブでジョブの出力を使いたい場合には、needs
コンテキストが利用できます。 詳細については、「コンテキスト」を参照してください。
例: ジョブの出力の定義
jobs:
job1:
runs-on: ubuntu-latest
# ステップの出力をジョブの出力にマップする
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
条件を式として自動的に評価するためです。 詳しい情報については「式」を参照してください。
Example: Using contexts
このステップは、イベントの種類が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.
Example: Using status check functions
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
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
GitHubで表示されるステップの名前。
jobs.<job_id>.steps[*].uses
ジョブでステップの一部として実行されるアクションを選択します。 アクションとは、再利用可能なコードの単位です。 ワークフロー、パブリックリポジトリ、または公開されているDockerコンテナイメージと同じリポジトリで定義されているアクションを使用できます。
Git ref、SHA、またはDockerタグ番号を指定して、使用しているアクションのバージョンを含めることを強く推奨します。 バージョンを指定しないと、アクションのオーナーがアップデートを公開したときに、ワークフローが中断したり、予期せぬ動作をしたりすることがあります。
- リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
- 特定のメジャーアクションバージョンを使用すると、互換性を維持したまま重要な修正とセキュリティパッチを受け取ることができます。 ワークフローが引き続き動作することも保証できます。
- アクションのデフォルトブランチを使用すると便利なこともありますが、別のユーザが破壊的変更を加えた新しいメジャーバージョンをリリースすると、ワークフローが動作しなくなる場合があります。
入力が必要なアクションもあり、入力をwith
キーワードを使って設定する必要があります。 必要な入力を判断するには、アクションのREADMEファイルをお読みください。
アクションは、JavaScriptのファイルもしくはDockerコンテナです。 使用するアクションがDockerコンテナの場合、ジョブはLinux環境で実行する必要があります。 詳細については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@v3
# Reference a specific version
- uses: actions/checkout@v3.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}
パブリックGitHubリポジトリで特定のブランチ、ref、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
ワークフローのリポジトリにあるアクションを含むディレクトリのパス。 アクションを使用する前にリポジトリをチェックアウトする必要があります。
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v3
- name: Use local my-action
uses: ./.github/actions/my-action
Example: Using a Docker Hub action
docker://{image}:{tag}
Docker Hubで公開されているDockerイメージ。
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}
パブリックレジストリのDockerイメージ。 この例では、gcr.io
にある Google Container Registry を使用しています。
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
ワークフローはプライベートリポジトリをチェックアウトし、アクションをローカルで参照する必要があります。 個人アクセストークンを生成し、暗号化されたシークレットとしてトークンを追加します。 詳しい情報については、「個人アクセストークンを作成する」および「暗号化されたシークレット」を参照してください。
例にある PERSONAL_ACCESS_TOKEN
をシークレットの名前に置き換えます。
jobs:
my_first_job:
steps:
- name: Check out repository
uses: actions/checkout@v3
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
コマンドで指定された文字列になります。
コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 For more information, see 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
キーワードを使用するか、カスタムセットのシェルオプションを定義することができます。 The shell command that is run internally executes a temporary file that contains the commands specified in the run
keyword.
サポートされているプラットフォーム | shell パラメータ | 説明 | 内部で実行されるコマンド |
---|---|---|---|
すべて | bash | 非Windowsプラットフォームのデフォルトシェルで、sh へのフォールバックがあります。 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}'" . |
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
PowerShell Desktopを使用してスクリプトを実行する例
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
カスタムシェル
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
:- 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. たとえば、
bash {0}
とします。 - shライクのシェルは、スクリプトで実行された最後のコマンドの終了コードで終了します。これが、アクションのデフォルトの動作でもあります。 runnerは、この終了コードに基づいてステップのステータスを失敗/成功としてレポートします。
- Fail-fast behavior using
-
powershell
/pwsh
- 可能な場合のフェイルファースト動作。
pwsh
およびpowershell
の組み込みシェルの場合は、スクリプトの内容の前に$ErrorActionPreference = 'stop'
が付加されます。 - ここでは、アクションステータスがスクリプトの最後の終了コードを反映するように、PowerShellスクリプトに
if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }
を付加しています。 - 必要な場合には、組み込みシェルを使用せずに、
pwsh -File {0}
やpowershell -Command "& '{0}'"
などのカスタムシェルを指定すれば、いつでもオプトアウトすることができます。
- 可能な場合のフェイルファースト動作。
-
cmd
- 各エラーコードをチェックしてそれぞれに対応するスクリプトを書く以外、フェイルファースト動作を完全にオプトインする方法はないようです。 デフォルトでその動作を指定することはできないため、この動作はスクリプトに記述する必要があります。
cmd.exe
は、実行した最後のプログラムのエラーレベルで終了し、runnerにそのエラーコードを返します。 この動作は、これ以前のsh
およびpwsh
のデフォルト動作と内部的に一貫しており、cmd.exe
のデフォルトなので、この動作には影響しません。
jobs.<job_id>.steps[*].with
アクションによって定義される入力パラメータのmap
。 各入力パラメータはキー/値ペアです。 入力パラメータは環境変数として設定されます。 変数の前にはINPUT_
が付けられ、大文字に変換されます。
サンプル
hello_world
アクションで定義される3つの入力パラメータ (first_name
、middle_name
、last_name
) を定義します。 hello-world
アクションからは、これらの入力変数はINPUT_FIRST_NAME
、INPUT_MIDDLE_NAME
、INPUT_LAST_NAME
という環境変数としてアクセスできます。
jobs:
my_first_job:
steps:
- name: My first step
uses: actions/hello_world@main
with:
first_name: Mona
middle_name: The
last_name: Octocat
jobs.<job_id>.steps[*].with.args
Dockerコンテナへの入力を定義する文字列
。 GitHubは、コンテナの起動時にargs
をコンテナのENTRYPOINT
に渡します。 このパラメータは、文字列の配列
をサポートしません。
サンプル
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
コンテキストを使って設定しなければなりません。 For more information, see "Using environment variables" and "Contexts."
サンプル
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
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: GITHUB_TOKEN
は、ジョブの完了時もしくは最大24時間後に期限切れになります。 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. マトリックス戦略を使うと、単一のジョブ定義中で変数を使って、変数の組み合わせに基づく複数のジョブの実行を自動的に生成できます。 たとえばマトリックス戦略を使って、コードを言語の複数のバージョンや、複数のオペレーティングシステムでテストできます。 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]
取り得る変数のそれぞれの組み合わせに対して、ジョブが実行されます。 この例では、ワークフローはos
及びversion
変数のそれぞれの組み合わせに対応する6つのジョブを実行します。
デフォルトでは、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}
1つのマトリックスはワークフローの実行ごとに最大で256のジョブを生成します。 この制限は、GitHub Enterprise Serverホスト及びセルフホストの両方のランナーに適用されます。
定義した変数はmatrix
コンテキストのプロパティとなり、このプロパティはワークフローファイルの他の領域から参照できます。 この例では、matrix.version
とmatrix.os
を使ってジョブが使用している現在のversion
とos
の値にアクセスできます。 詳細については、「コンテキスト」を参照してください。
Example: Using a single-dimension matrix
1つの変数を指定して、1次元のマトリックスを作成できます。
たとえば、以下のワークフローは変数version
に[10, 12, 14]
という値を定義しています。 このワークフローは、変数中のそれぞれの値に対して1つずつ、3つのジョブを実行します。 それぞれのジョブはversion
の値にmatrix.version
コンテキストを通じてアクセスし、その値をnode-version
としてactions/setup-node
アクションに渡します。
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
steps:
- uses: actions/setup-node@v3
with:
node-version: ${{ matrix.version }}
Example: Using a multi-dimension matrix
複数の変数を指定して、多次元マトリックスを作成できます。 変数の取り得るそれぞれの組み合わせに対してジョブが実行されます。
たとえば、以下のワークフローは2つの変数を指定しています。
os
変数では2つのオペレーティングシステムが指定されていますversion
変数では、3つのNode.jsのバージョンが指定されています
このワークフローは、os
及びversion
変数のそれぞれの組み合わせに応じた6のジョブを実行します。 各ジョブは、runs-on
の値を現在のos
の値に設定し、現在のversion
の値をactions/setup-node
アクションに渡します。
jobs:
example_matrix:
strategy:
matrix:
os: [ubuntu-18.04, ubuntu-20.04]
version: [10, 12, 14]
runs-on: ${{ matrix.os }}
steps:
- uses: actions/setup-node@v3
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@v3
with:
node-version: ${{ matrix.version }}
jobs.<job_id>.strategy.matrix.include
jobs.<job_id>.strategy.matrix.include
を使って、既存のマトリックス設定を拡張したり、新しい設定を追加したりしてください。 include
の値は、オブジェクトのリストです。
include
リスト中の各オブジェクトについて、オブジェクト中のkey:valueペアがいずれもオリジナルのマトリックスの値を上書きしない場合、それらのkey:valueペアはそれぞれのマトリックスの組み合わせに追加されます。 オブジェクトがマトリックスの組み合わせのいずれにも追加できない場合、代わりに新しいマトリックスの組み合わせが作成されます。 オリジナルのマトリックスの値は上書きされませんが、追加されたマトリックスの値は上書きできることに注意してください。
たとえば、以下のマトリックス
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}
は、値を上書きせずにオリジナルのマトリックスの組み合わせに追加することができないので、追加のマトリックスの組み合わせとして追加されます。 これは{fruit: banana}
のマトリックスの組み合わせには追加されませんが、それはこの組み合わせがオリジナルのマトリックスの組み合わせの1つではないからです。
Example: Expanding configurations
たとえば、以下のワークフローはos
とnode
の組み合わせに対応する6つのジョブを実行します。 os
の値がwindows-latest
でnode
の値が16
に対するジョブが実行されると、そのジョブにはnpm
という追加の変数が6
を値として含まれます。
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@v3
with:
node-version: ${{ matrix.node }}
- if: ${{ matrix.npm }}
run: npm install -g npm@${{ matrix.npm }}
- run: npm --version
Example: Adding configurations
たとえばこのマトリックスは、マトリックス内のos
及びversion
の各組み合わせに、os
の値がwindows-latest
でversion
の値が17
の場合を加えて、10個のジョブを実行します。
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
マトリックス変数を指定しなければ、include
以下のすべての設定が実行されます。 たとえば、以下のワークフローはinclude
の各エントリに対応して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個の各設定に対応するジョブから、{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
and 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
は単一のジョブに適用されます。 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
に設定すれば、ジョブが失敗した時にワークフローの実行が次へ進めるようになります。
Example: Preventing a specific failing matrix job from failing a 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-18.04]
experimental: [false]
include:
- node: 15
os: ubuntu-18.04
experimental: true
jobs.<job_id>.container
ノート: ワークフローがDockerコンテナアクション、ジョブコンテナ、サービスコンテナを使うなら、Linuxランナーを使わなければなりません:
- GitHubホストランナーを使うなら、Ubuntuランナーを使わなければなりません。
- セルフホストランナーを使っているなら、ランナーとしてLinuxマシンを使い、Dockerをインストールしておかなければなりません。
jobs.<job_id>.container
を使って、コンテナをまだ指定していないジョブ内の任意のステップを実行するためのコンテナを作成してください。 スクリプトアクションとコンテナアクションの両方を使うステップがある場合、コンテナアクションは同じボリュームマウントを使用して、同じネットワーク上にある兄弟コンテナとして実行されます。
container
を設定しない場合は、コンテナで実行されるよう設定されているアクションを参照しているステップを除くすべてのステップが、runs-on
で指定したホストで直接実行されます。
例: コンテナ内でのジョブの実行
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
イメージのコンテナレジストリがイメージをプルするために認証を要求するなら、username
とpassword
のmap
を設定するためにjobs.<job_id>.container.credentials
が利用できます。 この認証情報は、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
を使って、コンテナで公開するポートの配列
を設定してください。
jobs.<job_id>.container.volumes
jobs.<job_id>.container.volumes
を使って、コンテナが使用するボリュームの配列
を設定してください。 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とマップされたポートを使ってアクセスできます。
ネットワーキングサービスコンテナ間の差異に関する詳しい情報については「サービスコンテナについて」を参照してください。
Example: Using 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
# Dockerホストのポート8080をnginxコンテナのポート80にマップする
ports:
- 8080:80
redis:
image: redis
# Dockerホストのポート6379をRedisコンテナのランダムな空きポートにマップする
ports:
- 6379/tcp
jobs.<job_id>.services.<service_id>.image
アクションを実行するサービスコンテナとして使用するDockerイメージ。 The value can be the Docker Hub image name or a registry name.
jobs.<job_id>.services.<service_id>.credentials
イメージのコンテナレジストリがイメージをプルするために認証を要求するなら、username
とpassword
のmap
を設定するためにjobs.<job_id>.container.credentials
が利用できます。 この認証情報は、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
オプションはサポートされていません。
jobs.<job_id>.uses
The location and version of a reusable workflow file to run as a job. Use one of the following syntaxes:
{owner}/{repo}/.github/workflows/{filename}@{ref}
パブリックもしくはインターナルリポジトリ内の再利用可能なワークフローの場合。../.github/workflows/{filename}
同じリポジトリ内の再利用可能なワークフローの場合。
{ref}
にはSHA、リリースタグ、ブランチ名が使えます。 コミットSHAを使うのが、安定性とセキュリティの上で最も安全です。 詳しい情報については「GitHub Actionsのためのセキュリティ強化」を参照してください。 2番目の構文({owner}/{repo}
and @{ref}
なし)を使うなら、呼び出されるワークフローは呼び出し元のワークフローと同じコミットからのものになります。
サンプル
jobs:
call-workflow-1-in-local-repo:
uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
call-workflow-2-in-local-repo:
uses: ./.github/workflows/workflow-2.yml
call-workflow-in-another-repo:
uses: octo-org/another-repo/.github/workflows/workflow.yml@v1
詳しい情報については「ワークフローの再利用」を参照してください。
jobs.<job_id>.with
When a job is used to call a reusable workflow, you can use with
to provide a map of inputs that are passed to the called workflow.
Any inputs that you pass must match the input specifications defined in the called workflow.
Unlike jobs.<job_id>.steps[*].with
, the inputs you pass with jobs.<job_id>.with
are not be available as environment variables in the called workflow. Instead, you can reference the inputs by using the inputs
context.
サンプル
jobs:
call-workflow:
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
with:
username: mona
jobs.<job_id>.with.<input_id>
A pair consisting of a string identifier for the input and the value of the input. The identifier must match the name of an input defined by on.workflow_call.inputs.<inputs_id>
in the called workflow. The data type of the value must match the type defined by on.workflow_call.inputs.<input_id>.type
in the called workflow.
Allowed expression contexts: github
, and needs
.
jobs.<job_id>.secrets
When a job is used to call a reusable workflow, you can use secrets
to provide a map of secrets that are passed to the called workflow.
Any secrets that you pass must match the names defined in the called workflow.
サンプル
jobs:
call-workflow:
uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
secrets:
access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
jobs.<job_id>.secrets.<secret_id>
A pair consisting of a string identifier for the secret and the value of the secret. The identifier must match the name of a secret defined by on.workflow_call.secrets.<secret_id>
in the called workflow.
Allowed expression contexts: github
, needs
, and secrets
.
フィルタパターンのチートシート
特別なキャラクタをパス、ブランチ、タグフィルタで利用できます。
*
ゼロ個以上のキャラクタにマッチしますが、/
にはマッチしません。 たとえばOcto*
はOctocat
にマッチします。**
ゼロ個以上の任意のキャラクタにマッチします。?
: Matches zero or one of the preceding character.+
: 直前の文字の 1 つ以上に一致します。[]
括弧内にリストされた、あるいは範囲に含まれる1つのキャラクタにマッチします。 範囲に含めることができるのはa-z
、A-Z
、0-9
のみです。 たとえば、[0-9a-z]
という範囲は任意の数字もしくは小文字にマッチします。 たとえば[CB]at
はCat
あるいはBat
にマッチし、[1-2]00
は100
や200
にマッチします。!
: パターンの先頭に置くと、肯定のパターンを否定にします。 先頭のキャラクタではない場合は、特別な意味を持ちません。
YAMLにおいては、*
、[
、!
は特別なキャラクタです。 パターンを*
、[
、!
で始める場合、そのパターンをクオートで囲まなければなりません。
# 有効
- '**/README.md'
# 無効 - ワークフローの実行を妨げる
# 解析エラーを作成する
- **/README.md
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
."
ブランチやタグにマッチするパターン
パターン | 説明 | マッチの例 |
---|---|---|
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]+ | Matches all semantic versioning branches and tags with major version 1 or 2. | v1.10.1 v2.0.0 |
ファイルパスにマッチするパターン
パスパターンはパス全体にマッチしなければならず、リポジトリのルートを出発点とします。
パターン | マッチの説明 | マッチの例 |
---|---|---|
'*' | ワイルドカードの* は任意のキャラクタにマッチしますが、スラッシュ(/ )にはマッチしません。 * はYAMLにおける特別なキャラクタです。 パターンを* で始める場合は、クオートを使わなければなりません。 | README.md server.rb |
'*.jsx?' | ? はゼロ個以上の先行するキャラクタにマッチします。 | 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 Does not match README.md docs/hello.md |
*.md !README.md README* | パターンは順番にチェックされます。 先行するパターンを否定するパターンで、ファイルパスが再度含まれるようになります。 | hello.md README.md README.doc |