GitHub Actionsのワークフロー構文

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

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

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

name

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

on

ワークフローを自動的にトリガーするには、onを使ってワークフローの実行を引き起こせるイベントを定義してください。 使用可能なイベントの一覧は、「ワークフローをトリガーするイベント」を参照してください。

ワークフローをトリガーする単一もしくは複数のイベントを定義したり、あるいはタイムスケジュールを設定したりできます。 ワークフローの実行を、特定のファイル、タグ、ブランチが変更されたときにだけ生じるように制限することもできます。 これらのオプションは、以下のセクションで説明されています。

単一イベントの利用

たとえば、以下のonの値を持つワークフローは、ワークフローのリポジトリの任意のブランチにプッシュが行われたときに実行されます。

on: push

複数イベントの利用

単一のイベントもしくは複数のイベントを指定できます。 たとえば、以下のonの値を持つワークフローは、リポジトリ内の任意のブランチにプッシュが行われたとき、あるいは誰かがリポジトリをフォークした時に実行されます。

on: [push, fork]

複数のイベントを指定した場合、ワークフローがトリガされるのに必要なのはそれらのイベントの中の1つだけです。 ワークフローをトリガーする複数のイベントが同時に生じた場合、複数のワークフローの実行がトリガーされます。

アクティビティタイプの利用

一部のイベントは、ワークフローを実行すべきときを詳細に制御できるようにしてくれるアクティビティタイプを持ちます。 on.<event_name>.typesを使って、ワークフローの実行をトリガーするイベントアクティビティのタイプを定義してください。

たとえば、issue_commentイベントはcreated、edited、deletedというアクティビティタイプを持ちます。 ワークフローがlabelイベントでトリガーされるなら、それはラベルが作成、編集、削除されたときに実行されます。 labelイベントにcreatedアクティビティタイプを指定したなら、ワークフローはラベルが作成されたときに実行され、ラベルが編集あるいは削除されたときには実行されません。

on:
  label:
    types:
      - created

複数のアクティビティタイプを指定した場合、ワークフローのトリガーを引き起こすのに必要なのはそれらのイベントアクティビティタイプの1つだけです。 ワークフローに対するトリガーになるイベントアクティビティタイプが複数同時に発生した場合、複数のワークフローの実行がトリガーされます。 たとえば、以下のワークフローはIssueがオープンされるかラベル付けされたときにトリガーされます。 2つのラベルを付けたIssueがオープンされた場合、Issueのオープンイベントに対して1つ、そして2つのIssueのラベル付けのイベントに対して2つ、合計3つのワークフローの実行が開始されます。

on:
  issues:
    types:
      - opened
      - labeled

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

フィルタの利用

一部のイベントは、ワークフローを実行すべきときを詳細に制御できるようにしてくれるフィルタを持ちます。

たとえばpushイベントはbranchesフィルタを持ち、これは任意のプッシュではなく、branchesフィルタにマッチするブランチへのプッシュが生じたときにのみワークフローが実行されるようにします。

on:
  push:
    branches:
      - main
      - 'releases/**'

複数のイベントでのアクティビティタイプとフィルタの利用

イベントに対してアクティビティタイプもしくはフィルタを指定し、ワークフローが複数のイベントをトリガーするなら、それぞれのイベントは個別に設定しなければなりません。 設定を持たないイベントも含め、すべてのイベントにはコロン (:)を追加しなければなりません。

たとえば、以下のon値を持つワークフローは、次の場合に実行されます。

• ラベルが作成された
• リポジトリのmainブランチにプッシュが行われた
• GitHub Pagesが有効化されたブランチにプッシュが行われた

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

on.<event_name>.typesを使って、ワークフローの実行をトリガーするアクティビティの種類を定義してください。 ほとんどの GitHub イベントは、2 つ以上のアクティビティタイプからトリガーされます。 たとえば、labelはラベルのcreated、edited、deletedによってトリガーされます。 typesキーワードを使用すると、ワークフローを実行させるアクティブの範囲を狭くすることができます。 webhook イベントをトリガーするアクティビティタイプが1つだけの場合、typesキーワードは不要です。

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

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

pull_request及びpull_request_targetイベントを使う場合、特定のブランチをターゲットとするPull Requestに対してだけ実行されるようにワークフローを設定できます。

ブランチ名のパターンを含めたい場合、あるいはぶらん名のパターンを含めるとともに除外もしたい場合に、branchesフィルタを使ってください。 ブランチ名のパターンを除外のみしたい場合にbranches-ignoreフィルタを使ってください。 branchesとbranches-ignoreを1つのワークフロー内の同じイベントに使うことはできません。

branches/branches-ignoreとpathsの両方を定義した場合、ワークフローはどちらのフィルタも満たされた場合にのみ実行されます。

branches及びbranches-ignoreキーワードは、複数のブランチ名にマッチさせるために*、**、+、?、!などの文字を使うglobパターンを受け付けます。 これらの文字のいずれかを含む名前に対してリテラルの一致をさせたい場合には、これらの特殊文字を\でエスケープしなければなりません。 globパターンに関する詳しい情報については「フィルタパターンのチートシート」を参照してください。

例: ブランチを含める

branchesで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、次のワークフローは以下をターゲットとするPull Requestに対するpull_requestイベントがあった場合に実行されます。

• mainという名前のブランチ(refs/heads/main)
• mona/octocatという名前のブランチ(refs/heads/mona/octocat)
• releases/10のようにreleases/で始まる名前のブランチ(refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'

例: ブランチの除外

パターンがtags-ignoreとマッチする場合、ワークフローは実行されません。 branchesで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、次のワークフローは以下をターゲットとしないPull Requestに対するpull_requestイベントがあった場合に実行されます。

• mona/octocatという名前のブランチ(refs/heads/mona/octocat)
• releases/beta/3-alphaのように、releases/**-alphaにマッチする名前のブランチ(refs/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'

例: ブランチを含めるとともに除外

branches及びbranches-ignoreフィルタを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対して含めるブランチパターンと除外するブランチパターンをどちらも使いたい場合には、branchesフィルタを!文字と合わせて使い、除外するブランチを示してください。

!文字を使ってブランチを定義する場合、!文字なしで少なくとも1つのブランチを定義する必要もあります。 ブランチの除外だけをしたい場合には、代わりにbranches-ignoreを使ってください。

パターンを定義する順序により、結果に違いが生じます。

• 肯定のマッチングパターンの後に否定のマッチングパターン ("!" のプレフィクス) を定義すると、Git ref を除外します。
• 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。

以下のワークフローは、releases/10 や releases/beta/mona へのpull_requestイベントで実行されますが、releases/10-alpha や releases/beta/3-alphaに対するPull Requstでは実行されません。肯定のマッチングパターンの後に、否定のマッチングパターン !releases/**-alpha が続いているからです。

on:
  pull_request:
    branches:    
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

pushイベントを使う場合、特定のブランチもしくはタグでワークフローを実行するように設定できます。

ブランチ名のパターンを含めたい場合、あるいはブランチ名のパターンを含めるとともに除外もしたい場合に、branchesフィルターを使ってください。 ブランチ名のパターンを除外のみしたい場合には、branches-ignoreフィルターを使ってください。 branches及びbranches-ignoreフィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。

タグ名のパターンを含めたい場合、あるいはタグ名のパターンを含めるとともに除外もしたい場合に、tagsフィルターを使ってください。 タグ名のパターンを除外のみしたい場合には、tags-ignoreフィルターを使ってください。 tags及びtags-ignoreフィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。

tags/tags-ignoreのみ、もしくはbranches/branches-ignoreだけを定義した場合、ワークフローは未定義のGit refに影響するイベントに対しては実行されません。 tags/tags-ignoreあるいはbranches/branches-ignoreのどちらも定義しなかった場合、ブランチもしくはタグに影響するイベントに対して実行されます。 branches/branches-ignore及びpathsをどちらも定義した場合、ワークフローは双方のフィルタを満たす場合にのみ実行されます。

branches、branches-ignore、tags、tags-ignoreのキーワードは、1つ以上ののブランチもしくはタグ名にマッチする*、**、+、?、!といった文字を使うglobパターンを受け付けます。 これらの文字のいずれかを含む名前に対してリテラルの一致をさせたい場合には、これらの特殊文字を\でエスケープしなければなりません。 globパターンに関する詳しい情報については「フィルタパターンのチートシート」を参照してください。

例: ブランチ及びタグ名を含める

branchesおよびtagsで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、次のワークフローは以下に対するpushイベントがあった場合に実行されます。

• mainという名前のブランチ(refs/heads/main)
• mona/octocatという名前のブランチ(refs/heads/mona/octocat)
• releases/10のようにreleases/で始まる名前のブランチ(refs/heads/releases/10)
• v2という名前のタグ(refs/tags/v2)
• v1.9.1のようにv1.で始まる名前のタグ(refs/tags/v1.9.1)

on:
  push:
    # refs/headsに対してマッチするパターンのシーケンス
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # refs/tagsに対してマッチするパターンのシーケンス
    tags:        
      - v2
      - v1.*

例: ブランチ及びタグの除外

パターンがbranches-ignoreまたはtags-ignoreとマッチする場合、ワークフローは実行されません。 branchesおよびtagsで定義されているパターンは、Git refの名前と照らし合わせて評価されます。 たとえば、次のワークフローはpushイベントがあり、そのpushイベントが以下に対するものでない場合に実行されます。

• mona/octocatという名前のブランチ(refs/heads/mona/octocat)
• beta/3-alphaのように、releases/**-alphaにマッチする名前のブランチ(refs/releases/beta/3-alpha)
• v2という名前のタグ(refs/tags/v2)
• v1.9のようにv1.で始まる名前のタグ(refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:    
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:        
      - v2
      - v1.*

例: ブランチとタグを含めるとともに除外

branches及びbranches-ignoreフィルタを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 同様に、tags及びtags-ignoreを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対してブランチもしくはタグパターンを含めるとともに除外したい場合には、branchesもしくはtagsフィルタを!文字とともに使って、除外すべきブランチもしくはタグを示してください。

!文字を使ってブランチを定義する場合、!文字なしで少なくとも1つのブランチを定義する必要もあります。 ブランチの除外だけをしたい場合には、代わりにbranches-ignoreを使ってください。 同様に、!文字でタグを定義する場合には、!なしで少なくとも1つのタグを定義する必要があります。 タグの除外だけをしたい場合には、代わりにtags-ignoreを使ってください。

パターンを定義する順序により、結果に違いが生じます。

• 肯定のマッチングパターンの後に否定のマッチングパターン ("!" のプレフィクス) を定義すると、Git ref を除外します。
• 否定のマッチングパターンの後に肯定のマッチングパターンを定義すると、Git ref を再び含めます。

以下のワークフローは、releases/10 や releases/beta/mona へのプッシュで実行されますが、releases/10-alpha や releases/beta/3-alpha へのプッシュでは実行されません。肯定のマッチングパターンの後に、否定のマッチングパターン !releases/**-alpha が続いているからです。

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

pushおよびpull_requestイベントを使用する場合、変更されたファイルパスに基づいてワークフローを実行するよう設定できます。 パスフィルタは、タグのプッシュに対しては評価されません。

pathsフィルタは、ファイルパスのパターンを含めたい場合や、ファイルパスのパターンを含めるとともに除外もしたい場合に使ってください。 ファイルパスパターンの除外のみをしたい場合には、paths-ignoreを使ってください。 paths及びpaths-ignoreフィルタを1つのワークフロー中の同じイベントでどちらも使用することはできません。

branches/branches-ignoreとpathsの両方を定義した場合、ワークフローはどちらのフィルタも満たされた場合にのみ実行されます。

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

例: パスを含める

pathsフィルタのパターンにマッチするパスが1つでもあれば、ワークフローは実行されます。 たとえば、以下のワークフローはJavaScriptファイル(.js)をプッシュするたびに実行されます。

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

例: パスの除外

すべてのパス名が paths-ignore のパターンと一致する場合、ワークフローは実行されません。 paths-ignore内のパターンにマッチしないパス名があった場合、場合、パターンにマッチするパスがあったとしても、ワークフローは実行されます。

以下のパスフィルタを持つワークフローは、リポジトリのルートにある docsディレクトリ外のファイルを少なくとも1つ含むpushイベントでのみ実行されます。

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

例: パスを含めるとともに除外

paths及びpaths-ignoreを1つのワークフロー中の同じイベントをフィルタリングするために使うことはできません。 1つのイベントに対して含めるパスパターンと除外するパスパターンをどちらも使いたい場合には、pathsフィルタを!文字と合わせて使い、除外するパスを示してください。

!文字を使ってパスを定義する場合、!文字なしで少なくとも1つのパスを定義する必要もあります。 パスの除外だけをしたい場合には、代わりにpaths-ignoreを使ってください。

パターンを定義する順序により、結果に違いが生じます:

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

この例は、pushイベントにsub-projectディレクトリあるいはそのサブディレクトリ内のファイルが含まれ、そのファイルがsub-project/docsディレクトリ内にはない場合に実行されます。 たとえばsub-project/index.jsもしくはsub-project/src/index.jsを変更するプッシュはワークフローを実行させますが、sub-project/docs/readme.mdだけを変更するプッシュは実行させません。

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Git diffの比較

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

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

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

Diffは300ファイルに制限されています。 フィルタが返す先頭の300ファイル内にマッチしない変更されたファイルがある場合、ワークフローは実行されません。 ワークフローが自動的に実行されるよう、さらに具体的なフィルタを作成する必要があるかもしれません。

詳しい情報については「Pull Request中のブランチの比較について」を参照してください。

on.schedule

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

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

on:
  schedule:
    # *はYAMLにおける特殊文字なので、この文字列はクオートしなければならない
    - cron:  '30 5,17 * * *'

A single workflow can be triggered by multiple schedule events. You can access the schedule event that triggered the workflow through the github.event.schedule context. This example triggers the workflow to run at 5:30 UTC every Monday-Thursday, but skips the Not on Monday or Wednesday step on Monday and Wednesday.

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

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

on.workflow_call

Use on.workflow_call to define the inputs and outputs for a reusable workflow. You can also map the secrets that are available to the called workflow. For more information on reusable workflows, see "Reusing workflows."

on.workflow_call.inputs

When using the workflow_call keyword, you can optionally specify inputs that are passed to the called workflow from the caller workflow. For more information about the workflow_call keyword, see "Events that trigger workflows."

In addition to the standard input parameters that are available, on.workflow_call.inputs requires a type parameter. 詳しい情報についてはon.workflow_call.inputs.<input_id>.typeを参照してください。

If a default parameter is not set, the default value of the input is false for a boolean, 0 for a number, and "" for a string.

Within the called workflow, you can use the inputs context to refer to an input.

If a caller workflow passes an input that is not specified in the called workflow, this results in an error.

サンプル

on:
  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

jobs:
  print-username:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input name to STDOUT
        run: echo The username is ${{ inputs.username }}

詳しい情報については「ワークフローの再利用」を参照してください。

on.workflow_call.inputs.<input_id>.type

Required if input is defined for the on.workflow_call keyword. The value of this parameter is a string specifying the data type of the input. This must be one of: boolean, number, or string.

on.workflow_call.outputs

A map of outputs for a called workflow. Called workflow outputs are available to all downstream jobs in the caller workflow. Each output has an identifier, an optional description, and a value. The value must be set to the value of an output from a job within the called workflow.

In the example below, two outputs are defined for this reusable workflow: workflow_output1 and workflow_output2. These are mapped to outputs called job_output1 and job_output2, both from a job called my_job.

サンプル

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}

For information on how to reference a job output, see jobs.<job_id>.outputs. 詳しい情報については「ワークフローの再利用」を参照してください。

on.workflow_call.secrets

A map of the secrets that can be used in the called workflow.

Within the called workflow, you can use the secrets context to refer to a secret.

If a caller workflow passes a secret that is not specified in the called workflow, this results in an error.

サンプル

on:
  workflow_call:
    secrets:
      access-token:
        description: 'A token passed from the caller workflow'
        required: false

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest

    steps:
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

A string identifier to associate with the secret.

on.workflow_call.secrets.<secret_id>.required

A boolean specifying whether the secret must be supplied.

on.workflow_run.<branches|branches-ignore>

workflow_runを使う場合、ワークフローがトリガーされるためには、どのブランチでトリガーされたワークフローが実行されなければならないかを指定できます。

branches及びbranches-ignoreフィルタは、複数のブランチ名にマッチさせるために*、**、+、?、!などの文字を使うglobパターンを受け付けます。 これらの文字のいずれかを含む名前に対してリテラルの一致をさせたい場合には、これらの特殊文字を\でエスケープしなければなりません。 globパターンに関する詳しい情報については「フィルタパターンのチートシート」を参照してください。

たとえば、以下のトリガーを持つワークフローは、Buildという名前のワークフローがreleases/で始まる名前のブランチで実行される場合にのみ実行されます。

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

以下のトリガーを持つワークフローは、Buildという名前のワークフローがcanaryという名前ではないブランチ上で実行される場合にのみ実行されます。

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

branchesとbranches-ignoreを1つのワークフロー内の同じイベントに使うことはできません。 1つのイベントに対して含めるブランチパターンと除外するブランチパターンをどちらも使いたい場合には、branchesフィルタを!文字と合わせて使い、除外するブランチを示してください。

パターンを定義する順序により、結果に違いが生じます。

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

たとえば、以下のトリガーを持つワークフローは、Buildというナメのワークフローがreleases/10もしくはreleases/beta/monaという名前のブランチ上で実行されている場合に実行されますが、releases/10-alpha、releases/beta/3-alpha、mainといった名前のブランチ上で実行されている場合には実行されません。

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch.inputs

workflow_dispatchイベントを使う場合、ワークフローに渡す入力を指定することもできます。

トリガーされたワークフローは、入力をinputsコンテキストで受け取ります。 詳しい情報については「コンテキスト」を参照してください。

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning' 
        type: choice
        options:
        - info
        - warning
        - debug 
      print_tags:
        description: 'True to print to STDOUT'
        required: true 
        type: boolean 
      tags:
        description: 'Test scenario tags'
        required: true 
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true 

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if:  ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

permissions

permissionsを使ってGITHUB_TOKEN に付与されているデフォルトの権限を変更し、必要に応じてアクセスを追加または削除して、必要最小限のアクセスのみを許可することができます。 詳しい情報については、「ワークフローでの認証」を参照してください。

permissions は、最上位キーとしてワークフロー内のすべてのジョブに適用するために、または特定のジョブ内で使用できます。 特定のジョブ内に permissions キーを追加すると、GITHUB_TOKEN を使用するそのジョブ内のすべてのアクションと実行コマンドが、指定したアクセス権を取得します。 詳しい情報については、jobs.<job_id>.permissions を参照してください。

利用可能なスコープとアクセス値:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

これらのスコープのいずれかのアクセスを指定した場合、指定されたなかったものはすべてnoneに設定されます。

以下の構文を使って、読み取りもしくは書き込みアクセスを利用可能なすべてのスコープに定義できます。

permissions: read-all|write-all

以下の構文を使って、利用可能なすべてのスコープの権限を無効化できます。

permissions: {}

permissionsキーを使って、フォークされたリポジトリの読み取り権限の付与や削除ができますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理ユーザがGitHub Actionsの設定でSend write tokens to workflows from pull requests（Pull Requestからワークフローに書き込みトークンを送る）を選択している場合があります。 詳しい情報については、「リポジトリの GitHub Actions 設定の管理」を参照してください。

例: GITHUB_TOKENへの権限の割り当て

この例は、ワークフロー内のすべてのジョブに適用される GITHUB_TOKEN に設定されている権限を示しています。 すべての権限に読み取りアクセスが付与されます。

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

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

Variables in the env map cannot be defined in terms of other variables in the map.

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

サンプル

env:
  SERVER: production

defaults

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

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

defaults.run

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

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

例: デフォルトのシェルとワーキングディレクトリの設定

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

concurrency

concurrencyを使って、同じ並行処理グループを使うジョブもしくはワークフローが一度に1つだけ実行されることを保証できます。 並行処理グループには、任意の文字列または式を使用できます。 この式はgithub contextだけを使用します。 式に関する詳しい情報については「式」を参照してください。

ジョブレベルで concurrency を指定することもできます。 詳しい情報については、jobs.<job_id>.concurrency を参照してください。

並行ジョブもしくはワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブもしくはワークフローが進行中だと、キューイングされたジョブもしくはワークフローは保留中になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じ並行グループ内にある実行中のジョブもしくはワークフローもキャンセルするには、cancel-in-progress: trueを指定してください。

並行性とデフォルトの動作の使用例

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

並行性を使って進行中のジョブもしくは実行をキャンセルする例

concurrency: 
  group: ${{ github.ref }}
  cancel-in-progress: true

例: フォールバック値の利用

特定のイベントに対してのみ定義されているプロパティでグループ名を構築した場合、フォールバック値を使用できます。 たとえばgithub.head_refはpull_requestでのみ定義されています。 ワークフローがpull_requestイベントに加えて他のイベントにも反応するなら、構文エラーを避けるためにフォールバックを提供する必要があります。 以下の並行グループは、進行中のジョブをキャンセルするか、pull_requestイベントでのみ実行されます。github.head_refが未定の場合、この並行グループは一意であることが保証され、実行に対して定義される実行IDにフォールバックします。

concurrency: 
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

例: 進行中のジョブをキャンセルするか、現在のワークフローに対して実行する

同じリポジトリに複数のワークフローを持っている場合、進行中のジョブがキャンセルされたり、他のワークフローから実行されたりすることを防ぐために、並行グループ名はワークフロー全体に対して一意でなければなりません。 そうでなかった場合、進行中あるいは保留されているジョブは、ワークフローに関係なくキャンセルされます。

同じワークフローで進行中の実行だけをキャンセルするには、並行グループの構築にgithub.workflowプロパティが利用できます。

concurrency: 
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs

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

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

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

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

jobs.<job_id>

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

例: ジョブの作成

この例では2つのジョブが作成されており、そのjob_idの値はmy_first_jobとmy_second_jobです。

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

jobs.<job_id>.name

jobs.<job_id>.nameを使ってジョブの名前を設定してください。この名前はGitHubのUIに表示されます。

jobs.<job_id>.permissions

特定のジョブについて、jobs.<job_id>.permissionsを使ってGITHUB_TOKENに付与されたデフォルトの権限を変更し、必要に応じてアクセスを付与したり削除したりして、必要最小限のアクセスだけを許可できます。 詳しい情報については、「ワークフローでの認証」を参照してください。

ジョブ定義内で権限を指定することで、必要に応じて、ジョブごとに GITHUB_TOKEN に異なる権限のセットを設定できます。 または、ワークフロー内のすべてのジョブの権限を指定することもできます。 ワークフローレベルでの権限の定義については、 permissions を参照してください。

利用可能なスコープとアクセス値:

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

これらのスコープのいずれかのアクセスを指定した場合、指定されたなかったものはすべてnoneに設定されます。

以下の構文を使って、読み取りもしくは書き込みアクセスを利用可能なすべてのスコープに定義できます。

permissions: read-all|write-all

以下の構文を使って、利用可能なすべてのスコープの権限を無効化できます。

permissions: {}

permissionsキーを使って、フォークされたリポジトリの読み取り権限の付与や削除ができますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理ユーザがGitHub Actionsの設定でSend write tokens to workflows from pull requests（Pull Requestからワークフローに書き込みトークンを送る）を選択している場合があります。 詳しい情報については、「リポジトリの GitHub Actions 設定の管理」を参照してください。

例: 特定のジョブに対する権限の設定

この例では、stale という名前のジョブにのみ適用される GITHUB_TOKEN に設定されている権限を示しています。 issues および pull-requests のスコープに対して書き込みアクセスが許可されます。 他のすべてのスコープにはアクセスできません。

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5

jobs.<job_id>.needs

jobs.<job_id>.needsを使って、このジョブを実行する前に成功して完了していなければならないジョブを特定してください。 これは文字列型または文字列の配列です。 1つのジョブが失敗した場合、失敗したジョブを続行するような条件式を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。 1つの実行にお互いを必要とする一連のジョブが含まれていた場合、失敗時点以降の依存関係チェーン中のすべてのジョブに失敗が適用されます。

例: 依存対象のジョブの成功を必要とする

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

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

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

1. job1
2. job2
3. job3

例: 依存対象のジョブの成功を必要としない

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

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

jobs.<job_id>.if

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

if 条件の中で式を使用する際には、式構文 (${{ }})を省略できます。これは、GitHub が if 条件を式として自動的に評価するためです。 詳しい情報については「式」を参照してください。

例: 特定のリポジトリのジョブだけを実行する

この例はifを使っていつproduction-deployジョブが実行できるかを制御しています。 このジョブは、リポジトリの名前がocto-repo-prodで、octo-orgというOrganization内にあるときだけ実行されます。 そうでない場合、このジョブはskippedとマークされます。

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

jobs.<job_id>.runs-onを使って、ジョブを実行するマシンのタイプを定義してください。 マシンは、GitHubホストランナーでも、セルフホストランナーでもかまいません。runs-onは単一の文字列として、あるいは文字列の配列として渡せます。 文字列の配列を指定した場合、ワークフローは指定されたすべてのruns-onの値にラベルがマッチしたセルフホストランナーが利用可能であれば、そのランナーで実行されます。 複数のマシン上でワークフローを実行したいのであれば、jobs.<job_id>.strategyを使ってください。

GitHubホストランナーの選択

If you use a GitHub-hosted runner, each job runs in a fresh instance of a runner image specified by runs-on.

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

例: オペレーティングシステムの指定

runs-on: ubuntu-latest

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

セルフホストランナーの選択

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

すべてのセルフホストランナーはself-hostedラベルを持っています。 このラベルだけを使えば、任意のセルフホストランナーを選択することになります。 オペレーティングシステムやアーキテクチャなど、特定の条件を満たすランナーを選択するには、self-hosted（これは先頭になければなりません）で始まり、必要に応じて追加のラベルを含むラベルの配列を提供することをおすすめします。 ラベルの配列を指定すると、ジョブは指定したすべてのラベルを持つランナーにキューイングされます。

self-hostedラベルは必須ではありませんが、セルフホストランナーを使う際には意図せず現在もしくは将来のGitHubホストランナーをジョブが指定しまうことがないよう、このラベルを指定することを強くおすすめします。

例: ランナーの選択にラベルを使用

runs-on: [self-hosted, linux]

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

jobs.<job_id>.environment

jobs.<job_id>.environmentを使って、ジョブが参照する環境を定義してください。 環境を参照するジョブがランナーに送られる前に、その環境のすべての保護ルールはパスしなければなりません。 詳しい情報については「デプロイメントの環境の利用」を参照してください。

環境は、環境のnameだけで、あるいはname and urlを持つenvironmentオブジェクトとして渡すことができます。 デプロイメントAPIでは、このURLはenvironment_urlにマップされます。 デプロイメントAPIに関する詳しい情報については「デプロイメント」を参照してください。

例: 単一の環境名の使用

environment: staging_environment

例: 環境名とURLの使用

environment:
  name: production_environment
  url: https://github.com

URLには式を指定でき、secrets context以外の任意のコンテキストを利用できます。 式に関する詳しい情報については「式」を参照してください。

例: URLとしての出力の使用

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

jobs.<job_id>.concurrency

jobs.<job_id>.concurrencyを使って、同じ並行処理グループを使う1つのジョブもしくはワークフローだけが実行されることを保証できます。 並行処理グループには、任意の文字列または式を使用できます。 式は、secrets コンテキストを除く任意のコンテキストを使用できます。 式に関する詳しい情報については「式」を参照してください。

ワークフローレベルで concurrency を指定することもできます。 詳しい情報については、concurrency を参照してください。

並行ジョブもしくはワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブもしくはワークフローが進行中だと、キューイングされたジョブもしくはワークフローは保留中になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じ並行グループ内にある実行中のジョブもしくはワークフローもキャンセルするには、cancel-in-progress: trueを指定してください。

並行性とデフォルトの動作の使用例

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

並行性を使って進行中のジョブもしくは実行をキャンセルする例

concurrency: 
  group: ${{ github.ref }}
  cancel-in-progress: true

例: フォールバック値の利用

特定のイベントに対してのみ定義されているプロパティでグループ名を構築した場合、フォールバック値を使用できます。 たとえばgithub.head_refはpull_requestでのみ定義されています。 ワークフローがpull_requestイベントに加えて他のイベントにも反応するなら、構文エラーを避けるためにフォールバックを提供する必要があります。 以下の並行グループは、進行中のジョブをキャンセルするか、pull_requestイベントでのみ実行されます。github.head_refが未定の場合、この並行グループは一意であることが保証され、実行に対して定義される実行IDにフォールバックします。

concurrency: 
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

例: 進行中のジョブをキャンセルするか、現在のワークフローに対して実行する

同じリポジトリに複数のワークフローを持っている場合、進行中のジョブがキャンセルされたり、他のワークフローから実行されたりすることを防ぐために、並行グループ名はワークフロー全体に対して一意でなければなりません。 そうでなかった場合、進行中あるいは保留されているジョブは、ワークフローに関係なくキャンセルされます。

同じワークフローで進行中の実行だけをキャンセルするには、並行グループの構築にgithub.workflowプロパティが利用できます。

concurrency: 
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs.<job_id>.outputs

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

出力はUnicode文字列であり、最大1MBです。 ワークフローの実行中のすべての出力の合計は、最大で50MBです。

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

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

例: ジョブの出力の定義

jobs:
  job1:
    runs-on: ubuntu-latest
    # ステップの出力をジョブの出力にマップする
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{needs.job1.outputs.output1}} ${{needs.job1.outputs.output2}}

jobs.<job_id>.env

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

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

サンプル

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

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

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

jobs.<job_id>.defaults.run

jobs.<job_id>.defaults.runを使ってジョブ中のすべてのrunステップにデフォルトのshellとworking-directoryを指定してください。 このセクションではコンテキストと式は許されていません。

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

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

例: ジョブのrunステップにデフォルトのオプションを設定

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

jobs.<job_id>.steps

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

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

サンプル

name: Greeting from Mona

on: push

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

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

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

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

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

if 条件の中で式を使用する際には、式構文 (${{ }})を省略できます。これは、GitHub が if 条件を式として自動的に評価するためです。 詳しい情報については「式」を参照してください。

Example: Using contexts

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

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

Example: Using status check functions

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

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

Example: Using secrets

Secrets cannot be directly referenced in if: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.

If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }} in the example) will be an empty string.

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

For more information, see "Context availability" and "Encrypted secrets."

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

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

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

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

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

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

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

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

Example: Using versioned actions

steps:
  # Reference a specific commit
  - uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
  # Reference the major version of a release
  - uses: actions/checkout@v3
  # Reference a specific version
  - uses: actions/checkout@v3.2.0
  # Reference a branch
  - uses: actions/checkout@main

Example: Using a public action

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

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

Example: Using a public action in a subdirectory

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

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

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

Example: Using an action in the same repository as the workflow

./path/to/dir

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

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

Example: Using a Docker Hub action

docker://{image}:{tag}

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

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

Example: Using the GitHub Packages コンテナレジストリ

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

GitHub Packages コンテナレジストリ の Docker イメージ

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://ghcr.io/OWNER/IMAGE_NAME

Example: Using a Docker public registry action

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

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

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

Example: Using an action inside a different private repository than the workflow

ワークフローはプライベートリポジトリをチェックアウトし、アクションをローカルで参照する必要があります。 個人アクセストークンを生成し、暗号化されたシークレットとしてトークンを追加します。 詳しい情報については、「個人アクセストークンを作成する」および「暗号化されたシークレット」を参照してください。

例にある PERSONAL_ACCESS_TOKEN をシークレットの名前に置き換えます。

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

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

オペレーティングシステムのシェルを使用してコマンドラインプログラムを実行します。 nameを指定しない場合、ステップ名はデフォルトでrunコマンドで指定された文字列になります。

コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 For more information, see jobs.<job_id>.steps[*].shell.

runキーワードは、それぞれがランナー環境での新しいプロセスとシェルです。 複数行のコマンドを指定すると、各行が同じシェルで実行されます。 例:

• 1行のコマンド：

  - name: Install Dependencies
    run: npm install
  

• 複数行のコマンド：

  - name: Clean install dependencies and build
    run: |
      npm ci
      npm run build
  

working-directoryキーワードを使えば、コマンドが実行されるワーキングディレクトリを指定できます。

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

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

shellキーワードを使用して、ランナーのオペレーティングシステムのデフォルトシェルの設定を上書きできます。 組み込みのshellキーワードを使用するか、カスタムセットのシェルオプションを定義することができます。 The shell command that is run internally executes a temporary file that contains the commands specified in the run keyword.

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

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

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

組み込みのshellキーワードについては、GitHubがホストする実行環境で以下のデフォルトが提供されます。 シェルスクリプトを実行する際には、以下のガイドラインを使ってください。

• bash/sh:

  • Fail-fast behavior using set -eo pipefail: This option is set when shell: bash is explicitly specified. It is not applied by default.
  • You can take full control over shell parameters by providing a template string to the shell options. たとえば、bash {0}とします。
  • shライクのシェルは、スクリプトで実行された最後のコマンドの終了コードで終了します。これが、アクションのデフォルトの動作でもあります。 runnerは、この終了コードに基づいてステップのステータスを失敗/成功としてレポートします。

• powershell/pwsh

  • 可能な場合のフェイルファースト動作。 pwshおよびpowershellの組み込みシェルの場合は、スクリプトの内容の前に$ErrorActionPreference = 'stop' が付加されます。
  • ここでは、アクションステータスがスクリプトの最後の終了コードを反映するように、PowerShellスクリプトにif ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE }を付加しています。
  • 必要な場合には、組み込みシェルを使用せずに、pwsh -File {0}やpowershell -Command "& '{0}'"などのカスタムシェルを指定すれば、いつでもオプトアウトすることができます。

• cmd

  • 各エラーコードをチェックしてそれぞれに対応するスクリプトを書く以外、フェイルファースト動作を完全にオプトインする方法はないようです。 デフォルトでその動作を指定することはできないため、この動作はスクリプトに記述する必要があります。
  • cmd.exeは、実行した最後のプログラムのエラーレベルで終了し、runnerにそのエラーコードを返します。 この動作は、これ以前のshおよびpwshのデフォルト動作と内部的に一貫しており、cmd.exeのデフォルトなので、この動作には影響しません。

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

アクションによって定義される入力パラメータのmap。 各入力パラメータはキー/値ペアです。 入力パラメータは環境変数として設定されます。 変数の前にはINPUT_が付けられ、大文字に変換されます。

サンプル

hello_worldアクションで定義される3つの入力パラメータ (first_name、middle_name、last_name) を定義します。 hello-worldアクションからは、これらの入力変数はINPUT_FIRST_NAME、INPUT_MIDDLE_NAME、INPUT_LAST_NAMEという環境変数としてアクセスできます。

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

Dockerコンテナへの入力を定義する文字列。 GitHubは、コンテナの起動時にargsをコンテナのENTRYPOINTに渡します。 このパラメータは、文字列の配列をサポートしません。

サンプル

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

argsは、Dockerfile中のCMD命令の場所で使われます。 Dockerfile中でCMDを使うなら、以下の優先順位順のガイドラインを利用してください。

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.

jobs.<job_id>.strategy

Use jobs.<job_id>.strategy to use a matrix strategy for your jobs. マトリックス戦略を使うと、単一のジョブ定義中で変数を使って、変数の組み合わせに基づく複数のジョブの実行を自動的に生成できます。 たとえばマトリックス戦略を使って、コードを言語の複数のバージョンや、複数のオペレーティングシステムでテストできます。 For more information, see "Using a matrix for your jobs."

jobs.<job_id>.strategy.matrix

jobs.<job_id>.strategy.matrixを使って、様々なジョブ設定のマトリックスを定義してください。 マトリックス内では、1つ以上の変数のあとに値の配列を続けて定義してください。 たとえば、以下のマトリックスは[10, 12, 14]という値のversionという変数を、そして[ubuntu-latest, windows-latest]という値のosという変数を持っています。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

取り得る変数のそれぞれの組み合わせに対して、ジョブが実行されます。 この例では、ワークフローはos及びversion変数のそれぞれの組み合わせに対応する6つのジョブを実行します。

デフォルトでは、GitHubは利用可能なランナーに応じて並列に実行されるジョブ数を最大化します。 マトリックス内の変数の順序によって、ジョブが生成される順序が決まります。 定義された最初の変数が、ワークフロー中で生成される最初のジョブになります。 たとえば、上のマトリックスはジョブを以下の順序で生成します。

• {version: 10, os: ubuntu-latest}
• {version: 10, os: windows-latest}
• {version: 12, os: ubuntu-latest}
• {version: 12, os: windows-latest}
• {version: 14, os: ubuntu-latest}
• {version: 14, os: windows-latest}

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

定義した変数はmatrixコンテキストのプロパティとなり、このプロパティはワークフローファイルの他の領域から参照できます。 この例では、matrix.versionとmatrix.osを使ってジョブが使用している現在のversionとosの値にアクセスできます。 詳細については、「コンテキスト」を参照してください。

Example: Using a single-dimension matrix

1つの変数を指定して、1次元のマトリックスを作成できます。

たとえば、以下のワークフローは変数versionに[10, 12, 14]という値を定義しています。 このワークフローは、変数中のそれぞれの値に対して1つずつ、3つのジョブを実行します。 それぞれのジョブはversionの値にmatrix.versionコンテキストを通じてアクセスし、その値をnode-versionとしてactions/setup-nodeアクションに渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Example: Using a multi-dimension matrix

複数の変数を指定して、多次元マトリックスを作成できます。 変数の取り得るそれぞれの組み合わせに対してジョブが実行されます。

たとえば、以下のワークフローは2つの変数を指定しています。

• os変数では2つのオペレーティングシステムが指定されています
• version変数では、3つのNode.jsのバージョンが指定されています

このワークフローは、os及びversion変数のそれぞれの組み合わせに応じた6のジョブを実行します。 各ジョブは、runs-onの値を現在のosの値に設定し、現在のversionの値をactions/setup-nodeアクションに渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-18.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

Example: Using contexts to create matrices

コンテキストを使ってマトリックスを作成できます。 コンテキストに関する詳しい情報については「コンテキスト」を参照してください。

たとえば、以下のワークフローはrepository_dispatchイベントでトリガーされ、マトリックスの構築にイベントのペイロードからの情報を使います。 リポジトリのディスパッチイベントが以下のようなペイロードで作成されると、マトリックスのversion変数は[12, 14, 16]という値を持ちます。 repository_dispatchに関する詳しい情報については「ワークフローをトリガーするイベント」を参照してください。

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}

on:
  repository_dispatch:
    types:
      - test

jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

jobs.<job_id>.strategy.matrix.includeを使って、既存のマトリックス設定を拡張したり、新しい設定を追加したりしてください。 includeの値は、オブジェクトのリストです。

includeリスト中の各オブジェクトについて、オブジェクト中のkey:valueペアがいずれもオリジナルのマトリックスの値を上書きしない場合、それらのkey:valueペアはそれぞれのマトリックスの組み合わせに追加されます。 オブジェクトがマトリックスの組み合わせのいずれにも追加できない場合、代わりに新しいマトリックスの組み合わせが作成されます。 オリジナルのマトリックスの値は上書きされませんが、追加されたマトリックスの値は上書きできることに注意してください。

たとえば、以下のマトリックス

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

は、以下のマトリックスの組み合わせを持つ6つのジョブを生成します。

• {fruit: apple, animal: cat, color: pink, shape: circle}
• {fruit: apple, animal: dog, color: green, shape: circle}
• {fruit: pear, animal: cat, color: pink}
• {fruit: pear, animal: dog, color: green}
• {fruit: banana}
• {fruit: banana, animal: cat}

以下のようなロジックに従っています。

• {color: green}は、オリジナルの組み合わせのどの部分も上書きすることなく追加できるので、すべてのオリジナルのマトリックスの組み合わせに追加されます。
• {color: pink, animal: cat}は、animal: catを含むオリジナルのマトリックスの組み合わせに対してcolor:pinkだけを追加します。 これは、先のincludeエントリで追加されたcolor: greenを上書きします。
• {fruit: apple, shape: circle}はfruit: appleを含むオリジナルのマトリックスの組み合わせにshape: circleだけを追加します。
• {fruit: banana}は、値を上書きせずにオリジナルのマトリックスの組み合わせに追加することができないので、追加のマトリックスの組み合わせとして追加されます。
• {fruit: banana, animal: cat}は、値を上書きせずにオリジナルのマトリックスの組み合わせに追加することができないので、追加のマトリックスの組み合わせとして追加されます。 これは{fruit: banana}のマトリックスの組み合わせには追加されませんが、それはこの組み合わせがオリジナルのマトリックスの組み合わせの1つではないからです。

Example: Expanding configurations

たとえば、以下のワークフローはosとnodeの組み合わせに対応する6つのジョブを実行します。 osの値がwindows-latestでnodeの値が16に対するジョブが実行されると、そのジョブにはnpmという追加の変数が6を値として含まれます。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Example: Adding configurations

たとえばこのマトリックスは、マトリックス内のos及びversionの各組み合わせに、osの値がwindows-latestでversionの値が17の場合を加えて、10個のジョブを実行します。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

マトリックス変数を指定しなければ、include以下のすべての設定が実行されます。 たとえば、以下のワークフローはincludeの各エントリに対応して2つのジョブを実行します。 これによって、完全にマトリックスを展開することなく、マトリックス戦略を活用できます。

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

マトリックスで定義されている特定の設定を除外したい場合には、jobs.<job_id>.strategy.matrix.excludeを使ってください。 除外する設定は、部分一致だけでかまいません。 たとえば、以下のワークフローは9つのジョブを実行します。12個の各設定に対応するジョブから、{os: macos-latest, version: 12, environment: production}にマッチする1つのジョブと{os: windows-latest, version: 16}にマッチする2つのジョブが除外されます。

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

jobs.<job_id>.strategy.fail-fast

jobs.<job_id>.strategy.fail-fast and jobs.<job_id>.continue-on-errorで、ジョブの失敗をどのように扱うかを制御できます。

jobs.<job_id>.strategy.fail-fastはマトリックス全体に適用されます。 jobs.<job_id>.strategy.fail-fastがtrueに設定されていると、GitHubはマトリックス内のいずれかのジョブが失敗した場合、マトリックスの進行中及びキューイングされたすべてのジョブをキャンセルします。 この属性のデフォルトはtrueです。

jobs.<job_id>.continue-on-errorは単一のジョブに適用されます。 jobs.<job_id>.continue-on-errorがtrueの場合、jobs.<job_id>.continue-on-error: trueを指定されたジョブが失敗したとしても、マトリックス内の他のジョブは実行を継続します。

jobs.<job_id>.strategy.fail-fastとjobs.<job_id>.continue-on-errorは合わせて利用できます。 たとえば、以下のワークフローは4つのジョブを開始します。 それぞれのジョブにおいて、continue-on-errorはmatrix.experimentalの値によって決定されます。 continue-on-error: falseを指定されたいずれかのジョブが失敗すると、進行中もしくはキューイングされたすべてのジョブはキャンセルされます。 continue-on-error: trueを指定されたジョブが失敗しても、他のジョブは影響を受けません。

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

デフォルトでは、GitHubは利用できるランナーに応じて並列に実行するジョブ数を最大化します。 matrixジョブ戦略を使用する際に同時に実行できるジョブの最大数を設定するには、jobs.<job_id>.strategy.max-parallelを使ってください。

たとえば以下のワークフローは、仮に6つのジョブすべてを一度に実行できるランナーが利用できるとしても、同時に最大で2つのジョブしか実行しません。

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

jobs.<job_id>.continue-on-error

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

Example: Preventing a specific failing matrix job from failing a workflow run

ジョブマトリックス中の特定のジョブが失敗しても、ワークフローの実行が失敗にならないようにすることができます。 For example, if you wanted to only allow an experimental job with node set to 15 to fail without failing the workflow run.

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

jobs.<job_id>.container

jobs.<job_id>.containerを使って、コンテナをまだ指定していないジョブ内の任意のステップを実行するためのコンテナを作成してください。 スクリプトアクションとコンテナアクションの両方を使うステップがある場合、コンテナアクションは同じボリュームマウントを使用して、同じネットワーク上にある兄弟コンテナとして実行されます。

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

例: コンテナ内でのジョブの実行

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:14.16
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

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

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:14.16

jobs.<job_id>.container.image

jobs.<job_id>.container.imageを使って、アクションを実行させるコンテナとして使うDockerイメージを定義してください。 この値は、Docker Hubのイメージ名か、レジストリ名にすることができます。

jobs.<job_id>.container.credentials

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

例: コンテナレジストリの認証情報の定義

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

jobs.<job_id>.container.env

jobs.<job_id>.container.envを使って、コンテナ内の環境変数のmapを設定してください。

jobs.<job_id>.container.ports

jobs.<job_id>.container.portsを使って、コンテナで公開するポートの配列を設定してください。

jobs.<job_id>.container.volumes

jobs.<job_id>.container.volumesを使って、コンテナが使用するボリュームの配列を設定してください。 volumes (ボリューム) を使用すると、サービス間で、または1つのジョブのステップ間でデータを共有できます。 指定できるのは、名前付きDockerボリューム、匿名Dockerボリューム、またはホスト上のバインドマウントです。

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

<source>:<destinationPath>.

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

例: コンテナでのボリュームのマウント

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

jobs.<job_id>.container.options

jobs.<job_id>.container.optionsを使って、追加のDockerコンテナのリソースオプションを設定してください。 オプションの一覧は、「docker createのオプション」を参照してください。

jobs.<job_id>.services

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

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

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

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

Example: Using localhost

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

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

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

アクションを実行するサービスコンテナとして使用するDockerイメージ。 The value can be the Docker Hub image name or a registry name.

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

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

サンプル

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

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

jobs.<job_id>.services.<service_id>.ports

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

jobs.<job_id>.services.<service_id>.volumes

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

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

<source>:<destinationPath>.

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

サンプル

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

jobs.<job_id>.services.<service_id>.options

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

jobs.<job_id>.uses

The location and version of a reusable workflow file to run as a job. Use one of the following syntaxes:

• {owner}/{repo}/.github/workflows/{filename}@{ref} パブリックリポジトリ内の再利用可能なワークフローの場合。.
• ./.github/workflows/{filename} 同じリポジトリ内の再利用可能なワークフローの場合。

{ref}にはSHA、リリースタグ、ブランチ名が使えます。 コミットSHAを使うのが、安定性とセキュリティの上で最も安全です。 詳しい情報については「GitHub Actionsのためのセキュリティ強化」を参照してください。 2番目の構文（{owner}/{repo} and @{ref}なし）を使うなら、呼び出されるワークフローは呼び出し元のワークフローと同じコミットからのものになります。

サンプル

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

詳しい情報については「ワークフローの再利用」を参照してください。

jobs.<job_id>.with

When a job is used to call a reusable workflow, you can use with to provide a map of inputs that are passed to the called workflow.

Any inputs that you pass must match the input specifications defined in the called workflow.

Unlike jobs.<job_id>.steps[*].with, the inputs you pass with jobs.<job_id>.with are not be available as environment variables in the called workflow. Instead, you can reference the inputs by using the inputs context.

サンプル

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    with:
      username: mona

jobs.<job_id>.with.<input_id>

A pair consisting of a string identifier for the input and the value of the input. The identifier must match the name of an input defined by on.workflow_call.inputs.<inputs_id> in the called workflow. The data type of the value must match the type defined by on.workflow_call.inputs.<input_id>.type in the called workflow.

Allowed expression contexts: github, and needs.

jobs.<job_id>.secrets

When a job is used to call a reusable workflow, you can use secrets to provide a map of secrets that are passed to the called workflow.

Any secrets that you pass must match the names defined in the called workflow.

サンプル

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    secrets:
      access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

jobs.<job_id>.secrets.inherit

Use the inherit keyword to pass all the calling workflow's secrets to the called workflow. This includes all secrets the calling workflow has access to, namely organization, repository, and environment secrets. The inherit keyword can be used to pass secrets across repositories within the same organization, or across organizations within the same enterprise.

サンプル

on:
  workflow_dispatch:

jobs:
  pass-secrets-to-workflow:
    uses: ./.github/workflows/called-workflow.yml
    secrets: inherit

on:
  workflow_call:

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
      - name: Use a repo or org secret from the calling workflow.
        run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }}

jobs.<job_id>.secrets.<secret_id>

A pair consisting of a string identifier for the secret and the value of the secret. The identifier must match the name of a secret defined by on.workflow_call.secrets.<secret_id> in the called workflow.

Allowed expression contexts: github, needs, and secrets.

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

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

• *ゼロ個以上のキャラクタにマッチしますが、/にはマッチしません。 たとえばOcto*はOctocatにマッチします。
• **ゼロ個以上の任意のキャラクタにマッチします。
• ?: Matches zero or one of the preceding character.
• +: 直前の文字の 1 つ以上に一致します。
• [] 括弧内にリストされた、あるいは範囲に含まれる1つのキャラクタにマッチします。 範囲に含めることができるのはa-z、A-Z、0-9のみです。 たとえば、[0-9a-z]という範囲は任意の数字もしくは小文字にマッチします。 たとえば[CB]atはCatあるいはBatにマッチし、[1-2]00は100や200にマッチします。
• !: パターンの先頭に置くと、肯定のパターンを否定にします。 先頭のキャラクタではない場合は、特別な意味を持ちません。

YAMLにおいては、*、[、!は特別なキャラクタです。 パターンを*、[、!で始める場合、そのパターンをクオートで囲まなければなりません。

# 有効
- '**/README.md'

# 無効 - ワークフローの実行を妨げる
# 解析エラーを作成する
- **/README.md

For more information about branch, tag, and path filter syntax, see "on.<push>.<branches|tags>", "on.<pull_request>.<branches|tags>", and "on.<push|pull_request>.paths."

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

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

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