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

ワークフローの名前です。 GitHub では、ワークフローの名前がリポジトリの [アクション] タブに表示されます。name を省略すると、GitHub は、リポジトリのルートに対して相対的なワークフロー ファイル パスを表示します。

run-name

The name for workflow runs generated from the workflow. GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If run-name is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by a push or pull_request event, it is set as the commit message or the title of the pull request.

This value can include expressions and can reference the github and inputs contexts.

Example of run-name

run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}

on

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

ワークフローをトリガーできる 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

各イベントとそのアクティビティの種類の詳細については、「Events that trigger workflows」を参照してください。

フィルターを使用する

一部のイベントには、ワークフローを実行するタイミングをより細かく制御できるフィルターがあります。

たとえば、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 の配列を使用できます。 各イベントとそのアクティビティの種類の詳細については、「Events that trigger workflows」を参照してください。

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/paths-ignore の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

branches と branches-ignore のキーワードは、複数のブランチ名に一致する文字 (*、**、+、?、! など) を使用する glob パターンを受け入れます。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な場合は、\ でこれらの各特殊文字をエスケープする必要があります。 glob パターンの詳細については、Workflow syntax for GitHub Actions を参照してください。

Example: Including branches

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

マージ前にパスするためにワークフローが必要な場合は、パスまたはブランチ フィルターを使用してワークフローの実行をスキップしないでください。 詳細については、「ワークフロー実行をスキップする」および「ルールセットで使用できるルール」を参照してください。

ブランチ フィルター、パス フィルター、または コミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

Example: Excluding branches

パターンが branches-ignore パターンと一致する場合、ワークフローは実行されません。 branches-ignore で定義されているパターンは、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'

Example: Including and excluding branches

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/paths-ignore の両方を定義すると、ワークフローは両方のフィルターが満たされた場合にのみ実行されます。

branches、branches-ignore、tags、および tags-ignore のキーワードは、複数のブランチまたはタグ名に一致する文字 (*、**、+、?、! など) を使用する glob パターンを許容します。 名前にこれらの文字のいずれかが含まれており、リテラルの一致が必要な場合は、\ でこれらの各特殊文字を_エスケープ_する必要があります。 glob パターンの詳細については、Workflow syntax for GitHub Actions を参照してください。

Example: Including branches and tags

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

Example: Excluding branches and tags

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

• mona/octocat という名前のブランチ (refs/heads/mona/octocat)
• releases/beta/3-alpha のように名前が releases/**-alpha と一致する ブランチ (refs/heads/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.*

Example: Including and excluding branches and tags

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 のフィルターの両方をワークフロー内の同じイベントで使うことはできません。 1 つのイベントに対してパス パターンの包含と除外の両方を行う場合は、除外するパスを示すために! 文字を接頭辞にしたpathsフィルタを使用します。

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

paths と paths-ignore のキーワードは、複数のパス名と一致するために * と ** のワイルドカード文字を使用する glob パターンを受け入れます。 詳細については、「Workflow syntax for GitHub Actions」を参照してください。

Example: Including paths

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

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

マージ前にパスするためにワークフローが必要な場合は、パスまたはブランチ フィルターを使用してワークフローの実行をスキップしないでください。 詳細については、「ワークフロー実行をスキップする」および「ルールセットで使用できるルール」を参照してください。

パス フィルター、ブランチ フィルター、またはコミット メッセージのためにワークフローがスキップされる場合、そのワークフローに関連付けられているチェックは "保留中" 状態のままになります。 これらのチェックを成功させる必要がある pull request は、マージが禁止されます。

Example: Excluding paths

すべてのパス名が paths-ignore のパターンと一致する場合、ワークフローは実行されません。 パス名が paths-ignore のパターンと一致しない場合は、一部のパス名がパターンと一致する場合でも、ワークフローが実行されます。

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

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

Example: Including and excluding paths

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

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

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

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

ファイルが 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 comparisons

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

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

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

詳しくは、「プルリクエスト中でのブランチの比較について」をご覧ください。

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 構文の詳細については、「Events that trigger workflows」を参照してください。

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 ワークフローの再利用.

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. For more information, see Accessing contextual information about workflow runs.

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

Example of on.workflow_call.inputs

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 ワークフローの再利用.

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 of on.workflow_call.outputs

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 ワークフローの再利用.

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 of on.workflow_call.secrets

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:
    # passing the secret to an action
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

  # passing the secret to a nested reusable workflow
  pass-secret-to-workflow:
    uses: ./.github/workflows/my-workflow
    secrets:
       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 パターンの詳細については、Workflow syntax for GitHub Actions を参照してください。

たとえば、次のトリガーを持つワークフローは、名前が 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

workflow_dispatch イベントを使用すると、必要に応じてワークフローに渡される入力を指定できます。

このトリガーは、ワークフロー ファイルが既定のブランチにある場合に限りイベントを受信します。

on.workflow_dispatch.inputs

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

Example of on.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 }} 

on.workflow_dispatch.inputs.<input_id>.required

A boolean specifying whether the input must be supplied.

on.workflow_dispatch.inputs.<input_id>.type

The value of this parameter is a string specifying the data type of the input. This must be one of: boolean, choice, number, environment or string.

permissions

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

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

以下の表に示すように、使用可能なアクセス許可ごとに、read (該当する場合)、write、または none のいずれかのアクセス レベルを割り当てることができます。 write には read が含まれます。 これらのアクセス許可のいずれかにアクセスを指定すると、指定されていないすべてのアクセス許可が none に設定されます。

使用可能なアクセス許可と、それぞれがアクションに実行を許可する内容の詳細:

Defining access for the GITHUB_TOKEN scopes

permissions キー内で使用可能なアクセス許可の値として read、write、または none を指定することで、GITHUB_TOKEN が許可するアクセスを定義できます。

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
  security-events: read|write|none
  statuses: read|write|none

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

利用可能なすべてのアクセス許可に対して read-all または write-all どちらかのアクセスを定義するには、以下の構文が使えます。

permissions: read-all

permissions: write-all

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

permissions: {}

Changing the permissions in a forked repository

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で [Send write tokens to workflows from pull requests](pull request からワークフローに書き込みトークンを送信する) を選択している場合があります。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」をご覧ください。

Setting the GITHUB_TOKEN permissions for all jobs in a workflow

You can specify permissions at the top level of a workflow, so that the setting applies to all jobs in the workflow.

Example: Setting the GITHUB_TOKEN permissions for an entire workflow

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

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

A map of variables that are available to the steps of all jobs in the workflow. You can also set 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 of env

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

defaults.run.shell

shell を使用してステップの shell を定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

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

defaults.run.working-directory

working-directory を使用してステップの shell の作業ディレクトリを定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

concurrency

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

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

つまり、コンカレンシー グループには、最大 1 つの実行ジョブと 1 つの保留中のジョブが存在できることを意味します。 並行ジョブかワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中だと、キューイングされたジョブかワークフローは pending になります。 同じコンカレンシー グループ内の既存の pending ジョブまたはワークフロー (存在する場合) は取り消され、キューに登録された新規ジョブまたはワークフローがその代わりに使用されます。

同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、cancel-in-progress: true を指定します。 同じコンカレンシー グループ内で現在実行中のジョブまたはワークフローを条件付きで取り消すには、許可されている式コンテキストのいずれかを含む式として cancel-in-progress を指定 できます。

例：コンカレンシーとデフォルトビヘイビアーの使用

GitHub Actions のデフォルトビヘイビアーでは、複数のジョブまたはワークフロー実行を同時開催で実行できます。 concurrency キーワード を使用すると、ワークフロー実行のコンカレンシーを制御できます。

たとえば、トリガー条件が定義された直後にconcurrencyキーワード を使用して、特定のブランチに対するワークフロー実行全体のコンカレンシーを制限できます：

on:
  push:
    branches:
      - main

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

ジョブ レベルでconcurrencyキーワード を使用して、ワークフロー内のジョブのコンカレンシーを制限することもできます：

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

例: コンカレンシー グループ

コンカレンシー グループは、同じコンカレンシー 鍵を共有するワークフロー実行またはジョブの実行を管理および制限する方法を提供します。

concurrency 鍵は、ワークフローまたはジョブをまとめてコンカレンシー グループにグループ化するために使用されます。 concurrency鍵を定義すると、GitHub Actions によって、その鍵を持つワークフローまたはジョブが常に 1 つだけ実行されるようになります。 新しいワークフローの実行またはジョブが同じ concurrency 鍵で開始された場合、GitHub Actions はその鍵で既に実行されているワークフローまたはジョブをキャンセルします。 concurrency鍵は 、ハードコーディングされた文字列にすることも、コンテキスト変数を含む動的な式にすることもできます。

ワークフローまたはジョブがコンカレンシー グループの一部になるように、ワークフローでコンカレンシー条件を定義できます。

つまり、ワークフローの実行またはジョブが開始されると、GitHub は、同じコンカレンシー グループで既に進行状況にあるワークフローの実行またはジョブをキャンセルします。 これは、競合を引き起こしたり、必要以上に多くのリソースを消費したりする可能性のある処置を防ぐために、ステージング環境への展開に使用されるワークフローやジョブの特定のセットに対する並列実行を防ぐ場合に便利です。

この例では、 job-1は、staging_environmentと名付けられたコンカレンシー グループの一部です。 つまり、新しいjob-1 の実行がトリガーされると、既に進行状況の staging_environmentコンカレンシー グループ内の同じジョブの実行はすべてキャンセルされます。

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

または、ワークフロー内などの concurrency: ci-${{ github.ref }}のような 動的な式を使用すると、ワークフローまたはジョブは、ワークフローをトリガーしたブランチまたはタグのリファレンスに続く ci-と名付けられたコンカレンシー グループの一部になります。 この例では、前の実行の進行中に新しいコミットが メイン ブランチにプッシュされた場合、前の実行はキャンセルされ、新しいコミットが開始されます：

on:
  push:
    branches:
      - main

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

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

コンカレンシーを使用して進行状況のジョブをキャンセルするか、GitHub Actions で実行するには、concurrency鍵を使用でき、次のcancel-in-progressオプションをtrueに設定します：

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

この例では、特定のコンカレンシー グループを定義せずに、GitHub Actions はジョブまたはワークフローの_どんな_進行状況の実行もキャンセルします。

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

特定のイベントにのみ定義されるプロパティでグループ名を作成する場合、フォールバック値を使用できます。 たとえば、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

例: 特定のブランチで進行中のジョブのみを取り消す

特定のブランチで進行中のジョブを取り消したいが、他のブランチでは取り消さない場合は、cancel-in-progress で条件式を使用できます。 たとえば、開発ブランチでは進行中のジョブを取り消したいが、リリース ブランチでは取り消さない場合に、これを行うことができます。

リリース ブランチで実行されていない場合に、同じワークフローの進行中の実行のみを取り消すには、cancel-in-progress を次のような式に設定します。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

この例では、release/1.2.3 ブランチへの複数のプッシュは進行中の実行を取り消しません。 main などの別のブランチにプッシュすると、進行中の実行が取り消されます。

jobs

ワークフロー実行は、既定で並列実行される 1 つ以上の jobs で構成されます。 ジョブを順番に実行するには、jobs.<job_id>.needs キーワードを使用して他のジョブへの依存関係を定義できます。

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

ワークフローの利用限度内であれば、実行するジョブ数に限度はありません。 詳細情報が必要な場合、GitHub ホスト ランナーについては「使用制限、支払い、管理」を、自己ホストランナーの使用制限については「Usage limits for self-hosted runners」を参照してください。

ワークフロー実行で実行中のジョブの一意識別子を確認する必要がある場合は、GitHub API を使用できます。 詳しくは、「GitHub Actions 用の REST 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 を参照してください。

以下の表に示すように、使用可能なアクセス許可ごとに、read (該当する場合)、write、または none のいずれかのアクセス レベルを割り当てることができます。 write には read が含まれます。 これらのアクセス許可のいずれかにアクセスを指定すると、指定されていないすべてのアクセス許可が none に設定されます。

使用可能なアクセス許可と、それぞれがアクションに実行を許可する内容の詳細:

Defining access for the GITHUB_TOKEN scopes

permissions キー内で使用可能なアクセス許可の値として read、write、または none を指定することで、GITHUB_TOKEN が許可するアクセスを定義できます。

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
  security-events: read|write|none
  statuses: read|write|none

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

利用可能なすべてのアクセス許可に対して read-all または write-all どちらかのアクセスを定義するには、以下の構文が使えます。

permissions: read-all

permissions: write-all

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

permissions: {}

Changing the permissions in a forked repository

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で [Send write tokens to workflows from pull requests](pull request からワークフローに書き込みトークンを送信する) を選択している場合があります。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」をご覧ください。

Example: Setting the GITHUB_TOKEN permissions for one job in a workflow

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

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v9

jobs.<job_id>.needs

jobs.<job_id>.needs を使って、このジョブの実行前に正常に完了する必要があるジョブを示します。 文字列型または文字列の配列です。 ジョブが失敗またはスキップされた場合、そのジョブを必要とするすべてのジョブは、そのジョブが継続する条件式を使っていない限り、スキップされます。 互いに必要とする一連のジョブが実行に含まれている場合、失敗またはスキップの時点から、依存関係チェーン内のすべてのジョブに失敗またはスキップが適用されます。 依存しているジョブが成功しなかった場合でもジョブを実行する場合は、jobs.<job_id>.if のalways() 条件式を使用します。

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

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 が成功したかどうかに関係なく、完了後に常に実行されます。 詳しくは、「Evaluate expressions in workflows and actions」をご覧ください。

jobs.<job_id>.if

jobs.<job_id>.if 条件文を使って、条件が満たされなければジョブを実行しないようにできます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。 このキーでサポートされているコンテキストの詳細については、「Accessing contextual information about workflow runs」を参照してください。

if 条件の中で式を使う際には、任意で式構文 ${{ }} を省略できます。これは、GitHub Actions が if 条件を式として自動的に評価するためです。 ただし、この例外はどこでも適用されるわけではありません。

! は YAML 形式で予約された表記であるため、必ず${{ }} 構文の式を使用するか、式が ! で始まる場合は ''、""、または () でエスケープする必要があります。 次に例を示します。

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

詳しくは、「Evaluate expressions in workflows and actions」をご覧ください。

例: 特定のリポジトリに対してのみジョブを実行する

この例では 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@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats

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

jobs.<job_id>.runs-on

jobs.<job_id>.runs-on を使って、ジョブを実行するマシンの種類を定義します。

• 宛先マシンは、セルフホステッド ランナーにすることができます。

• ランナーに割り当てられたラベル、グループ メンバーシップ、またはこれらの組み合わせに基づいてランナーをターゲットにすることができます。

• runs-on は次として指定できます。

  • 1 つの文字列
  • 文字列を含む 1 つの変数
  • 文字列の配列、文字列を含む変数、または両方の組み合わせ
  • group または labels キーを使用する key: value ペア

• 文字列または変数の配列を指定すると、指定された runs-on 値の全部に一致するランナー上でワークフローが実行されます。 たとえば、ここでは、ラベル linux、x64、gpu が付いているセルフホステッド ランナー上でのみジョブが実行されます。

  runs-on: [self-hosted, linux, x64, gpu]
  

  詳細については、自己ホストランナーの選択に関する記事を参照してください。

• 配列内で文字列と変数を混在させることができます。 次に例を示します。

  on:
    workflow_dispatch:
      inputs:
        chosen-os:
          required: true
          type: choice
          options:
          - Ubuntu
          - macOS
  
  jobs:
    test:
      runs-on: [self-hosted, "${{ inputs.chosen-os }}"]
      steps:
      - run: echo Hello world!
  

• 複数のマシンでワークフローを実行する場合は、jobs.<job_id>.strategy を使います。

Choosing GitHub-hosted runners

Choosing self-hosted runners

ジョブにセルフホステッド ランナーを指定するには、ワークフロー ファイルでセルフホステッド ランナーのラベルを使って runs-on を設定します。

セルフホステッド ランナーには self-hosted ラベルが付いている場合があります。 セルフホステッド ランナーを設定すると、既定では self-hosted ラベルが付与されます。 --no-default-labels フラグを渡すことでセルフホステッド ラベルが適用されないように設定できます。 ラベルを使用すると、オペレーティング システムやアーキテクチャなど、特定のランナーを探すオプションを作成できます。self-hosted で始まり (リストの最初にこれを示す必要があります)、必要に応じて追加のラベルを含むラベルの配列を指定することをお勧めします。 ラベルの配列を指定すると、指定したラベルをすべて持つランナーのキューにジョブが入れられます。

Action-runner-controller は複数のラベルには対応していません。また、self-hosted ラベルにも対応していない点にご注意ください。

例: ランナー選択のためのラベルの使用

runs-on: [self-hosted, linux]

詳細については、「自己ホスト ランナーの概要」および「ワークフローでのセルフホストランナーの利用」を参照してください。

Choosing runners in a group

runs-on を使用してランナー グループをターゲットにして、そのグループのメンバーである任意のランナーでジョブが実行されるようにすることができます。 よりきめ細かく制御するには、ランナー グループとラベルを組み合わせることもできます。

例: グループを使用してジョブの実行場所を制御する

この例では、Ubuntu ランナーが ubuntu-runners というグループに追加されています。 runs-on キーは、ubuntu-runners グループ内の使用可能なランナーにジョブを送信します。

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: 
      group: ubuntu-runners
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

例: グループとラベルの組み合わせ

グループとラベルを組み合わせる場合、ランナーはジョブを実行する資格を得るために両方の要件を満たす必要があります。

この例では、ubuntu-runners というランナー グループに、ラベル ubuntu-20.04-16core も割り当てられている Ubuntu ランナーが設定されています。 runs-on キーは group と labels を組み合わせて、ラベルが一致するグループ内の使用可能な任意のランナーにジョブがルーティングされるようにします。

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-20.04-16core
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

例: プレフィックスを使用してランナー グループを区別する

たとえば、Organization 内に my-group という名前のランナー グループがあり、Enterprise 内に my-group という名前のランナー グループがある場合は、ワークフロー ファイルを更新して、org/my-group または ent/my-group を使用して 2 つを区別できます。

org/の使用

runs-on:
  group: org/my-group
  labels: [ self-hosted, label-1 ]

ent/の使用

runs-on:
  group: ent/my-group
  labels: [ self-hosted, label-1 ]

jobs.<job_id>.environment

ジョブが参照する環境を定義するには、jobs.<job_id>.environment を使います。

環境 name のみ、または name と url を含む環境オブジェクトという形式で環境を指定できます。 URL はデプロイ API の environment_url にマップされます。 配置 API の詳細については、「リポジトリの REST API エンドポイント」を参照してください。

例: 1 つの環境名を使う

environment: staging_environment

例: 環境名と URL を使う

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

url の値には式を指定できます。 使用できる式コンテキスト: github、inputs、vars、needs、strategy、matrix、job、runner、env、および steps。 式の詳細については、「Evaluate expressions in workflows and actions」を参照してください。

例: 出力を URL として使う

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

name の値には式を指定できます。 使用できる式コンテキスト: github、inputs、vars、needs、strategy、matrix。 式の詳細については、「Evaluate expressions in workflows and actions」を参照してください。

例: 環境名として式を使用する

environment:
  name: ${{ github.ref_name }}

jobs.<job_id>.concurrency

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

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

つまり、コンカレンシー グループには、最大 1 つの実行ジョブと 1 つの保留中のジョブが存在できることを意味します。 並行ジョブかワークフローがキューに入っている場合、リポジトリ内の同じ並行グループを使う他のジョブかワークフローが進行中だと、キューイングされたジョブかワークフローは pending になります。 同じコンカレンシー グループ内の既存の pending ジョブまたはワークフロー (存在する場合) は取り消され、キューに登録された新規ジョブまたはワークフローがその代わりに使用されます。

同じコンカレンシー グループ内の現在実行中のジョブかワークフローもキャンセルするには、cancel-in-progress: true を指定します。 同じコンカレンシー グループ内で現在実行中のジョブまたはワークフローを条件付きで取り消すには、許可されている式コンテキストのいずれかを含む式として cancel-in-progress を指定 できます。

例：コンカレンシーとデフォルトビヘイビアーの使用

GitHub Actions のデフォルトビヘイビアーでは、複数のジョブまたはワークフロー実行を同時開催で実行できます。 concurrency キーワード を使用すると、ワークフロー実行のコンカレンシーを制御できます。

たとえば、トリガー条件が定義された直後にconcurrencyキーワード を使用して、特定のブランチに対するワークフロー実行全体のコンカレンシーを制限できます：

on:
  push:
    branches:
      - main

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

ジョブ レベルでconcurrencyキーワード を使用して、ワークフロー内のジョブのコンカレンシーを制限することもできます：

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

例: コンカレンシー グループ

コンカレンシー グループは、同じコンカレンシー 鍵を共有するワークフロー実行またはジョブの実行を管理および制限する方法を提供します。

concurrency 鍵は、ワークフローまたはジョブをまとめてコンカレンシー グループにグループ化するために使用されます。 concurrency鍵を定義すると、GitHub Actions によって、その鍵を持つワークフローまたはジョブが常に 1 つだけ実行されるようになります。 新しいワークフローの実行またはジョブが同じ concurrency 鍵で開始された場合、GitHub Actions はその鍵で既に実行されているワークフローまたはジョブをキャンセルします。 concurrency鍵は 、ハードコーディングされた文字列にすることも、コンテキスト変数を含む動的な式にすることもできます。

ワークフローまたはジョブがコンカレンシー グループの一部になるように、ワークフローでコンカレンシー条件を定義できます。

つまり、ワークフローの実行またはジョブが開始されると、GitHub は、同じコンカレンシー グループで既に進行状況にあるワークフローの実行またはジョブをキャンセルします。 これは、競合を引き起こしたり、必要以上に多くのリソースを消費したりする可能性のある処置を防ぐために、ステージング環境への展開に使用されるワークフローやジョブの特定のセットに対する並列実行を防ぐ場合に便利です。

この例では、 job-1は、staging_environmentと名付けられたコンカレンシー グループの一部です。 つまり、新しいjob-1 の実行がトリガーされると、既に進行状況の staging_environmentコンカレンシー グループ内の同じジョブの実行はすべてキャンセルされます。

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

または、ワークフロー内などの concurrency: ci-${{ github.ref }}のような 動的な式を使用すると、ワークフローまたはジョブは、ワークフローをトリガーしたブランチまたはタグのリファレンスに続く ci-と名付けられたコンカレンシー グループの一部になります。 この例では、前の実行の進行中に新しいコミットが メイン ブランチにプッシュされた場合、前の実行はキャンセルされ、新しいコミットが開始されます：

on:
  push:
    branches:
      - main

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

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

コンカレンシーを使用して進行状況のジョブをキャンセルするか、GitHub Actions で実行するには、concurrency鍵を使用でき、次のcancel-in-progressオプションをtrueに設定します：

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

この例では、特定のコンカレンシー グループを定義せずに、GitHub Actions はジョブまたはワークフローの_どんな_進行状況の実行もキャンセルします。

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

特定のイベントにのみ定義されるプロパティでグループ名を作成する場合、フォールバック値を使用できます。 たとえば、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

例: 特定のブランチで進行中のジョブのみを取り消す

特定のブランチで進行中のジョブを取り消したいが、他のブランチでは取り消さない場合は、cancel-in-progress で条件式を使用できます。 たとえば、開発ブランチでは進行中のジョブを取り消したいが、リリース ブランチでは取り消さない場合に、これを行うことができます。

リリース ブランチで実行されていない場合に、同じワークフローの進行中の実行のみを取り消すには、cancel-in-progress を次のような式に設定します。

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

この例では、release/1.2.3 ブランチへの複数のプッシュは進行中の実行を取り消しません。 main などの別のブランチにプッシュすると、進行中の実行が取り消されます。

jobs.<job_id>.outputs

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

出力は、1 つのジョブにつき最大 1 MB です。 ワークフロー実行内のすべての出力の合計は、最大 50 MB です。 サイズは UTF-16 エンコードに基づいて概算されます。

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

出力に秘密情報が含まれる可能性があるためスキップされた場合、「秘密情報が含まれる可能性があるため出力{output.Key}をスキップする」という警告メッセージが表示されます。 秘密情報の取り扱い方法の詳細については、「例:ジョブまたはワークフロー間で秘密情報をマスクおよび受け渡しする方法」を参照してください。

依存するジョブでジョブ出力を使うには、needs コンテキストを使用できます。 詳しくは、「Accessing contextual information about workflow runs」をご覧ください。

例: ジョブの出力の定義

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 "test=hello" >> "$GITHUB_OUTPUT"
      - id: step2
        run: echo "test=world" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - env:
          OUTPUT1: ${{needs.job1.outputs.output1}}
          OUTPUT2: ${{needs.job1.outputs.output2}}
        run: echo "$OUTPUT1 $OUTPUT2"

マトリックス ジョブでのジョブ出力の使用

マトリックスを使用して、異なる名前の複数の出力を生成できます。 マトリックスを使用する場合、ジョブ出力はマトリックス内のすべてのジョブから結合されます。

jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      output_1: ${{ steps.gen_output.outputs.output_1 }}
      output_2: ${{ steps.gen_output.outputs.output_2 }}
      output_3: ${{ steps.gen_output.outputs.output_3 }}
    strategy:
      matrix:
        version: [1, 2, 3]
    steps:
      - name: Generate output
        id: gen_output
        run: |
          version="${{ matrix.version }}"
          echo "output_${version}=${version}" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: [job1]
    steps:
      # Will show
      # {
      #   "output_1": "1",
      #   "output_2": "2",
      #   "output_3": "3"
      # }
      - run: echo '${{ toJSON(needs.job1.outputs) }}'

jobs.<job_id>.env

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

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

Example of jobs.<job_id>.env

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 に既定の設定を設定することもできます。 詳細については、「defaults.run」を参照してください。

これらは、jobs.<job_id>.defaults.run と jobs.<job_id>.steps[*].run のレベルでオーバーライドできます。

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

jobs.<job_id>.defaults.run.shell

shell を使用してステップの shell を定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

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

jobs.<job_id>.defaults.run.working-directory

working-directory を使用してステップの shell の作業ディレクトリを定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

Example: Setting default run step options for a job

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

jobs.<job_id>.steps

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.

GitHub only displays the first 1,000 checks, however, you can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see 使用制限、支払い、管理 for GitHub-hosted runners and Usage limits for self-hosted runners for self-hosted runner usage limits.

Example of jobs.<job_id>.steps

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 Accessing contextual information about workflow runs.

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

You can use the if conditional to prevent a step from running unless a condition is met. 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。 このキーでサポートされているコンテキストの詳細については、「Accessing contextual information about workflow runs」を参照してください。

if 条件の中で式を使う際には、任意で式構文 ${{ }} を省略できます。これは、GitHub Actions が if 条件を式として自動的に評価するためです。 ただし、この例外はどこでも適用されるわけではありません。

! は YAML 形式で予約された表記であるため、必ず${{ }} 構文の式を使用するか、式が ! で始まる場合は ''、""、または () でエスケープする必要があります。 次に例を示します。

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

For more information, see Evaluate expressions in workflows and actions.

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 Evaluate expressions in workflows and actions.

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 Accessing contextual information about workflow runs and GitHub Actions でのシークレットの使用.

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@8f4b7f84864484a7bf31766abe9204da3cbe65b3
  # Reference the major version of a release
  - uses: actions/checkout@v4
  # Reference a specific version
  - uses: actions/checkout@v4.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.

リポジトリ ファイル構造の例:

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

パスはデフォルトの作業ディレクトリ (github.workspace、$GITHUB_WORKSPACE) に対する相対パス (./) です。 アクションがワークフローとは異なる場所にリポジトリをチェックアウトする場合は、ローカル アクションに使用される相対パスを更新する必要があります。

ワークフロー ファイルの例:

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-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 a secret. For more information, see 個人用アクセス トークンを管理する and GitHub Actions でのシークレットの使用.

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@v4
        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

Alternatively, use a GitHub App instead of a personal access token in order to ensure your workflow continues to run even if the personal access token owner leaves. For more information, see GitHub Actions ワークフローで GitHub App を使用して認証済み API 要求を作成する.

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

Runs command-line programs that do not exceed 21,000 characters 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
  

jobs.<job_id>.steps[*].working-directory

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

Alternatively, you can specify a default working directory for all run steps in a job, or for all run steps in the entire workflow. For more information, see defaults.run.working-directory and jobs.<job_id>.defaults.run.working-directory.

You can also use a run step to run a script. For more information, see ワークフローにスクリプトを追加する.

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

You can override the default shell settings in the runner's operating system and the job's default 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.

Alternatively, you can specify a default shell for all run steps in a job, or for all run steps in the entire workflow. For more information, see defaults.run.shell and jobs.<job_id>.defaults.run.shell.

Example: Running a command using Bash

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

Example: Running a command using Windows cmd

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

Example: Running a command using PowerShell Core

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

Example: Using PowerShell Desktop to run a command

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

Example: Running an inline Python script

steps:
  - name: Display the path
    shell: python
    run: |
      import os
      print(os.environ['PATH'])

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
    shell: perl {0}
    run: |
      print %ENV

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:

  • By default, fail-fast behavior is enforced using set -e for both sh and bash. When shell: bash is specified, -o pipefail is also applied to enforce early exit from pipelines that generate a non-zero exit status.
  • 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.

Input parameters defined for a Docker container must use args. For more information, see jobs.<job_id>.steps[*].with.args.

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

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. A single argument that includes spaces should be surrounded by double quotes "".

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

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 of jobs.<job_id>.steps[*].with.entrypoint

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

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

Public actions may specify expected variables in the README file. If you are setting a secret or sensitive value, such as a password or token, you must set secrets using the secrets context. For more information, see Accessing contextual information about workflow runs.

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

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.

Fractional values are not supported. timeout-minutes must be a positive integer.

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 使用制限、支払い、管理 for GitHub-hosted runners and Usage limits for 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 ワークフローでのジョブのバリエーションの実行.

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

• {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 ホステッド ランナーとセルフホステッド ランナーの両方に適用されます。

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

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@v4
        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@v4
        with:
          node-version: ${{ matrix.version }}

マトリックス内の変数構成は、object の array になります。

matrix:
  os:
    - ubuntu-latest
    - macos-latest
  node:
    - version: 14
    - version: 20
      env: NODE_OPTIONS=--openssl-legacy-provider

このマトリックスでは、対応するコンテキストを持つ 4 つのジョブが生成されます。

- matrix.os: ubuntu-latest
  matrix.node.version: 14
- matrix.os: ubuntu-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
  matrix.node.version: 14
- matrix.os: macos-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider

Example: Using contexts to create matrices

コンテキストを使用してマトリックスを作成できます。 コンテキストについて詳しくは、「Accessing contextual information about workflow runs」をご覧ください。

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

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

on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v4
        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 つずつ、計 4 つのジョブが実行されます。 os の値が windows-latest で node の値が 16 のジョブが実行されると、6 の値を持つ npm という追加の変数がジョブに含まれます。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        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 に設定されているか、その式が true と評価されている場合、マトリックス内のいずれかのジョブが失敗すると、進行中およびキューに入れられたすべてのジョブは GitHub によって取り消されます。 このプロパティでは、既定値が 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 の既定では、ランナーの可用性に応じて並列実行されるジョブの数が最大化されます。 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:18
      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)

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      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:18

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 サービスコンテナについて.

Example: Using localhost

This example creates two services: nginx and redis. When you specify the container port but not the host port, the container port is randomly assigned to a free port on the host. GitHub sets the assigned host port in the ${{job.services.<service_name>.ports}} context. In this example, you can access the service host ports using the ${{ job.services.nginx.ports['80'] }} 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 random free TCP port on Docker host to port 6379 on redis container
    ports:
      - 6379/tcp
steps:
  - run: |
      echo "Redis available on 127.0.0.1:${{ job.services.redis.ports['6379'] }}"
      echo "Nginx available on 127.0.0.1:${{ job.services.nginx.ports['80'] }}"

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.

If jobs.<job_id>.services.<service_id>.image is assigned an empty string, the service will not start. You can use this to set up conditional services, similar to the following example.

services:
  nginx:
    image: ${{ options.nginx == true && 'nginx' || '' }}

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

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

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

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 of jobs.<job_id>.services.<service_id>.volumes

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}。
• 同じリポジトリ内の再利用可能なワークフローの ./.github/workflows/{filename}。

最初のオプションで、{ref} には、SHA、リリース タグ、またはブランチ名を指定できます。 リリース タグとブランチの名前が同じ場合は、リリース タグがブランチの名前よりも優先されます。 コミット SHA を使用することが、安定性とセキュリティにとって最も安全なオプションです。 詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

2 番目の構文オプションを ({owner}/{repo} および @{ref} なしで) 使用する場合、呼び出されたワークフローは呼び出し元ワークフローと同じコミットから取得されます。 refs/heads や refs/tags などの ref プレフィックスは使用できません。 このキーワード中では、コンテキストや式を使うことはできません。

Example of jobs.<job_id>.uses

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 ワークフローの再利用.

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 available as environment variables in the called workflow. Instead, you can reference the inputs by using the inputs context.

Example of jobs.<job_id>.with

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 of jobs.<job_id>.secrets

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.

Example of jobs.<job_id>.secrets.inherit

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.

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 alphanumeric 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
paths:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
paths:
  - **/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.