Skip to main content
ドキュメントには� �繁に更新が� えられ、その都度公開されています。本ページの翻訳はま� 未完成な部分があることをご了承く� さい。最新の情� �については、英語のドキュメンテーションをご参照く� さい。本ページの翻訳に問題がある� �合はこちらまでご連絡く� さい。

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2022-06-03. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの改善、新機能のためには、最新バージョンのGitHub Enterpriseにアップグレードしてく� さい。 アップグレードに関する支援については、GitHub Enterprise supportに連絡してく� さい。

GitHub Actionsのワークフロー構文

ここには以下の内容があります:

ワークフローは、1つ以上のジョブからなる設定可能な自動化プロセスです。 ワークフローの設定を定義するには、YAMLファイルを作成しなければなりません。

ノート: 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/, like releases/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, like releases/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/, like releases/10 (refs/heads/releases/10)
  • A tag named v2 (refs/tags/v2)
  • A tag whose name starts with v1., like v1.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, like beta/3-alpha (refs/releases/beta/3-alpha)
  • A tag named v2 (refs/tags/v2)
  • A tag whose name starts with v1., like v1.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/10releases/beta/mona へのプッシュで実行されますが、releases/10-alphareleases/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が始まり、job3job1job2が完了するまで待機します。

つまり、この例のジョブは逐次実行されるということです。

  1. job1
  2. job2
  3. job3

Example: Not requiring successful dependent jobs

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

この例では、job3は条件式のalways() を使っているので、job1job2が成功したかどうかにかかわらず、それらのジョブが完了したら常に実行されます。 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.

YAML
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}
すべてpwshPowerShell Coreです。 GitHubはスクリプト名に拡張子.ps1を追� します。pwsh -command ". '{0}'"
すべてpythonPythonのコマンドを実行します。python {0}
Linux / macOSsh非Windowsプラットフォー� においてシェルが提供されておらず、パス上でbashが見つからなかった� �合のフォールバック動作です。sh -e {0}
WindowscmdGitHubはスクリプト名に拡張子.cmdを追� し、{0}を置き換えます。%ComSpec% /D /E:ON /V:OFF /S /C "CALL "{0}"".
WindowspwshこれはWindowsで使われるデフォルトのシェルです。 PowerShell Coreです。 GitHubはスクリプト名に拡張子.ps1を追� します。 セルフホストのWindowsランナーにPowerShell Coreがインストールされていない� �合、その代わりにPowerShell Desktopが使われます。pwsh -command ". '{0}'".
WindowspowershellPowerShell 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_namemiddle_namelast_name) を定義します。 hello-worldアクションからは、これらの入力変数はINPUT_FIRST_NAMEINPUT_MIDDLE_NAMEINPUT_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を使うなら、以下の優先� �位� �のガイドラインを利用してく� さい。

  1. 必� �の引数をアクションのREADME中でドキュメント化し、CMD命令から除外してく� さい。
  2. argsを指定せずにアクションを利用できるよう、デフォルトを使ってく� さい。
  3. アクションが--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} adds color:pink only to the original matrix combinations that include animal: cat. This overwrites the color: green that was added by the previous include entry.
  • {fruit: apple, shape: circle} adds shape: circle only to the original matrix combinations that include fruit: 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

YAML
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-zA-Z0-9のみです。 たとえば、[0-9a-z]という範囲は任意の数字もしくは小文字にマッチします。 たとえば[CB]atCatあるいはBatにマッチし、[1-2]00100200にマッチします。
  • !: パターンの先� �に置くと、肯定のパターンを否定にします。 先� �のキャラクタではない� �合は、特別な意味を持ちません。

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/**/*.mddocsディレクトリ内にある.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