Workflow syntax for GitHub Actions

About YAML syntax for workflows

Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. YAML を初めて使用する場合は、「Learn YAML in Y minutes」 (YAML を Y 分で学習する) を参照してください。

You must store workflow files in the .github/workflows directory of your repository.

name

The name of your workflow. GitHub displays the names of your workflows on your repository's "Actions" tab. If you omit name, GitHub sets it to the workflow file path relative to the root of the repository.

on

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

ワークフローをトリガーできる 1 つまたは複数のイベントを定義することも、時間スケジュールを設定することもできます。 また、特定のファイル、タグ、またはブランチの変更に対してのみワークフローが実行されるよう制限することもできます。 以降のセクションでは、これらのオプションについて説明します。

単一のイベントを使用する

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

on: push

複数のイベントを使用する

1 つのイベントまたは複数のイベントを指定できます。 たとえば、次の 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 がオープンされると、3 つのワークフロー実行 (1 つは Issue がオープンされたイベント用、2 つは Issue のラベルが付いたイベント用) が開始されます。

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 のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

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/**'

例: ブランチの除外

パターンが branches-ignore パターンと一致する場合、ワークフローは実行されません。 branches で定義されているパターンは、Git ref の名前に対して評価されます。 たとえば、次のワークフローは、pull request の対象とならない限り、pull_request イベントが発生するたびに実行されます。

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

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

例: パスの包含および除外

1 つのワークフローで同じイベントのフィルター処理をするために branches と branches-ignore を使用することはできません。 1 つのイベントに対して分岐パターンの適用と除外の両方を行う場合は、branches フィルターと ! 文字を使用して、除外する分岐を指定します。

! 文字を含むブランチを定義する場合は、! 文字を含まないブランチも 1 つ以上定義する必要があります。 ブランチの除外のみを行いたい場合は、代わりに branches-ignore を使用します。

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

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

次のワークフローは、否定のパターン !releases/**-alpha が肯定のパターンの後に続くため、releases/10 または releases/beta/mona を対象とする pull request の pull_request イベントで実行されますが、releases/10-alpha または releases/beta/3-alpha を対象とする pull request では実行されません。

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

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

push イベントを使用する場合は、特定のブランチまたはタグで実行するワークフローを構成できます。

ブランチ名パターンを含める場合、またはブランチ名パターンを含める/除外の両方を行う場合は、branches フィルターを使用します。 ブランチ名パターンの除外のみを行う場合は、branches-ignore フィルターを使用します。 branches と branches-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

タグ名パターンを含める場合、またはタグ名パターンを含める/除外の両方を行う場合は、tags フィルターを使用します。 タグ名パターンの除外のみを行う場合は、tags-ignore フィルターを使用します。 tags と tags-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

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

branches、branches-ignore、tags、および tags-ignore のキーワードは、複数のブランチまたはタグ名に一致する文字 (*、**、+、?、! など) を使用する 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:
    # Sequence of patterns matched against refs/heads
    branches:    
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against 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.*

ブランチやタグを含めたり除外したりする例

1 つのワークフローで同じイベントをフィルターするために branches と branches-ignore を使用することはできません。 同様に、1 つのワークフローで同じイベントをフィルターするために tags と tags-ignore を使用することはできません。 1 つのイベントに対してブランチまたはタグ パターンを含める/除外の両方を行う場合は、branches または tags フィルターと ! 文字を使用して、除外するブランチまたはタグを指定します。

! 文字を含むブランチを定義する場合は、! 文字を含まないブランチも 1 つ以上定義する必要があります。 ブランチの除外のみを行いたい場合は、代わりに branches-ignore を使用します。 同様に、! 文字を含むタグを定義する場合は、! 文字を含まないタグも 1 つ以上定義する必要があります。 タグの除外のみを行いたい場合は、代わりに tags-ignore を使用します。

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

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

次のワークフローは、否定パターン !releases/**-alpha が肯定パターンに従うため、releases/10 または releases/beta/mona へのプッシュで実行され、releases/10-alpha または releases/beta/3-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 のフィルターの両方をワークフロー内の同じイベントで使うことはできません。

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/**'

例: パスの包含および除外

1 つのワークフローで同じイベントのフィルター処理をするために paths と paths-ignore を使用することはできません。 1 つのイベントに対してパス パターンの包含と除外の両方を行う場合は、paths フィルターと ! 文字を使用して、除外するパスを指定します。

! 文字を含むパスを定義する場合は、! 文字を含まないパスも 1 つ以上定義する必要があります。 パスの除外のみを行いたい場合は、代わりに paths-ignore を使用します。

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

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

ファイルが sub-project/docs ディレクトリに存在しない限り、push イベントが sub-project ディレクトリまたはそのサブディレクトリのファイルを含む場合は、この例はいつでも実行されます。 たとえば、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 は、ヘッド SHA とベース SHA を互いに直接比較します。
• 新しいブランチへのプッシュ: プッシュされた最も深いコミットの先祖の親に対するツードット diff です。

diff は 300 個のファイルに制限されます。 フィルターによって返された最初の 300 個のファイルに一致しないファイルが変更された場合、ワークフローは実行されません。 ワークフローが自動的に実行されるように、より具体的なフィルターを作成する必要がある場合があります。

詳細については、「pull request でのブランチの比較について」を参照してください。

on.schedule

on.schedule を使用すると、ワークフローの時間スケジュールを定義できます。 ワークフローを特定の UTC 時刻に実行するように、POSIX cron 構文でスケジュールすることができます。 スケジュールしたワークフローは、デフォルトまたはベースブランチの直近のコミットで実行されます。 スケジュールされたワークフローを実行できる最短の間隔は、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 * * *'

1 つのワークフローを、複数の schedule イベントでトリガーできます。 github.event.schedule のコンテキストを使用して、ワークフローをトリガーしたスケジュール イベントにアクセスできます。 この例では、毎週月曜日から木曜日の 5 時 30 分 (UTC) にワークフローが実行されますが、月曜日と水曜日の Not on Monday or 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. For more information, see 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.

Example

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 }}

For more information, see "Reusing workflows."

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.

Example

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. For more information, see "Reusing workflows."

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.

Example

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 パターンの詳細については、「フィルター パターンのチート シート」を参照してください。

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

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

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

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

branches と branches-ignore のフィルターの両方をワークフロー内の同じイベントで使うことはできません。 1 つのイベントに対して分岐パターンの適用と除外の両方を行う場合は、branches フィルターと ! 文字を使用して、除外する分岐を指定します。

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

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

たとえば、次のトリガーを持つワークフローは、名前が releases/10 または releases/beta/mona で始まるブランチで Build という名前のワークフローが稼働している場合にのみ実行されますが、releases/10-alpha、releases/beta/3-alpha または 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' 
        type: choice
        options:
        - info
        - warning
        - debug 
      print_tags:
        description: 'True to print to STDOUT'
        required: true 
        type: boolean 
      tags:
        description: 'Test scenario tags'
        required: true 
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true 

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

permissions

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

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

利用できるスコープとアクセスの値は以下のとおりです。

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

これらのスコープのいずれかにアクセス権を指定すると、指定されていないすべてのスコープが none に設定されます。

利用可能なすべてのスコープに対する読み取りあるいは書き込みアクセス権を定義するためには、以下の構文が使えます。

permissions: read-all|write-all

次の構文を使用して、使用可能なすべてのスコープのアクセス許可を無効にすることができます。

permissions: {}
``` `permissions` キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で **[Send write tokens to workflows from pull requests]\(pull request からワークフローに書き込みトークンを送信する\)** を選択している場合があります。 詳細については、「[リポジトリの GitHub Actions 設定の管理](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)」を参照してください。

### 例: GITHUB_TOKEN にアクセス許可を割り当てる

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

```yaml
name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

A map of environment variables that are available to the steps of all jobs in the workflow. You can also set environment variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env and jobs.<job_id>.steps[*].env.

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

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

Example

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

同じコンカレンシー グループを使うジョブまたはワークフローを一度に 1 つだけ実行するには、concurrency を使います。 並行処理グループには、任意の文字列または式を使用できます。 この式には github コンテキストのみを使用できます。 式の詳細については、「式」を参照してください。

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

並行ジョブかワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中だと、キューイングされたジョブかワークフローは pending になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、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 で構成されます。 ジョブを順番に実行するには、jobs.<job_id>.needs キーワードを使用して他のジョブへの依存関係を定義できます。

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

ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳細については、GitHub がホストするランナーの「使用量制限と課金」とセルフホステッド ランナーの使用制限の「セルフホステッド ランナーについて」

ワークフロー実行で実行されているジョブの一意識別子を見つける必要がある場合は、GitHub Enterprise Server API を使用できます。 詳細については、「ワークフロー ジョブ」を参照してください。

jobs.<job_id>

ジョブへの一意の識別子の指定には、jobs.<job_id> を使います。 job_id キーは文字列で、その値はジョブの設定データのマップです。 <job_id> は、jobs オブジェクトに固有の文字列に置き換える必要があります。 <job_id> は文字または _ で始まり、英数字、-、あるいは _ のみを含める必要があります。

例: ジョブを作成する

この例では、job_id 値が my_first_job と my_second_job の 2 つのジョブが作成されました。

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

jobs.<job_id>.name

GitHub UI に表示されるジョブの名前の設定に jobs.<job_id>.name を使用します。

jobs.<job_id>.permissions

特定のジョブについて、jobs.<job_id>.permissions を使用して GITHUB_TOKEN に付与された既定のアクセス許可を変更し、必要に応じてアクセスを追加または削除することで、必要最小限のアクセスのみを許可することができます。 詳細については「ワークフローで認証する」を参照してください。

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

利用できるスコープとアクセスの値は以下のとおりです。

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

これらのスコープのいずれかにアクセス権を指定すると、指定されていないすべてのスコープが none に設定されます。

利用可能なすべてのスコープに対する読み取りあるいは書き込みアクセス権を定義するためには、以下の構文が使えます。

permissions: read-all|write-all

次の構文を使用して、使用可能なすべてのスコープのアクセス許可を無効にすることができます。

permissions: {}
``` `permissions` キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で **[Send write tokens to workflows from pull requests]\(pull request からワークフローに書き込みトークンを送信する\)** を選択している場合があります。 詳細については、「[リポジトリの GitHub Actions 設定の管理](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks)」を参照してください。

#### 例: 特定のジョブのアクセス許可の設定

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

```yaml
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つのジョブが失敗した場合、失敗したジョブを続行するような条件式を使用していない限り、そのジョブを必要としている他のジョブはすべてスキップされます。 互いを必要とするジョブが実行に含まれていると、エラー時点以降、依存関係チェーン内のすべてのジョブにエラーが適用されます。

例: 依存ジョブの成功が必要である

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 という組織内にある場合のみ実行されます。 それ以外の場合、ジョブはスキップ済みとしてマーク されます。

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

jobs.<job_id>.runs-on

jobs.<job_id>.runs-on を使って、ジョブを実行するマシンの種類を定義します。 runs-on は単一の文字列か、文字列の配列として指定できます。 文字列の配列を指定した場合、ワークフローは、ラベルが指定された runs-on 値のすべてに一致するセルフホステッド ランナーで実行されます (使用可能な場合)。 複数のマシンでワークフローを実行する場合は、jobs.<job_id>.strategy を使います。

GitHub ホステッド ランナーの選択

GitHub ホステッド ランナーを使うと、各ジョブは 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 と url を含む環境オブジェクトという形式で環境を指定できます。 URL はデプロイ API の environment_url にマップされます。 デプロイ API の詳細については、「デプロイ」を参照してください。

例: 1 つの環境名を使う

environment: staging_environment

例: 環境名と URL を使う

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

URL は式で指定できます。また、secrets コンテキストを除く任意のコンテキストを使用できます。 式の詳細については、「式」を参照してください。

例: 出力を URL として使う

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

jobs.<job_id>.concurrency

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

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

並行ジョブかワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中だと、キューイングされたジョブかワークフローは pending になります。 この並行グループ内の以前の保留中のジョブもしくはワークフローは、キャンセルされます。 同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、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 文字列であり、最大 1 MB となります。 ワークフロー実行内のすべての出力の合計は、最大 50 MB です。

表現が含まれているジョブの出力は、各ジョブの終了時にランナー上で評価されます。 シークレットを含む出力はランナー上で編集され、GitHub Actionsには送られません。

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

例: ジョブの出力の定義

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    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

A map of environment variables that are available to all steps in the job. You can also set environment variables for the entire workflow or an individual step. For more information, see env and jobs.<job_id>.steps[*].env.

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

Example

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

A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

You can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see "Usage limits and billing" for GitHub-hosted runners and "About self-hosted runners" for self-hosted runner usage limits.

Example

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

A unique identifier for the step. You can use the id to reference the step in contexts. For more information, see "Contexts."

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

You can use the if conditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.

if 条件の中で式を使う際には、式構文 (${{ }})を省略できます。これは、GitHub が if 条件を式として自動的に評価するためです。 For more information, see "Expressions."

Example: Using contexts

This step only runs when the event type is a pull_request and the event action is 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

The my backup step only runs when the previous step of a job fails. 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

A name for your step to display on GitHub.

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

Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

• Using the commit SHA of a released action version is the safest for stability and security.
• If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
• Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Some actions require inputs that you must set using the with keyword. Review the action's README file to determine the inputs required.

Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see 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}

A subdirectory in a public GitHub repository at a specific branch, ref, or 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

The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.

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}

A Docker image published on Docker Hub.

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}

A Docker image in a public registry. This example uses the Google Container Registry at gcr.io.

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

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as an encrypted secret. For more information, see "Creating a personal access token" and "Encrypted secrets."

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

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

Runs command-line programs using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.

Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell.

Each run keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:

• A single-line command:

  - name: Install Dependencies
    run: npm install
  

• A multi-line command:

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

Using the working-directory keyword, you can specify the working directory of where to run the command.

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

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

You can override the default shell settings in the runner's operating system using the shell keyword. You can use built-in shell keywords, or you can define a custom set of shell options. 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

Example: Using PowerShell Desktop to run a script

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

Custom shell

You can set the shell value to a template string using command […options] {0} [..more_options]. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

For example:

steps:
  - name: Display the environment variables and their values
    run: |
      print %ENV
    shell: perl {0}

The command used, perl in this example, must be installed on the runner.

Exit codes and error action preference

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

• 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. For example, bash {0}.
  • sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.

• powershell/pwsh

  • Fail-fast behavior when possible. For pwsh and powershell built-in shell, we will prepend $ErrorActionPreference = 'stop' to script contents.
  • We append if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } to powershell scripts so action statuses reflect the script's last exit code.
  • Users can always opt out by not using the built-in shell, and providing a custom shell option like: pwsh -File {0}, or powershell -Command "& '{0}'", depending on need.

• cmd

  • There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
  • cmd.exe will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous sh and pwsh default behavior and is the cmd.exe default, so this behavior remains intact.

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

A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

Example

Defines the three input parameters (first_name, middle_name, and last_name) defined by the hello_world action. These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

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

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter.

Example

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.

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

1. Document required arguments in the action's README and omit them from the CMD instruction.
2. Use defaults that allow using the action without specifying any args.
3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.

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

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

Example

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

The entrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

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

Sets environment variables for steps to use in the runner environment. You can also set environment variables for the entire workflow or a job. For more information, see env and jobs.<job_id>.env.

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

Public actions may specify expected environment variables in the README file. If you are setting a secret in an environment variable, you must set secrets using the secrets context. For more information, see "Using environment variables" and "Contexts."

Example

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

jobs.<job_id>.steps[*].timeout-minutes

The maximum number of minutes to run the step before killing the process.

jobs.<job_id>.timeout-minutes

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 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. マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。 たとえば、マトリックス戦略を使用して、複数バージョンの言語または複数のオペレーティング システムでコードをテストできます。 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]

ジョブは、変数の可能な組み合わせごとに実行されます。 この例のワークフローでは 6 つのジョブが、os 変数と version 変数の組み合わせごとに 1 つずつ実行されます。

既定で、GitHub Enterprise Server は、ランナーの可用性に応じて並列実行されるジョブの数を最大化します。 マトリックス内の変数の順序によって、ジョブが作成される順序が決まります。 定義する最初の変数は、ワークフローの実行で最初に作成されるジョブになります。 たとえば、上記のマトリックスでは、次の順序でジョブが作成されます。

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

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

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

Example: Using a single-dimension matrix

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

たとえば、次のワークフローでは、変数 version に値 [10, 12, 14] を定義しています。 このワークフローでは、変数の値ごとに 1 つずつ、3 つのジョブが実行されます。 各ジョブは、matrix.version コンテキストを通して 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 変数の組み合わせごとに 1 つずつ、計 6 つのジョブが実行されます。 各ジョブは、runs-on の値を現在の os の値に設定し、現在の version の値を actions/setup-node アクションに渡します。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.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 リスト内の各オブジェクトに対して、キーと値のペアのいずれも元のマトリックス値を上書きしない場合、オブジェクト内のキーと値のペアが各マトリックスの組み合わせに追加されます。 オブジェクトをどのマトリックスの組み合わせにも追加できない場合は、代わりに新しいマトリックスの組み合わせが作成されます。 元のマトリックス値は上書きされませんが、追加されたマトリックス値は上書きできます。

たとえば、次のマトリックスを見てください。

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} は、値を上書きせずに元のマトリックスの組み合わせに追加できないため、追加のマトリックスの組み合わせとして追加されます。 この組み合わせは、元のマトリックスの組み合わせの 1 つではないため、{fruit: banana} マトリックスの組み合わせには追加されません。

Example: Expanding configurations

たとえば、次のワークフローでは、os と node の組み合わせごとに 1 つずつ、計 6 つのジョブが実行されます。 os の値が windows-latest で node の値が 16 のジョブが実行されると、6 の値を持つ npm という追加の変数がジョブに含まれます。

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

たとえば、このマトリックスでは 10 個のジョブが実行されます。マトリックス内の os と version の組み合わせごとに 1 つと、windows-latest の os 値と 17 の version 値のジョブです。

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

マトリックス変数を指定しない場合は、include の下のすべての構成が実行されます。 たとえば、次のワークフローでは、include エントリごとに 1 つずつ、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 個の構成ごとに 1 つのジョブで、{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 と jobs.<job_id>.continue-on-error を使用して、ジョブ エラーの処理方法制御できます。

jobs.<job_id>.strategy.fail-fast はマトリックス全体に適用されます。 jobs.<job_id>.strategy.fail-fast が true に設定されている場合、マトリックス内のいずれかのジョブが失敗すると、GitHub Enterprise Server によってマトリックス内の進行中およびキューに入れられたすべてのジョブがキャンセルされます。 このプロパティでは、既定値が true に設定されます。

jobs.<job_id>.continue-on-error は 1 つのジョブに適用されます。 jobs.<job_id>.continue-on-error が true の場合、jobs.<job_id>.continue-on-error: true が失敗するジョブであっても、マトリックス内の他のジョブは引き続き実行されます。

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

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

jobs.<job_id>.strategy.max-parallel

既定で、GitHub Enterprise Server は、ランナーの可用性に応じて並列実行されるジョブの数を最大化します。 matrix ジョブ戦略を使うとき、同時に実行できるジョブの最大数を設定するには、jobs.<job_id>.strategy.max-parallel を使います。

たとえば、次のワークフローでは、6 つのジョブすべてを一度に実行できるランナーがある場合でも、一度に最大 2 つのジョブを実行します。

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

jobs.<job_id>.continue-on-error

Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

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

You can allow specific jobs in a job matrix to fail without failing the 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-latest]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-latest
        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

イメージのコンテナー レジストリでイメージをプルするための認証が必要な場合は、jobs.<job_id>.container.credentials を使って username と password の map を設定できます。 資格情報は、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 を使用して、コンテナーで公開するポートの array を設定します。

jobs.<job_id>.container.volumes

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

jobs.<job_id>.container.options を使用して、追加の Docker コンテナー リソース オプションを構成します。 オプションのリストについては、「docker create オプション」を参照してください。

jobs.<job_id>.services

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.

If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.

For more information about the differences between networking service containers, see "About service containers."

Example: Using localhost

This example creates two services: nginx and redis. When you specify the Docker host port but not the container port, the container port is randomly assigned to a free port. GitHub sets the assigned container port in the ${{job.services.<service_name>.ports}} context. In this example, you can access the service container ports using the ${{ job.services.nginx.ports['8080'] }} and ${{ job.services.redis.ports['6379'] }} contexts.

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map TCP port 6379 on Docker host to a random free port on the Redis container
    ports:
      - 6379/tcp

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

The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.

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

イメージのコンテナー レジストリでイメージをプルするための認証が必要な場合は、jobs.<job_id>.container.credentials を使って username と password の map を設定できます。 資格情報は、docker login コマンドに指定するのと同じ値です。

Example

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

Sets a map of environment variables in the service container.

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

Sets an array of ports to expose on the service container.

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

Sets an array of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path:

<source>:<destinationPath>.

The <source> is a volume name or an absolute path on the host machine, and <destinationPath> is an absolute path in the container.

Example

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

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

Additional Docker container resource options. For a list of options, see "docker create options."

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} for reusable workflows in public or internal repositories.
• ./.github/workflows/{filename} for reusable workflows in the same repository.

{ref} can be a SHA, a release tag, or a branch name. Using the commit SHA is the safest for stability and security. For more information, see "Security hardening for GitHub Actions." If you use the second syntax option (without {owner}/{repo} and @{ref}) the called workflow is from the same commit as the caller workflow.

Example

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

For more information, see "Reusing workflows."

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.

Example

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.

Example

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

jobs.<job_id>.secrets.<secret_id>

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

Allowed expression contexts: github, needs, and secrets.

Filter pattern cheat sheet

You can use special characters in path, branch, and tag filters.

• *: Matches zero or more characters, but does not match the / character. For example, Octo* matches Octocat.
• **: Matches zero or more of any character.
• ?: Matches zero or one of the preceding character.
• +: Matches one or more of the preceding character.
• [] Matches one character listed in the brackets or included in ranges. Ranges can only include a-z, A-Z, and 0-9. For example, the range[0-9a-z] matches any digit or lowercase letter. For example, [CB]at matches Cat or Bat and [1-2]00 matches 100 and 200.
• !: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.

The characters *, [, and ! are special characters in YAML. If you start a pattern with *, [, or !, you must enclose the pattern in quotes. Also, if you use a flow sequence with a pattern containing [ and/or ], the pattern must be enclosed in quotes.

# Valid
branches:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
branches:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]

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."

Patterns to match branches and tags

Patterns to match file paths

Path patterns must match the whole path, and start from the repository's root.