GitHub Actionsのワークフロー構文

ワークフロー用のYAML構文について

ワークフローファイルはYAML構文を使用し、ファイル拡張子が.ymlまたは.yamlである必要があります。 YAMLについて詳しくなく、学んでいきたい場合は、「Learn YAML in five minutes (Y分で学ぶYAML)」をお読みください。

ワークフローファイルは、リポジトリの.github/workflowsディレクトリに保存する必要があります。

name

ワークフローの名前。 GitHubでは、リポジトリのアクションページにワークフローの名前が表示されます。 nameを省略すると、GitHubはリポジトリのルートに対するワークフローファイルの相対パスをその値に設定します。

on

必須。 ワークフローをトリガーするGitHubイベントの名前。 指定できるのは、1つのイベントstring、複数イベントのarray、イベントtypesのarrayです。あるいは、ワークフローをスケジュールする、またはワークフロー実行を特定のファイルやタグ、ブランチ変更に限定するイベント設定mapも指定できます。 使用可能なイベントの一覧は、「ワークフローをトリガーするイベント」を参照してください。

1つのイベントを使用する例

# リポジトリ内の任意のブランチにコードがプッシュされたときにトリガーされる
on: push

イベントのリストを使用する例

# プッシュもしくはPull Requestイベントでワークフローをトリガーする
on: [push, pull_request]

アクティビティの種類もしくは設定を伴う複数のイベントを使用する例

イベントに対してアクティビティの種類もしくは設定を指定する必要がある場合、それぞれのイベントを個別に設定しなければなりません。 設定を持たないイベントも含め、すべてのイベントにはコロン (:)を追加しなければなりません。

on:
  # プッシュもしくはPull Requestでワークフローをトリガーする
  # ただしメインブランチの場合のみ
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  # page_buildとリリース作成イベントでもトリガーする
  page_build:
  release:
    types: # この設定は上記のpage_buildイベントには影響しない
      - created

on.<event_name>.types

ワークフローの実行をトリガーする特定のアクティビティ。 ほとんどの GitHub イベントは、2 つ以上のアクティビティタイプからトリガーされます。 たとえば、releaseリソースに対するイベントは、release が published、unpublished、created、edited、deleted、または prereleased の場合にトリガーされます。 typesキーワードを使用すると、ワークフローを実行させるアクティブの範囲を狭くすることができます。 webhook イベントをトリガーするアクティビティタイプが1つだけの場合、typesキーワードは不要です。

イベントtypesの配列を使用できます。 各イベントとそのアクティビティタイプの詳細については、「ワークフローをトリガーするイベント」を参照してください。

# Trigger the workflow on pull request activity
on:
  release:
    # Only use the types keyword to narrow down the activity types that will trigger your workflow.
    types: [published, created, edited]

on.<push|pull_request>.<branches|tags>

pushおよびpull_requestイベントを使用する場合、特定のブランチまたはタグで実行するワークフローを設定できます。 pull_requestでは、ベース上のブランチ及びタグだけが評価されます。 tagsもしくはbranchesだけを定義すると、定義されていないGit refに影響するイベントに対して、ワークフローが実行されません。

branches、branches-ignore、tags、および tags-ignoreのキーワードは、*と**のワイルドカード文字を使って複数のブランチやタグ名と一致させるglobパターンを受け付けます。 詳しい情報については、「フィルタパターンのチートシート」を参照してください。

ブランチとタグを含める例

branchesおよびtagsで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、branchesでmona/octocatとパターンを定義すると、refs/heads/mona/octocatというGit refにマッチします。 releases/**というパターンは、refs/heads/releases/10というGit refにマッチします。

on:
  push:
    # refs/heads とマッチするパターンのシークエンス
    branches:    
      # メインブランチのプッシュイベント
      - main
      # refs/heads/mona/octocat に一致するブランチにイベントをプッシュする
      - 'mona/octocat'
      # refs/heads/releases/10 に一致するブランチにイベントをプッシュする
      - 'releases/**'
    # refs/tags とマッチするパターンのシーケンス
    tags:        
      - v1             # イベントを v1 タグにプッシュする
      - v1.*           # イベントを v1.0、v1.1、および v1.9 タグにプッシュする

ブランチとタグを無視する例

パターンがbranches-ignoreまたはtags-ignoreとマッチする場合は常に、ワークフローは実行されません。 branches-ignoreおよびtags-ignoreで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、branchesでmona/octocatとパターンを定義すると、refs/heads/mona/octocatというGit refにマッチします。 branchesのパターンreleases/**-alphaは、refs/releases/beta/3-alphaというGit refにマッチします。

on:
  push:
    # refs/heads にマッチするパターンのシーケンス
    branches-ignore:
      # refs/heads/mona/octocat にマッチするブランチにイベントをプッシュする
      - 'mona/octocat'
      # refs/heads/releases/beta/3-alpha refs/heads/mona/octocat にマッチするブランチにイベントをプッシュする
      - 'releases/**-alpha'
    # refs/heads にマッチするパターンのシーケンス
    tags-ignore:
      - v1.*           # イベントを v1.0、v1.1、v1.9 タグにプッシュする

ブランチとタグを除外する

タグやブランチへのプッシュおよびプルリクエストでワークフローが実行されることを防ぐために、2 種類のフィルタを使うことができます。

• branches または branches-ignore - ワークフロー内の同じイベントに対して、branches と branches-ignore のフィルタを両方使うことはできません。 肯定のマッチに対してブランチをフィルタし、ブランチを除外する必要がある場合は、branches フィルタを使います。 ブランチ名のみを除外する必要がある場合は、branches-ignore フィルタを使います。
• tags または tags-ignore - ワークフロー内の同じイベントに対して、tags と tags-ignore のフィルタを両方使うことはできません。 肯定のマッチに対してタグをフィルタし、タグを除外する必要がある場合は、tags フィルタを使います。 タグ名のみを除外する必要がある場合は、tags-ignore フィルタを使います。

肯定と否定のパターンを使用する例

"!" の文字を使うことで、tags と branches を除外できます。 パターンを定義する順序により、結果に違いが生じます。

• 肯定のマッチングパターンの後に否定のマッチングパターン ("!" のプレフィクス) を定義すると、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>.paths

push および pull_request イベントを使用する場合、1 つ以上の変更されたファイルが paths-ignore にマッチしない場合や、1 つ以上の変更されたファイルが、設定された paths にマッチする場合にワークフローを実行するように設定できます。 タグへのプッシュに対して、パスのフィルタは評価されません。

paths-ignore および paths キーワードは、* と ** のワイルドカード文字を使って複数のパス名と一致させる glob パターンを受け付けます。 詳しい情報については、「フィルタパターンのチートシート」を参照してください。

パスを無視する例

When all the path names match patterns in paths-ignore, the workflow will not run. GitHub は、paths-ignore に定義されているパターンを、パス名に対して評価します。 以下のパスフィルタを持つワークフローは、リポジトリのルートにある docsディレクトリ外のファイルを少なくとも1つ含むpushイベントでのみ実行されます。

on:
  push:
    paths-ignore:
    - 'docs/**'

パスを含む例

pathsフィルタのパターンにマッチするパスが1つでもあれば、ワークフローは実行されます。 JavaScriptファイルをプッシュしたときにビルドを走らせるには、ワイルドカードパターンが使えます。

on:
  push:
    paths:
    - '**.js'

パスの除外

パスは、2種類のフィルタで除外できます。 これらのフィルタをワークフロー内の同じイベントで両方使うことはできません。

• paths-ignore - パス名を除外する必要だけがある場合にはpaths-ignoreフィルタを使ってください。
• paths - 肯定のマッチのパスとパスの除外のフィルタが必要な場合はpathsフィルタを使ってください。

肯定と否定のパターンを使用する例

!文字を使って、pathsを除外できます。 パターンを定義する順序により、結果に違いが生じます:

• 肯定のマッチの後に否定のマッチングパターン（!がプレフィックスされている）を置くと、パスが除外されます。
• 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、パスを再び含めます。

この例は、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の比較

フィルタは、変更されたファイルをpaths-ignoreあるいはpathsリストに対して評価することによって、ワークフローを実行すべきか判断します。 ファイルが変更されていない場合、ワークフローは実行されません。

GitHubはプッシュに対してはツードットdiff、プルリクエストに対してはスリードットdiffを使って変更されたファイルのリストを生成します。

• Pull Request： スリードットdiffは、トピックブランチの最新バージョンとトピックブランチがベースブランチと最後に同期されたコミットとの比較です。
• 既存のブランチへのプッシュ： ツードットdiffは、headとベースのSHAを互いに直接比較します。
• 新しいブランチへのプッシュ： 最も深いプッシュの先祖の親に対するツードットdiffです。

詳しい情報については「プルリクエスト中のブランチの比較について」を参照してください。

on.schedule

POSIX クーロン構文を使用して、特定の UTC 時間にワークフローを実行できるようスケジュール設定できます。 スケジュールしたワークフローは、デフォルトまたはベースブランチの直近のコミットで実行されます。 スケジュールされたワークフローを実行できる最短の間隔は、5 分ごとに 1 回です。

この例では、ワークフローは毎日UTCの5:30と17:30にトリガーされます。

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '*/30 5,17 * * *'

cron構文に関する詳しい情報については、「ワークフローをトリガーするイベント」を参照してください。

env

ワークフロー中のすべてのジョブのステップから利用できる環境変数のmapです。 1つのジョブのステップ、あるいは1つのステップからだけ利用できる環境変数を設定することもできます。 詳しい情報については「jobs.<job_id>.env」及び「jobs.<job_id>.steps[*].envを参照してください。

同じ名前で複数の環境変数が定義されている場合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。

サンプル

env:
  SERVER: production

defaults

デフォルト設定のmapで、ワークフロー中のすべてのジョブに適用されます。 1つのジョブだけで利用できるデフォルト設定を設定することもできます。 詳しい情報についてはjobs.<job_id>.defaultsを参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

defaults.run

ワークフロー中のすべてのrunステップに対するデフォルトのshell及びworking-directoryオプションを提供することができます。 1つのジョブだけで利用できるrunのデフォルト設定を設定することもできます。 詳しい情報についてはjobs.<job_id>.defaults.runを参照してください。 このキーワード中では、コンテキストや式を使うことはできません。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

サンプル

defaults:
  run:
    shell: bash
    working-directory: scripts

jobs

1つのワークフロー実行は、1つ以上のジョブからなります。 デフォルトでは、ジョブは並行して実行されます。 ジョブを逐次的に実行するには、jobs.<job_id>.needsキーワードを使用して他のジョブに対する依存関係を定義します。

それぞれのジョブは、runs-onで指定されたランナー環境で実行されます。

ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳細については、GitHub ホストランナーの「使用制限と支払い」、およびセルフホストランナーの使用制限については「セルフホストランナーについて」を参照してください。

ワークフローの実行中で動作しているジョブのユニークな識別子が必要な場合は、GitHub APIが利用できます。 詳しい情報については、「ワークフロージョブ」を参照してください。

jobs.<job_id>

各ジョブには、対応するIDがあります。 job_idキーは文字列型で、その値はジョブの設定データのマップとなるものです。 <job_id>は、jobsオブジェクトごとに一意の文字列に置き換える必要があります。 <job_id>は、英字または_で始める必要があり、英数字と-、_しか使用できません。

サンプル

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

GitHubに表示されるジョブの名前。

jobs.<job_id>.needs

このジョブの実行前に正常に完了する必要があるジョブを示します。 文字列型または文字列の配列です。 1つのジョブが失敗した場合、失敗したジョブを続行するような条件式を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。

依存対象のジョブの成功が必要になる例

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

この例では、job1が正常に完了してからjob2が始まり、job3はjob1とjob2が完了するまで待機します。

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

1. job1
2. job2
3. job3

依存対象のジョブの成功が必要ではない例

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

この例では、job3は条件式のalways() を使っているので、job1とjob2が成功したかどうかにかかわらず、それらのジョブが完了したら常に実行されます。 詳しい情報については「コンテキストと式構文」を参照してください。

jobs.<job_id>.runs-on

必須。 ジョブが実行されるマシンの種類。 マシンはGitHubホストランナーあるいはセルフホストランナーのいずれかです。

GitHubホストランナー

GitHubホストランナーを使う場合、それぞれのジョブはruns-onで指定された仮想環境の新しいインスタンスで実行されます。

利用可能なGitHubホストランナーの種類は以下のとおりです。

サンプル

runs-on: ubuntu-latest

詳しい情報については「GitHubホストランナーの仮想環境」を参照してください。

セルフホストランナー

ジョブでセルフホストランナーを指定するには、ワークフローファイル中でセルフホストランナーのラベルでruns-onを設定してください。

すべてのセルフホストランナーはself-hostedラベルを持ち、self-hostedラベルだけを提供すれば任意のセルフホストランナーを選択できます。 あるいは、特定のオペレーティングシステムやシステムアーキテクチャのラベルといった追加のラベルと合わせて配列中でself-hostedを使い、指定した種類のランナーだけを選択することもできます。

サンプル

runs-on: [self-hosted, linux]

詳しい情報については「セルフホストランナーについて」及び「ワークフロー内でのセルフホストランナーの利用」を参照してください。

jobs.<job_id>.outputs

ジョブからの出力のmapです。 ジョブの出力は、そのジョブに依存しているすべての下流のジョブから利用できます。 ジョブの依存関係の定義に関する詳しい情報についてはjobs.<job_id>.needsを参照してください。

ジョブの出力は文字列であり、式を含むジョブの出力は、それぞれのジョブの終了時にランナー上で評価されます。 シークレットを含む出力はランナー上で編集され、GitHub Actionsには送られません。

依存するジョブでジョブの出力を使いたい場合には、needsコンテキストが利用できます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

サンプル

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

ジョブ中のすべてのステップに適用されるデフォルト設定のmap。 ワークフロー全体に対してデフォルト設定を設定することもできます。 詳しい情報についてはdefaultsを参照してください。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

jobs.<job_id>.defaults.run

ジョブ中のすべてのrunステップにデフォルトのshellとworking-directoryを提供します。 このセクションではコンテキストと式は許されていません。

ジョブ中のすべてのrunステップにデフォルトのshell及びworking-directoryを提供できます。 ワークフロー全体についてrunのためのデフォルト設定を設定することもできます。 詳しい情報についてはjobs.defaults.runを参照してください。 このキーワード中では、コンテキストや式を使うことはできません。

同じ名前で複数のデフォルトの設定が定義されている場合、GitHubは最も具体的なデフォルト設定を使用します。 たとえば、ジョブで定義されたデフォルト設定は、同じ名前を持つワークフローで定義されたデフォルト設定をオーバーライドします。

サンプル

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: scripts

jobs.<job_id>.if

条件文のifを使って、条件が満たされなければジョブを実行しないようにできます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。

if条件の中で式を使う場合、式構文(${{ }})を省略できます。これは、式に演算子が含まれていない場合、GitHubが自動的にif条件を式として評価するためです。 式に演算子が含まれている場合、明示的に評価されるようマークするためにその式を${{ }}で囲まなければなりません。 詳しい情報については「GitHub Actionsのコンテキストと式構文」を参照してください。

jobs.<job_id>.steps

1つのジョブには、steps (ステップ) と呼ばれる一連のタスクがあります。 ステップでは、コマンドを実行する、設定タスクを実行する、あるいはリポジトリやパブリックリポジトリ、Dockerレジストリで公開されたアクションを実行することができます。 すべてのステップでアクションを実行するとは限りませんが、すべてのアクションはステップとして実行されます。 各ステップは、ランナー環境のそれ自体のプロセスで実行され、ワークスペースとファイルシステムにアクセスします。 ステップはそれ自体のプロセスで実行されるため、環境変数を変更しても、ステップ間では反映されません。 GitHubには、ジョブを設定して完了するステップが組み込まれています。

ワークフローの利用限度内であれば、実行するステップ数に限度はありません。 詳細については、GitHub ホストランナーの「使用制限と支払い」、およびセルフホストランナーの使用制限については「セルフホストランナーについて」を参照してください。

サンプル

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
    - name: Print a greeting
      env:
        MY_VAR: Hi there! My name is
        FIRST_NAME: Mona
        MIDDLE_NAME: The
        LAST_NAME: Octocat
      run: |
        echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

ステップの一意の識別子。 idを使って、コンテキストのステップを参照することができます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

jobs.<job_id>.steps[*].if

条件文のifを使って、条件が満たされなければステップを実行しないようにできます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。

if条件の中で式を使う場合、式構文(${{ }})を省略できます。これは、式に演算子が含まれていない場合、GitHubが自動的にif条件を式として評価するためです。 式に演算子が含まれている場合、明示的に評価されるようマークするためにその式を${{ }}で囲まなければなりません。 詳しい情報については「GitHub Actionsのコンテキストと式構文」を参照してください。

コンテキストの使用例

このステップは、イベントの種類がpull_requestでイベントアクションがunassignedの場合にのみ実行されます。

steps:
 - name: My first step
   if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
   run: echo This event is a pull request that had an assignee removed.

ステータスチェック関数の使用例

my backup stepは、ジョブの前のステップが失敗した場合にのみ実行されます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

steps:
  - name: My first step
    uses: monacorp/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

jobs.<job_id>.steps[*].name

GitHubで表示されるステップの名前。

jobs.<job_id>.steps[*].uses

ジョブでステップの一部として実行されるアクションを選択します。 アクションとは、再利用可能なコードの単位です。 ワークフロー、パブリックリポジトリ、または公開されているDockerコンテナイメージと同じリポジトリで定義されているアクションを使用できます。

Git ref、SHA、またはDockerタグ番号を指定して、使用しているアクションのバージョンを含めることを強く推奨します。 バージョンを指定しないと、アクションのオーナーがアップデートを公開したときに、ワークフローが中断したり、予期せぬ動作をしたりすることがあります。

• リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
• 特定のメジャーアクションバージョンを使用すると、互換性を維持したまま重要な修正とセキュリティパッチを受け取ることができます。 ワークフローが引き続き動作することも保証できます。
• アクションのデフォルトブランチを使用すると便利なこともありますが、別のユーザが破壊的変更を加えた新しいメジャーバージョンをリリースすると、ワークフローが動作しなくなる場合があります。

入力が必要なアクションもあり、入力をwithキーワードを使って設定する必要があります。 必要な入力を判断するには、アクションのREADMEファイルをお読みください。

アクションは、JavaScriptのファイルもしくはDockerコンテナです。 使用するアクションがDockerコンテナの場合は、Linux環境で実行する必要があります。 詳細についてはruns-onを参照してください。

バージョンされたアクションを使用する例

steps:    
  # 特定のコミットを参照
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # リリースのメジャーバージョンを参照
  - uses: actions/setup-node@v1
  # リリースのマイナーバージョンを参照
  - uses: actions/setup-node@v1.2
  # ブランチを参照
  - uses: actions/setup-node@main

パブリックアクションを使用する例

{owner}/{repo}@{ref}

パブリックGitHubリポジトリのブランチ、ref、SHAを指定できます。

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@1.0.0
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

サブディレクトリのパブリックアクションを使用する例

{owner}/{repo}/{path}@{ref}

パブリックGitHubリポジトリで特定のブランチ、ref、SHAにあるサブディレクトリ。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

ワークフローと同じリポジトリにあるアクションを使用する例

./path/to/dir

ワークフローのリポジトリにあるアクションを含むディレクトリのパス。 アクションを使用する前にリポジトリをチェックアウトする必要があります。

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Use local my-action
        uses: ./.github/actions/my-action

Docker Hubアクションを使用する例

docker://{image}:{tag}

Docker Hubで公開されているDockerイメージ。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Dockerパブリックレジストリアクションを使用する例

docker://{host}/{image}:{tag}

パブリックレジストリのDockerイメージ。 この例では、gcr.io にある Google Container Registry を使用しています。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

ワークフローとは異なるプライベートリポジトリ内でのアクションの使用例

ワークフローはプライベートリポジトリをチェックアウトし、アクションをローカルで参照する必要があります。

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.GITHUB_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コマンドで指定された文字列になります。

コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 詳しい情報については「特定のシェルの利用」を参照してください。

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

特定のシェルを使用する

shellキーワードを使用して、ランナーのオペレーティングシステムのデフォルトシェルを上書きできます。 組み込みのshellキーワードを使用するか、カスタムセットのシェルオプションを定義することができます。

bashを使用してスクリプトを実行する例

steps:
  - name: Display the path
    run: echo $PATH
    shell: bash

Windowsのcmdを使用してスクリプトを実行する例

steps:
  - name: Display the path
    run: echo %PATH%
    shell: cmd

PowerShell Coreを使用してスクリプトを実行する例

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: pwsh

PowerShell Desktopを使用してスクリプトを実行する例

steps:
  - name: Display the path
    run: echo ${env:PATH}
    shell: powershell

Python 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）は、ランナーにインストールされていなければなりません。

GitHubホストランナーに含まれるソフトウェアに関する情報については「GitHubホストランナーの仕様」を参照してください。

終了コードとエラーアクションの環境設定

組み込みの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: monacorp/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: monacorp/action-name@main
    with:
      entrypoint: /a/different/executable

entrypointキーワードはDockerコンテナアクションで使われることを意図したものですが、入力を定義しないJavaScriptのアクションでも使うことができます。

jobs.<job_id>.steps[*].env

ランナー環境でステップが使う環境変数を設定します。 ワークフロー全体あるいはジョブのための環境変数を設定することもできます。 詳しい情報については「env」及び「jobs.<job_id>.env」を参照してください。

同じ名前で複数の環境変数が定義されている場合、GitHubは最も具体的な環境変数を使用します。 たとえば、ステップ中で定義された環境変数は、ジョブやワークフローの同じ名前の変数をステップの実行の間オーバーライドします。 ジョブで定義された変数は、そのジョブの実行の間はワークフローで定義された同じ名前の変数をオーバーライドします。

パブリックなアクションは、READMEファイル中で期待する環境変数を指定できます。 環境変数に秘密情報を設定しようとしている場合、秘密情報はsecretsコンテキストを使って設定しなければなりません。 詳しい情報については「環境変数の利用」及び「GitHub Actionsのコンテキストと式構文」を参照してください。

サンプル

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

jobs.<job_id>.strategy

strategy (戦略) によって、ジョブのビルドマトリクスが作成されます。 それぞれのジョブを実行する様々なバリエーションを定義できます。

jobs.<job_id>.strategy.matrix

様々なジョブの設定のマトリックスを定義できます。 マトリックスによって、単一のジョブの定義内の変数の置き換えを行い、複数のジョブを作成できるようになります。 たとえば、マトリックスを使って複数のサポートされているバージョンのプログラミング言語、オペレーティングシステム、ツールに対するジョブを作成できます。 マトリックスは、ジョブの設定を再利用し、設定した各マトリクスに対してジョブを作成します。

ジョブマトリックスは、ワークフローの実行ごとに最大で256のジョブを生成できます。 この制限は、セルフホストランナーにも適用されます。

matrix内で定義した各オプションは、キーと値を持ちます。 定義したキーはmatrixコンテキスト中のプロパティとなり、ワークフローファイルの他のエリア内のプロパティを参照できます。 たとえば、オペレーティングシステムの配列を含むosというキーを定義したなら、matrix.osプロパティをruns-onキーワードの値として使い、それぞれのオペレーティングシステムに対するジョブを作成できます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

matrixを定義する順序は意味を持ちます。 最初に定義したオプションは、ワークフロー中で最初に実行されるジョブになります。

複数のバージョンの Node.js を使用して実行する例

設定オプションに配列を指定すると、マトリクスを指定できます。 たとえばランナーがNode.jsのバージョン6、8、10,をサポートしている場合、これらのバージョンの配列をmatrixで指定できます。

この例では、nodeキーにNode.jsの3つのバージョンの配列を設定することによって、3つのジョブのマトリクスを作成します。 このマトリックスを使用するために、この例ではmatrix.nodeコンテキストプロパティをsetup-nodeアクションの入力パラメータであるnode-versionに設定しています。 その結果、3 つのジョブが実行され、それぞれが異なるバージョンのNode.js を使用します。

strategy:
  matrix:
    node: [6, 8, 10]
steps:
  # GitHubホストランナーで使われるnodeのバージョンの設定
  - uses: actions/setup-node@v1
    with:
      # 設定するNode.jsのバージョン
      node-version: ${{ matrix.node }}

GitHubホストランナーを使う場合にNode.jsのバージョンを設定する方法としては、setup-nodeアクションをおすすめします。 詳しい情報についてはsetup-nodeアクションを参照してください。

複数のオペレーティングシステムで実行する例

複数のランナーオペレーティングシステムでワークフローを実行するマトリックスを作成できます。 複数のマトリックス設定を指定することもできます。 この例では、6つのジョブのマトリックスを作成します。

• 配列osで指定された2つのオペレーティングシステム
• 配列nodeで指定された3つのバージョンのNode.js

オペレーティングシステムのマトリックスを定義する際には、runs-onの値を、定義したmatrix.osコンテキストのプロパティに設定しなければなりません。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [6, 8, 10]
steps:
  - uses: actions/setup-node@v1
    with:
      node-version: ${{ matrix.node }}

GitHub ホストランナーでサポートされている設定オプションについては、「GitHub の仮想環境」を参照してください。

組み合わせに追加の値が含まれる例

既存のビルドマトリクスジョブに、設定オプションを追加できます。 たとえば、windows-latest を使うジョブでnode のバージョン 4 を実行しているときに、npm の特定のバージョンを使いたい場合は、include を使って追加のオプションを指定できます。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [4, 6, 8, 10]
    include:
      # includes a new variable of npm with a value of 2
      # for the matrix leg matching the os and version
      - os: windows-latest
        node: 4
        npm: 2

新しい組み合わせを含む例

includeを使って新しいジョブを追加し、マトリックスを構築できます。 マッチしなかったincludeの設定があれば、マトリックスに追加されます。 たとえば、nodeのバージョン12を使って複数のオペレーティングシステム上でビルドを行い、追加で実験的なジョブをUbuntu上でnodeバージョン13で行いたいなら、includeを使ってこの追加のジョブを指定できます。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    node: [12]
    os: [macos-latest, windows-latest, ubuntu-18.04]
    include:
      - node: 13
        os: ubuntu-18.04
        experimental: true

マトリクスから設定を除外する例

exclude オプションを使って、ビルドマトリクスに定義されている特定の設定を削除できます。 exclude を使うと、ビルドマトリクスにより定義されたジョブが削除されます。 ジョブの数は、指定する配列に含まれるオペレーティングシステム (os) の外積から、任意の減算 (exclude) で引いたものです。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [4, 6, 8, 10]
    exclude:
      # excludes node 4 on macOS
      - os: macos-latest
        node: 4

マトリックスで環境変数を使用する

それぞれのテストの組み合わせに、includeキーを使ってカスタムの環境変数を追加できます。 そして、後のステップでそのカスタムの環境変数を参照できます。

この例では、node-versionに対するマトリクスのエントリは、それぞれ環境変数のsite及びdatacenterに異なる値を使うように設定されています。 そしてEcho site detailsステップはenv: ${{ matrix.env }}を使ってカスタム変数を参照しています。

name: Node.js CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
       include:
         - node-version: 10.x
           site: "prod"
           datacenter: "site-a"
         - node-version: 12.x
           site: "dev"
           datacenter: "site-b"
    steps:
      - name: Echo site details
        env:
          SITE: ${{ matrix.site }}
          DATACENTER: ${{ matrix.datacenter }}
        run: echo $SITE $DATACENTER

jobs.<job_id>.strategy.fail-fast

trueに設定すると、いずれかのmatrixジョブが失敗した場合にGitHubは進行中のジョブをすべてキャンセルします。 デフォルト: true

jobs.<job_id>.strategy.max-parallel

matrixジョブ戦略を使用するとき、同時に実行できるジョブの最大数。 デフォルトでは、GitHubはGitHubがホストしている仮想マシン上で利用できるrunnerに応じてできるかぎりの数のジョブを並列に実行します。

strategy:
  max-parallel: 2

jobs.<job_id>.continue-on-error

ジョブが失敗した時に、ワークフローの実行が失敗にならないようにします。 trueに設定すれば、ジョブが失敗した時にワークフローの実行が次へ進めるようになります。

失敗した特定のマトリックスジョブがワークフローの実行を失敗させないようにする例

ジョブマトリックス中の特定のジョブが失敗しても、ワークフローの実行が失敗にならないようにすることができます。 たとえば、nodeが13に設定された実験的なジョブが失敗しても、ワークフローの実行を失敗させないようにしたいとしましょう。

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [11, 12]
    os: [macos-latest, ubuntu-18.04]
    experimental: [false]
    include:
      - node: 13
        os: ubuntu-18.04
        experimental: true

jobs.<job_id>.container

ジョブの中で、まだコンテナを指定していない手順を実行するコンテナ。 スクリプトアクションとコンテナアクションの両方を使うステップがある場合、コンテナアクションは同じボリュームマウントを使用して、同じネットワーク上にある兄弟コンテナとして実行されます。

containerを設定しない場合は、コンテナで実行されるよう設定されているアクションを参照しているステップを除くすべてのステップが、runs-onで指定したホストで直接実行されます。

サンプル

jobs:
  my_job:
    container:
      image: node:10.16-jessie
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1

コンテナイメージのみを指定する場合、imageは省略できます。

jobs:
  my_job:
    container: node:10.16-jessie

jobs.<job_id>.container.image

アクションを実行するコンテナとして使用するDockerイメージ。 この値には、Docker Hubのイメージ名もしくはレジストリ名が指定できます。

jobs.<job_id>.container.credentials

イメージのコンテナレジストリがイメージをプルするために認証を要求するなら、credentialsにusernameとpasswordのmapをセットして利用できます。 この認証情報は、docker loginコマンドに渡すものと同じ値です。

サンプル

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.ghcr_token }}

jobs.<job_id>.container.env

コンテナ中の環境変数のmapを設定します。

jobs.<job_id>.container.ports

コンテナで公開するポートのarrayを設定します。

jobs.<job_id>.container.volumes

使用するコンテナにボリュームのarrayを設定します。 volumes (ボリューム) を使用すると、サービス間で、または1つのジョブのステップ間でデータを共有できます。 指定できるのは、名前付きDockerボリューム、匿名Dockerボリューム、またはホスト上のバインドマウントです。

ボリュームを指定するには、ソースパスとターゲットパスを指定してください。

<source>:<destinationPath>.

<source>は、ホストマシン上のボリューム名または絶対パス、<destinationPath>はコンテナでの絶対パスです。

サンプル

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

追加のDockerコンテナリソースのオプション。 オプションの一覧は、「docker createのオプション」を参照してください。

jobs.<job_id>.services

ワークフロー中のジョブのためのサービスコンテナをホストするために使われます。 サービスコンテナは、データベースやRedisのようなキャッシュサービスの作成に役立ちます。 ランナーは自動的にDockerネットワークを作成し、サービスコンテナのライフサイクルを管理します。

コンテナを実行するようにジョブを設定した場合、あるいはステップがコンテナアクションを使う場合は、サービスもしくはアクションにアクセスするためにポートをマップする必要はありません。 Dockerは自動的に、同じDockerのユーザ定義ブリッジネットワーク上のコンテナ間のすべてのポートを公開します。 サービスコンテナは、ホスト名で直接参照できます。 ホスト名は自動的に、ワークフロー中のサービスに設定したラベル名にマップされます。

ランナーマシン上で直接実行されるようにジョブを設定し、ステップがコンテナアクションを使わないのであれば、必要なDockerサービスコンテナのポートはDockerホスト（ランナーマシン）にマップしなければなりません サービスコンテナには、localhostとマップされたポートを使ってアクセスできます。

ネットワーキングサービスコンテナ間の差異に関する詳しい情報については「サービスコンテナについて」を参照してください。

localhostを使用する例

この例では、nginxとredisという2つのサービスを作成します。 Dockerホストのポートを指定して、コンテナのポートを指定しなかった場合、コンテナのポートは空いているポートにランダムに割り当てられます。 GitHubは、割り当てられたコンテナポートを${{job.services.<service_name>.ports}}コンテキストに設定します。 以下の例では、サービスコンテナのポートへは${{ job.services.nginx.ports['8080'] }} 及び${{ job.services.redis.ports['6379'] }} コンテキストでアクセスできます。

services:
  nginx:
    image: nginx
    # Dockerホストのポート8080をnginxコンテナのポート80にマップする
    ports:
      - 8080:80
  redis:
    image: redis
    # Dockerホストのポート6379をRedisコンテナのランダムな空きポートにマップする
    ports:
      - 6379/tcp

jobs.<job_id>.services.<service_id>.image

アクションを実行するサービスコンテナとして使用するDockerイメージ。 この値には、Docker Hubのイメージ名もしくはレジストリ名が指定できます。

jobs.<job_id>.services.<service_id>.credentials

イメージのコンテナレジストリがイメージをプルするために認証を要求するなら、credentialsにusernameとpasswordのmapをセットして利用できます。 この認証情報は、docker loginコマンドに渡すものと同じ値です。

サンプル

services:
  myservice1: 
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.ghcr_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のオプション」を参照してください。

フィルタパターンのチートシート

特別なキャラクタをパス、ブランチ、タグフィルタで利用できます。

• *ゼロ個以上のキャラクタにマッチしますが、/にはマッチしません。 たとえばOcto*はOctocatにマッチします。
• **ゼロ個以上の任意のキャラクタにマッチします。
• ?: ゼロ個もしくは1個のキャラクタにマッチします。 たとえばOctoc?tはOctocatにマッチします。
• +: 直前の文字の 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

ブランチ、タグ、およびパスフィルタの文法に関する詳しい情報については、「on.<push|pull_request>.<branches|tags>」および「on.<push|pull_request>.paths」を参照してください。

ブランチやタグにマッチするパターン

ファイルパスにマッチするパターン

パスパターンはパス全体にマッチしなければならず、リポジトリのルートを出発点とします。