ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情� �を見ることができます。
ワークフロー用のYAML構文について
ワークフローファイルはYAML構文を使用し、ファイル拡張子が.yml
または.yaml
である必要があります。 YAMLについて詳しくなく、学んでいきたい� �合は、「Learn YAML in five minutes (Y分で学ぶYAML)」をお読みく� さい。
ワークフローファイルは、リポジトリの.github/workflows
ディレクトリに保存する必要があります。
name
ワークフローの名前。 GitHubでは、リポジトリのアクションページにワークフローの名前が表示されます。 name
を省略すると、GitHubはリポジトリのルートに対するワークフローファイルの相対パスをその値に設定します。
on
To automatically trigger a workflow, use on
to define which events can cause the workflow to run. 使用可能なイベントの一覧は、「ワークフローをトリガーするイベント」を参照してく� さい。
You can define single or multiple events that can a trigger workflow, or set a time schedule. You can also restrict the execution of a workflow to only occur for specific files, tags, or branch changes. These options are described in the following sections.
Using a single event
For example, a workflow with the following on
value will run when a push is made to any branch in the workflow's repository:
on: push
Using multiple events
You can specify a single event or multiple events. For example, a workflow with the following on
value will run when a push is made to any branch in the repository or when someone forks the repository:
on: [push, fork]
If you specify multiple events, only one of those events needs to occur to trigger your workflow. If multiple triggering events for your workflow occur at the same time, multiple workflow runs will be triggered.
Using activity types
Some events have activity types that give you more control over when your workflow should run. Use on.<event_name>.types
to define the type of event activity that will trigger a workflow run.
For example, the issue_comment
event has the created
, edited
, and deleted
activity types. If your workflow triggers on the label
event, it will run whenever a label is created, edited, or deleted. If you specify the created
activity type for the label
event, your workflow will run when a label is created but not when a label is edited or deleted.
on:
label:
types:
- created
If you specify multiple activity types, only one of those event activity types needs to occur to trigger your workflow. If multiple triggering event activity types for your workflow occur at the same time, multiple workflow runs will be triggered. For example, the following workflow triggers when an issue is opened or labeled. If an issue with two labels is opened, three workflow runs will start: one for the issue opened event and two for the two issue labeled events.
on:
issue:
types:
- opened
- labeled
各イベントとそのアクティビティタイプの詳細については、「ワークフローをトリガーするイベント」を参照してく� さい。
Using filters
Some events have filters that give you more control over when your workflow should run.
For example, the push
event has a branches
filter that causes your workflow to run only when a push to a branch that matches the branches
filter occurs, instead of when any push occurs.
on:
push:
branches:
- main
- 'releases/**'
Using activity types and filters with multiple events
If you specify activity types or filters for an event and your workflow triggers on multiple events, you must configure each event separately. 設定を持たないイベントも含め、すべてのイベントにはコロン (:
)を追� しなければなりません。
For example, a workflow with the following on
value will run when:
- A label is created
- A push is made to the
main
branch in the repository - A push is made to a GitHub Pages-enabled branch
on:
label:
types:
- created
push:
branches:
- main
page_build:
on.<event_name>.types
Use on.<event_name>.types
to define the type of activity that will trigger a workflow run. ほとんどの GitHub イベントは、2 つ以上のアクティビティタイプからトリガーされます。 For example, the label
is triggered when a label is created
, edited
, or deleted
. types
キーワードを使用すると、ワークフローを実行させるアクティブの範囲を狭くすることができます。 webhook イベントをトリガーするアクティビティタイプが1つ� けの� �合、types
キーワードは不要です。
イベントtypes
の配列を使用できます。 各イベントとそのアクティビティタイプの詳細については、「ワークフローをトリガーするイベント」を参照してく� さい。
on:
label:
types: [created, edited]
on.<pull_request|pull_request_target>.<branches|branches-ignore>
When using the pull_request
and pull_request_target
events, you can configure a workflow to run only for pull requests that target specific branches.
Use the branches
filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore
filter when you only want to exclude branch name patterns. You cannot use both the branches
and branches-ignore
filters for the same event in a workflow.
If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
The branches
and branches-ignore
keywords accept glob patterns that use characters like *
, **
, +
, ?
, !
and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \
. For more information about glob patterns, see the "Filter pattern cheat sheet."
Example: Including branches
The patterns defined in branches
are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request
event for a pull request targeting:
- A branch named
main
(refs/heads/main
) - A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name starts with
releases/
, likereleases/10
(refs/heads/releases/10
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches:
- main
- 'mona/octocat'
- 'releases/**'
Example: Excluding branches
When a pattern matches the branches-ignore
pattern, the workflow will not run. The patterns defined in branches
are evaluated against the Git ref's name. For example, the following workflow would run whenever there is a pull_request
event unless the pull request is targeting:
- A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name matches
releases/**-alpha
, likereleases/beta/3-alpha
(refs/heads/releases/beta/3-alpha
)
on:
pull_request:
# Sequence of patterns matched against refs/heads
branches-ignore:
- 'mona/octocat'
- 'releases/**-alpha'
Example: Including and excluding branches
You cannot use branches
and branches-ignore
to filter the same event in a single workflow. If you want to both include and exclude branch patterns for a single event, use the branches
filter along with the !
character to indicate which branches should be excluded.
If you define a branch with the !
character, you must also define at least one branch without the !
character. If you only want to exclude branches, use branches-ignore
instead.
パターンを定義する� �序により、結果に違いが生じます。
- 肯定のマッチングパターンの後に否定のマッチングパターン ("
!
" のプレフィクス) を定義すると、Git ref を除外します。 - 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。
The following workflow will run on pull_request
events for pull requests that target releases/10
or releases/beta/mona
, but not for pull requests that target releases/10-alpha
or releases/beta/3-alpha
because the negative pattern !releases/**-alpha
follows the positive pattern.
on:
pull_request:
branches:
- 'releases/**'
- '!releases/**-alpha'
on.push.<branches|tags|branches-ignore|tags-ignore>
When using the push
event, you can configure a workflow to run on specific branches or tags.
Use the branches
filter when you want to include branch name patterns or when you want to both include and exclude branch names patterns. Use the branches-ignore
filter when you only want to exclude branch name patterns. You cannot use both the branches
and branches-ignore
filters for the same event in a workflow.
Use the tags
filter when you want to include tag name patterns or when you want to both include and exclude tag names patterns. Use the tags-ignore
filter when you only want to exclude tag name patterns. You cannot use both the tags
and tags-ignore
filters for the same event in a workflow.
If you define only tags
/tags-ignore
or only branches
/branches-ignore
, the workflow won't run for events affecting the undefined Git ref. If you define neither tags
/tags-ignore
or branches
/branches-ignore
, the workflow will run for events affecting either branches or tags. If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
The branches
, branches-ignore
, tags
, and tags-ignore
keywords accept glob patterns that use characters like *
, **
, +
, ?
, !
and others to match more than one branch or tag name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \
. For more information about glob patterns, see the "Filter pattern cheat sheet."
Example: Including branches and tags
branches
およびtags
で定義されているパターンは、Git refの名前と照らし合わせて評価されます。 For example, the following workflow would run whenever there is a push
event to:
- A branch named
main
(refs/heads/main
) - A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name starts with
releases/
, likereleases/10
(refs/heads/releases/10
) - A tag named
v2
(refs/tags/v2
) - A tag whose name starts with
v1.
, likev1.9.1
(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.*
Example: Excluding branches and tags
When a pattern matches the branches-ignore
or tags-ignore
pattern, the workflow will not run. branches
およびtags
で定義されているパターンは、Git refの名前と照らし合わせて評価されます。 For example, the following workflow would run whenever there is a push
event, unless the push
event is to:
- A branch named
mona/octocat
(refs/heads/mona/octocat
) - A branch whose name matches
releases/**-alpha
, likebeta/3-alpha
(refs/releases/beta/3-alpha
) - A tag named
v2
(refs/tags/v2
) - A tag whose name starts with
v1.
, likev1.9
(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.*
Example: Including and excluding branches and tags
You can't use branches
and branches-ignore
to filter the same event in a single workflow. Similarly, you can't use tags
and tags-ignore
to filter the same event in a single workflow. If you want to both include and exclude branch or tag patterns for a single event, use the branches
or tags
filter along with the !
character to indicate which branches or tags should be excluded.
If you define a branch with the !
character, you must also define at least one branch without the !
character. If you only want to exclude branches, use branches-ignore
instead. Similarly, if you define a tag with the !
character, you must also define at least one tag without the !
character. If you only want to exclude tags, use tags-ignore
instead.
パターンを定義する� �序により、結果に違いが生じます。
- 肯定のマッチングパターンの後に否定のマッチングパターン ("
!
" のプレフィクス) を定義すると、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>
When using the push
and pull_request
events, you can configure a workflow to run based on what file paths are changed. Path filters are not evaluated for pushes of tags.
Use the paths
filter when you want to include file path patterns or when you want to both include and exclude file path patterns. Use the paths-ignore
filter when you only want to exclude file path patterns. You cannot use both the paths
and paths-ignore
filters for the same event in a workflow.
If you define both branches
/branches-ignore
and paths
, the workflow will only run when both filters are satisfied.
The paths
and paths-ignore
keywords accept glob patterns that use the *
and **
wildcard characters to match more than one path name. 詳しい情� �については、「フィルタパターンのチートシート」を参照してく� さい。
Example: Including paths
paths
フィルタのパターンにマッチするパスが1つでもあれば、ワークフローは実行されます。 For example, the following workflow would run anytime you push a JavaScript file (.js
).
on:
push:
paths:
- '**.js'
Note: If a workflow is skipped due to path filtering, branch filtering or a commit message, then checks associated with that workflow will remain in a "Pending" state. A pull request that requires those checks to be successful will be blocked from merging. For more information, see "Handling skipped but required checks."
Example: Excluding paths
すべてのパス名が paths-ignore
のパターンと一致する� �合、ワークフローは実行されません。 If any path names do not match patterns in paths-ignore
, even if some path names match the patterns, the workflow will run.
以下のパスフィルタを持つワークフローは、リポジトリのルートにある docs
ディレクトリ外のファイルを少なくとも1つ含むpush
イベントでのみ実行されます。
on:
push:
paths-ignore:
- 'docs/**'
Example: Including and excluding paths
You can not use paths
and paths-ignore
to filter the same event in a single workflow. If you want to both include and exclude path patterns for a single event, use the paths
filter along with the !
character to indicate which paths should be excluded.
If you define a path with the !
character, you must also define at least one path without the !
character. If you only want to exclude paths, use paths-ignore
instead.
パターンを定義する� �序により、結果に違いが生じます:
- 肯定のマッチの後に否定のマッチングパターン(
!
がプレフィックスされている)を置くと、パスが除外されます。 - 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、パスを再び含めます。
この例は、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の比較
Note: If you push more than 1,000 commits, or if GitHub does not generate the diff due to a timeout, the workflow will always run.
フィルタは、変更されたファイルをpaths-ignore
あるいはpaths
リストに対して評価することによって、ワークフローを実行すべきか判断します。 ファイルが変更されていない� �合、ワークフローは実行されません。
GitHubはプッシュに対してはツードットdiff、プルリクエストに対してはスリードットdiffを使って変更されたファイルのリストを生成します。
- プルリクエスト: スリードットdiffは、トピックブランチの最新バージョンとトピックブランチがベースブランチと最後に同期されたコミットとの比較です。
- 既存のブランチへのプッシュ: ツードットdiffは、headとベースのSHAを互いに直接比較します。
- 新しいブランチへのプッシュ: 最も深いプッシュの先祖の親に対するツードットdiffです。
Diffs are limited to 300 files. If there are files changed that aren't matched in the first 300 files returned by the filter, the workflow will not run. You may need to create more specific filters so that the workflow will run automatically.
詳しい情� �については「Pull Request中のブランチの比較について」を参照してく� さい。
on.schedule
You can use on.schedule
to define a time schedule for your workflows. 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_run.<branches|branches-ignore>
When using the workflow_run
event, you can specify what branches the triggering workflow must run on in order to trigger your workflow.
The branches
and branches-ignore
filters accept glob patterns that use characters like *
, **
, +
, ?
, !
and others to match more than one branch name. If a name contains any of these characters and you want a literal match, you need to escape each of these special characters with \
. For more information about glob patterns, see the "Filter pattern cheat sheet."
For example, a workflow with the following trigger will only run when the workflow named Build
runs on a branch whose name starts with releases/
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches:
- 'releases/**'
A workflow with the following trigger will only run when the workflow named Build
runs on a branch that is not named canary
:
on:
workflow_run:
workflows: ["Build"]
types: [requested]
branches-ignore:
- "canary"
You cannot use both the branches
and branches-ignore
filters for the same event in a workflow. If you want to both include and exclude branch patterns for a single event, use the branches
filter along with the !
character to indicate which branches should be excluded.
パターンを定義する� �序により、結果に違いが生じます。
- A matching negative pattern (prefixed with
!
) after a positive match will exclude the branch. - A matching positive pattern after a negative match will include the branch again.
For example, a workflow with the following trigger will run when the workflow named Build
runs on a branch that is named releases/10
or releases/beta/mona
but will not releases/10-alpha
, releases/beta/3-alpha
, or 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 }}
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
Use defaults
to create a map
of default settings that will apply to all jobs in the workflow. 1つのジョブ� けで利用できるデフォルト設定を設定することもできます。 詳しい情� �についてはjobs.<job_id>.defaults
を参照してく� さい。
同じ名前で複数のデフォルトの設定が定義されている� �合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。
defaults.run
You can use defaults.run
to provide default shell
and working-directory
options for all run
steps in a workflow. 1つのジョブ� けで利用できるrun
のデフォルト設定を設定することもできます。 詳しい情� �についてはjobs.<job_id>.defaults.run
を参照してく� さい。 このキーワード中では、コンテキストや式を使うことはできません。
同じ名前で複数のデフォルトの設定が定義されている� �合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。
Example: Set the default shell and working directory
defaults:
run:
shell: bash
working-directory: scripts
jobs
A workflow run is made up of one or more jobs
, which run in parallel by default. ジョブを逐次的に実行するには、jobs.<job_id>.needs
キーワードを使用して他のジョブに対する依存関係を定義します。
それぞれのジョブは、runs-on
で指定されたランナー環境で実行されます。
ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
If you need to find the unique identifier of a job running in a workflow run, you can use the GitHub Enterprise Server API. 詳しい情� �については、「ワークフロージョブ」を参照してく� さい。
jobs.<job_id>
Use jobs.<job_id>
to give your job a unique identifier. job_id
キーは文字列型で、その値はジョブの設定データのマップとなるものです。 <job_id>
は、jobs
オブジェクトごとに一意の文字列に置き換える必要があります。 <job_id>
は、英字または_
で始める必要があり、英数字と-
、_
しか使用できません。
Example: Creating jobs
In this example, two jobs have been created, and their job_id
values are my_first_job
and my_second_job
.
jobs:
my_first_job:
name: My first job
my_second_job:
name: My second job
jobs.<job_id>.name
Use jobs.<job_id>.name
to set a name for the job, which is displayed in the GitHub UI.
jobs.<job_id>.needs
Use jobs.<job_id>.needs
to identify any jobs that must complete successfully before this job will run. 文字列型または文字列の配列です。 1つのジョブが失敗した� �合、失敗したジョブを続行するような条件式を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。 If a run contains a series of jobs that need each other, a failure applies to all jobs in the dependency chain from the point of failure onwards.
Example: Requiring successful dependent jobs
jobs:
job1:
job2:
needs: job1
job3:
needs: [job1, job2]
この例では、job1
が正常に完了してからjob2
が始まり、job3
はjob1
とjob2
が完了するまで待機します。
つまり、この例のジョブは逐次実行されるということです。
job1
job2
job3
Example: Not requiring successful dependent jobs
jobs:
job1:
job2:
needs: job1
job3:
if: ${{ always() }}
needs: [job1, job2]
この例では、job3
は条件式のalways()
を使っているので、job1
とjob2
が成功したかどうかにかかわらず、それらのジョブが完了したら常に実行されます。 For more information, see "Expressions."
jobs.<job_id>.if
You can use the jobs.<job_id>.if
conditional to prevent a job from running unless a condition is met. 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。
if
条件の中で式を使用する際には、式構文 (${{ }}
)を省略できます。これは、GitHub が if
条件を式として自動的に評価するためです。 For more information, see "Expressions."
Example: Only run job for specific repository
This example uses if
to control when the production-deploy
job can run. It will only run if the repository is named octo-repo-prod
and is within the octo-org
organization. Otherwise, the job will be marked as 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@v2
- uses: actions/setup-node@v2
with:
node-version: '14'
- run: npm install -g bats
jobs.<job_id>.runs-on
Use jobs.<job_id>.runs-on
to define the type of machine to run the job on. You can provide runs-on
as a single string or as an array of strings. If you specify an array of strings, your workflow will run on a self-hosted runner whose labels match all of the specified runs-on
values, if available. If you would like to run your workflow on multiple machines, use jobs.<job_id>.strategy
.
ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情� �を見ることができます。
Choosing GitHub-hosted runners
GitHubホストランナーを使う� �合、それぞれのジョブはruns-on
で指定された仮想環境の新しいインスタンスで実行されます。
利用可能なGitHubホストランナーの種類は以下のとおりです。
仮想環境 | YAMLのワークフローラベル | 注釈 |
---|---|---|
Windows Server 2022 | windows-latest もしくはwindows-2022 |
The windows-latest label currently uses the Windows Server 2022 runner image.
|
Windows Server 2019 | windows-2019 |
|
Ubuntu 22.04 | ubuntu-22.04 |
Ubuntu 22.04 is currently in public beta. |
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 |
The macos-latest label currently uses the macOS 11 runner image.
|
macOS Catalina 10.15 | macos-10.15 |
Note: The -latest
virtual environments 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.
Note: Beta and Deprecated Images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta Images may not be covered by customer support.
Example: Specifying an operating system
runs-on: ubuntu-latest
詳しい情� �については「GitHubホストランナーの仮想環境」を参照してく� さい。
Choosing self-hosted runners
ジョブでセルフホストランナーを指定するには、ワークフローファイル中でセルフホストランナーのラベルでruns-on
を設定してく� さい。
All self-hosted runners have the self-hosted
label. Using only this label will select any self-hosted runner. To select runners that meet certain criteria, such as operating system or architecture, we recommend providing an array of labels that begins with self-hosted
(this must be listed first) and then includes additional labels as needed. When you specify an array of labels, jobs will be queued on runners that have all the labels that you specify.
Although the self-hosted
label is not required, we strongly recommend specifying it when using self-hosted runners to ensure that your job does not unintentionally specify any current or future GitHub-hosted runners.
Example: Using labels for runner selection
runs-on: [self-hosted, linux]
詳しい情� �については「セルフホストランナーについて」及び「ワークフロー内でのセルフホストランナーの利用」を参照してく� さい。
jobs.<job_id>.environment
Use jobs.<job_id>.environment
to define the environment that the job references. 環境を参照するジョブがランナーに送られる前に、その環境のすべて保護ルールはパスしなければなりません。 For more information, see "Using environments for deployment."
環境は、環境のname
� けで、あるいはname
and url
を持つenvironmentオブジェクトとして渡すことができます。 デプロイメントAPIでは、このURLはenvironment_url
にマップされます。 デプロイメントAPIに関する詳しい情� �については「デプロイメント」を参照してく� さい。
Example: Using a single environment name
environment: staging_environment
Example: Using environment name and URL
environment:
name: production_environment
url: https://github.com
The URL can be an expression and can use any context except for the secrets
context. For more information about expressions, see "Expressions."
Example: Using output as URL
environment:
name: production_environment
url: ${{ steps.step_id.outputs.url_output }}
jobs.<job_id>.outputs
You can use jobs.<job_id>.outputs
to create a map
of outputs for a job. ジョブの出力は、そのジョブに依存しているすべての下流のジョブから利用できます。 ジョブの依存関係の定義に関する詳しい情� �についてはjobs.<job_id>.needs
を参照してく� さい。
Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.
Job outputs containing expressions are evaluated on the runner at the end of each job. シークレットを含む出力はランナー上で編集され、GitHub Actionsには送られません。
依存するジョブでジョブの出力を使いたい� �合には、needs
コンテキストが利用できます。 詳細については、「コンテキスト」を参照してく� さい。
Example: Defining outputs for a job
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
Use jobs.<job_id>.defaults
to create a map
of default settings that will apply to all steps in the job. ワークフロー全体に対してデフォルト設定を設定することもできます。 詳しい情� �についてはdefaults
を参照してく� さい。
同じ名前で複数のデフォルトの設定が定義されている� �合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。
jobs.<job_id>.defaults.run
Use jobs.<job_id>.defaults.run
to provide default shell
and working-directory
to all run
steps in the job. このセクションではコンテキストと式は許されていません。
ジョブ中のすべてのrun
ステップにデフォルトのshell
及びworking-directory
を提供できます。 ワークフロー全体についてrun
のためのデフォルト設定を設定することもできます。 詳しい情� �についてはjobs.defaults.run
を参照してく� さい。 このキーワード中では、コンテキストや式を使うことはできません。
同じ名前で複数のデフォルトの設定が定義されている� �合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。
Example: Setting default run
step options for a job
jobs:
job1:
runs-on: ubuntu-latest
defaults:
run:
shell: bash
working-directory: scripts
jobs.<job_id>.steps
1つのジョブには、steps
(ステップ) と呼ばれる一連のタスクがあります。 ステップでは、コマンドを実行する、設定タスクを実行する、あるいはリポジトリやパブリックリポジトリ、Dockerレジストリで公開されたアクションを実行することができます。 すべてのステップでアクションを実行するとは限りませんが、すべてのアクションはステップとして実行されます。 各ステップは、ランナー環境のそれ自体のプロセスで実行され、ワークスペースとファイルシステ� にアクセスします。 ステップはそれ自体のプロセスで実行されるため、環境変数を変更しても、ステップ間では反� されません。 GitHubには、ジョブを設定して完了するステップが組み込まれています。
ワークフローの利用限度内であれば、実行するステップ数に限度はありません。 For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.
サンプル
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
条件を式として自動的に評価するためです。 For more information, see "Expressions."
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
は、ジョブの前のステップが失敗した� �合にのみ実行されます。 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
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@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}
パブリック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@v2
- 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@v2
with:
repository: octocat/my-private-repo
ref: v1.0
token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
path: ./.github/actions/my-private-repo
- name: Run my action
uses: ./.github/actions/my-private-repo/my-action
jobs.<job_id>.steps[*].run
オペレーティングシステ� のシェルを使用してコマンドラインプログラ� を実行します。 name
を指定しない� �合、ステップ名はデフォルトでrun
コマンドで指定された文字列になります。
コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 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
:set -eo pipefail
を使用したフェイルファースト動作 :bash
及び組み込みのshell
のデフォルト。 Windows以外のプラットフォー� でオプションを指定しない� �合のデフォルトでもあります。- フェイルファーストをオプトアウトし、シェルのオプションにテンプレート文字列を指定して完全に制御することもできます。 たとえば、
bash {0}
とします。 - shライクのシェルは、スクリプトで実行された最後のコマンドの終了コードで終了します。これが、アクションのデフォルトの動作でもあります。 runnerは、この終了コードに基づいてステップのステータスを失敗/成功としてレポートします。
-
powershell
/pwsh
- 可能な� �合のフェイルファースト動作。
pwsh
およびpowershell
の組み込みシェルの� �合は、スクリプトの内容の前に$ErrorActionPreference = 'stop'
が付� されます。 - ここでは、アクションステータスがスクリプトの最後の終了コードを反� するように、PowerShellスクリプトに
if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }
を付� しています。 - 必要な� �合には、組み込みシェルを使用せずに、
pwsh -File {0}
やpowershell -Command "& '{0}'"
などのカスタ� シェルを指定すれば、いつでもオプトアウトすることができます。
- 可能な� �合のフェイルファースト動作。
-
cmd
- 各エラーコードをチェックしてそれぞれに対応するスクリプトを書く以外、フェイルファースト動作を完全にオプトインする方法はないようです。 デフォルトでその動作を指定することはできないため、この動作はスクリプトに記述する必要があります。
cmd.exe
は、実行した最後のプログラ� のエラーレベルで終了し、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: The GITHUB_TOKEN
expires when a job finishes or after a maximum of 24 hours. 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. A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based the combinations of the variables. For example, you can use a matrix strategy to test your code in multiple versions of a language or on multiple operating systems. For more information, see "Using a matrix for your jobs."
jobs.<job_id>.strategy.matrix
Use jobs.<job_id>.strategy.matrix
to define a matrix of different job configurations. Within your matrix, define one or more variables followed by an array of values. For example, the following matrix has a variable called version
with the value [10, 12, 14]
and a variable called os
with the value [ubuntu-latest, windows-latest]
:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
A job will run for each possible combination of the variables. In this example, the workflow will run six jobs, one for each combination of the os
and version
variables.
By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. The order of the variables in the matrix determines the order in which the jobs are created. The first variable you define will be the first job that is created in your workflow run. For example, the above matrix will create the jobs in the following order:
{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}
A matrix will generate a maximum of 256 jobs per workflow run. This limit applies to both GitHub Enterprise Server-hosted and self-hosted runners.
The variables that you define become properties in the matrix
context, and you can reference the property in other areas of your workflow file. In this example, you can use matrix.version
and matrix.os
to access the current value of version
and os
that the job is using. 詳細については、「コンテキスト」を参照してく� さい。
Example: Using a single-dimension matrix
You can specify a single variable to create a single-dimension matrix.
For example, the following workflow defines the variable version
with the values [10, 12, 14]
. The workflow will run three jobs, one for each value in the variable. Each job will access the version
value through the matrix.version
context and pass the value as node-version
to the actions/setup-node
action.
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
You can specify multiple variables to create a multi-dimensional matrix. A job will run for each possible combination of the variables.
For example, the following workflow specifies two variables:
- Two operating systems specified in the
os
variable - Three Node.js versions specified in the
version
variable
The workflow will run six jobs, one for each combination of the os
and version
variables. Each job will set the runs-on
value to the current os
value and will pass the current version
value to the actions/setup-node
action.
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@v2
with:
node-version: ${{ matrix.version }}
Example: Using contexts to create matrices
You can use contexts to create matrices. For more information about contexts, see "Contexts."
For example, the following workflow triggers on the repository_dispatch
event and uses information from the event payload to build the matrix. When a repository dispatch event is created with a payload like the one below, the matrix version
variable will have a value of [12, 14, 16]
. For more information about the repository_dispatch
trigger, see "Events that trigger workflows."
{
"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
Use jobs.<job_id>.strategy.matrix.include
to expand existing matrix configurations or to add new configurations. The value of include
is a list of objects.
For each object in the include
list, the key:value pairs in the object will be added to each of the matrix combinations if none of the key:value pairs overwrite any of the original matrix values. If the object cannot be added to any of the matrix combinations, a new matrix combination will be created instead. Note that the original matrix values will not be overwritten, but added matrix values can be overwritten.
For example, this matrix:
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
will result in six jobs with the following matrix combinations:
{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}
following this logic:
{color: green}
is added to all of the original matrix combinations because it can be added without overwriting any part of the original combinations.{color: pink, animal: cat}
addscolor:pink
only to the original matrix combinations that includeanimal: cat
. This overwrites thecolor: green
that was added by the previousinclude
entry.{fruit: apple, shape: circle}
addsshape: circle
only to the original matrix combinations that includefruit: apple
.{fruit: banana}
cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination.{fruit: banana, animal: cat}
cannot be added to any original matrix combination without overwriting a value, so it is added as an additional matrix combination. It does not add to the{fruit: banana}
matrix combination because that combination was not one of the original matrix combinations.
Example: Expanding configurations
For example, the following workflow will run six jobs, one for each combination of os
and node
. When the job for the os
value of windows-latest
and node
value of 16
runs, an additional variable called npm
with the value of 6
will be included in the job.
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
For example, this matrix will run 10 jobs, one for each combination of os
and version
in the matrix, plus a job for the os
value of windows-latest
and version
value of 17
.
jobs:
example_matrix:
strategy:
matrix:
os: [macos-latest, windows-latest, ubuntu-latest]
version: [12, 14, 16]
include:
- os: windows-latest
version: 17
If you don't specify any matrix variables, all configurations under include
will run. For example, the following workflow would run two jobs, one for each include
entry. This lets you take advantage of the matrix strategy without having a fully populated matrix.
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
To remove specific configurations defined in the matrix, use jobs.<job_id>.strategy.matrix.exclude
. An excluded configuration only has to be a partial match for it to be excluded. For example, the following workflow will run nine jobs: one job for each of the 12 configurations, minus the one excluded job that matches {os: macos-latest, version: 12, environment: production}
, and the two excluded jobs that match {os: windows-latest, version: 16}
.
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
You can control how job failures are handled with jobs.<job_id>.strategy.fail-fast
and jobs.<job_id>.continue-on-error
.
jobs.<job_id>.strategy.fail-fast
applies to the entire matrix. If jobs.<job_id>.strategy.fail-fast
is set to true
, GitHub Enterprise Server will cancel all in-progress and queued jobs in the matrix if any job in the matrix fails. This property defaults to true
.
jobs.<job_id>.continue-on-error
applies to a single job. If jobs.<job_id>.continue-on-error
is true
, other jobs in the matrix will continue running even if the job with jobs.<job_id>.continue-on-error: true
fails.
You can use jobs.<job_id>.strategy.fail-fast
and jobs.<job_id>.continue-on-error
together. For example, the following workflow will start four jobs. For each job, continue-on-error
is determined by the value of matrix.experimental
. If any of the jobs with continue-on-error: false
fail, all jobs that are in progress or queued will be cancelled. If the job with continue-on-error: true
fails, the other jobs will not be affected.
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
By default, GitHub Enterprise Server will maximize the number of jobs run in parallel depending on runner availability. To set the maximum number of jobs that can run simultaneously when using a matrix
job strategy, use jobs.<job_id>.strategy.max-parallel
.
For example, the following workflow will run a maximum of two jobs at a time, even if there are runners available to run all six jobs at once.
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
Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:
- GitHubホストランナーを使うなら、Ubuntuランナーを使わなければなりません。
- セルフホストランナーを使っているなら、ランナーとしてLinuxマシンを使い、Dockerをインストールしておかなければなりません。
Use jobs.<job_id>.container
to create a container to run any steps in a job that don't already specify a container. スクリプトアクションとコンテナアクションの両方を使うステップがある� �合、コンテナアクションは同じボリュー� マウントを使用して、同じネットワーク上にある兄弟コンテナとして実行されます。
container
を設定しない� �合は、コンテナで実行されるよう設定されているアクションを参照しているステップを除くすべてのステップが、runs-on
で指定したホストで直接実行されます。
Example: Running a job within a container
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
Use jobs.<job_id>.container.image
to define the Docker image to use as the container to run the action. The value can be the Docker Hub image name or a registry name.
jobs.<job_id>.container.credentials
If the image's container registry requires authentication to pull the image, you can use jobs.<job_id>.container.credentials
to set a map
of the username
and password
. この認証情� �は、docker login
コマンドに渡すものと同じ値です。
Example: Defining credentials for a container registry
container:
image: ghcr.io/owner/image
credentials:
username: ${{ github.actor }}
password: ${{ secrets.github_token }}
jobs.<job_id>.container.env
Use jobs.<job_id>.container.env
to set a map
of environment variables in the container.
jobs.<job_id>.container.ports
Use jobs.<job_id>.container.ports
to set an array
of ports to expose on the container.
jobs.<job_id>.container.volumes
Use jobs.<job_id>.container.volumes
to set an array
of volumes for the container to use. volumes (ボリュー� ) を使用すると、サービス間で、または1つのジョブのステップ間でデータを共有できます。 指定できるのは、名前付きDockerボリュー� 、匿名Dockerボリュー� 、またはホスト上のバインドマウントです。
ボリュー� を指定するには、ソースパスとターゲットパスを指定してく� さい。
<source>:<destinationPath>
.
<source>
は、ホストマシン上のボリュー� 名または絶対パス、<destinationPath>
はコンテナでの絶対パスです。
Example: Mounting volumes in a container
volumes:
- my_docker_volume:/volume_mount
- /data/my_data
- /source/directory:/destination/directory
jobs.<job_id>.container.options
Use jobs.<job_id>.container.options
to configure additional Docker container resource options. オプションの一覧は、「docker create
のオプション」を参照してく� さい。
Warning: The --network
option is not supported.
jobs.<job_id>.services
Note: If your workflows use Docker container actions, job containers, or service containers, then you must use a Linux runner:
- 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
If the image's container registry requires authentication to pull the image, you can use jobs.<job_id>.container.credentials
to set a map
of the username
and password
. この認証情� �は、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
のオプション」を参照してく� さい。
Warning: The --network
option is not supported.
フィルタパターンのチートシート
特別なキャラクタをパス、ブランチ、タグフィルタで利用できます。
*
ゼロ個以上のキャラクタにマッチしますが、/
にはマッチしません。 たとえば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 |