GitHub Actions　のワークフロー構文

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

ワークフロー ファイルでは YAML 構文が使用され、ファイル拡張子 .yml または .yaml が必要です。 YAML の初心者で詳しく学びたい場合は、「Learn YAML in Y minutes」(YAML を Y 分で学ぶ) を参照してください。

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

name

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

run-name

ワークフローから生成されたワークフロー実行の名前。 GitHub では、リポジトリの [アクション] タブのワークフロー実行のリストにワークフロー実行名が表示されます。run-name が省略されているか空白のみの場合、実行名はワークフロー実行のイベント固有の情報に設定されます。 たとえば、push または pull_request イベントによってトリガーされるワークフローの場合、コミット メッセージまたは pull request のタイトルとして設定されます。

この値には式を含めることができ、github および inputs コンテキストを参照することもできます。

          `run-name` の例

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

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>

例: ブランチの包含

例: ブランチの除外

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

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 パターンの詳細については、GitHub Actions　のワークフロー構文 を参照してください。

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

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`)
  

•         `releases/**-alpha` のように名前が `releases/beta/3-alpha` と一致する ブランチ (`refs/heads/releases/beta/3-alpha`) <!-- markdownlint-disable-line outdated-release-phase-terminology -->
  

•         `v2` という名前のタグ (`refs/tags/v2`)
  

•         `v1.` のように名前が `v1.9` で始まるタグ (`refs/tags/v1.9`)
  

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

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

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

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

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

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

次のワークフローは、否定パターン releases/10 が肯定パターンに従うため、releases/beta/mona または releases/10-alpha へのプッシュで実行され、releases/beta/3-alpha または !releases/**-alpha では実行されません。

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

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

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

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

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

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

例: パスの包含

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

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

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

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

例: パスの除外

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

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

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

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

ワークフローをトリガーするパスの説明

Git diffの比較

ワークフロー > [!NOTE]

1,000 以上のコミットをプッシュする場合、あるいは GitHub がタイムアウトのために diff を生成できない場合、そのワークフローは常に実行されます。

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

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

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

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

on.schedule

          `on.schedule` を使用すると、ワークフローの時間スケジュールを定義できます。

データ 再利用可能.repositories.actions-スケジュール済み-ワークフロー-例 %}

          `schedule` イベントについて詳しくは、「[AUTOTITLE](/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule)」を参照してください。

on.workflow_call

          `on.workflow_call` は、再利用可能なワークフローの入力と出力を定義するために使います。 呼び出し対象のワークフローで使用できるシークレットをマップすることもできます。 再利用可能なワークフローについて詳しくは、「[AUTOTITLE](/actions/using-workflows/reusing-workflows)」をご覧ください。

on.workflow_call.inputs

          `workflow_call` キーワードを使う場合は、必要に応じて、呼び出し元ワークフローから呼び出し対象のワークフローに渡される入力を指定できます。 
          `workflow_call` キーワードについて詳しくは、「[AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#workflow-reuse-events)」をご覧ください。

          `on.workflow_call.inputs` には、使用可能な標準入力パラメーターに加えて `type` パラメーターが必要です。 詳細については、「[`on.workflow_call.inputs.<input_id>.type`](#onworkflow_callinputsinput_idtype)」を参照してください。

          `default` パラメーターが設定されていない場合、入力の既定値は `false` (ブール値の場合)、`0` (数値の場合)、`""` (文字列の場合) です。

呼び出し対象のワークフロー内で inputs コンテキストを使って入力を参照できます。 詳しくは、「コンテキスト リファレンス」をご覧ください。

呼び出し対象のワークフローで指定されていない入力が呼び出し元ワークフローによって渡されると、エラーが発生します。

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

詳しくは、「ワークフローを再利用する」をご覧ください。

on.workflow_call.inputs.<input_id>.type

          `on.workflow_call` キーワードに対して入力が定義されている場合は必須です。 このパラメーターの値は、入力のデータ型を指定する文字列です。 これは、`boolean`、`number`、または `string` のいずれかである必要があります。

on.workflow_call.outputs

呼び出し対象のワークフローの出力のマップ。 呼び出し対象のワークフロー出力は、呼び出し元ワークフロー内のすべてのダウンストリーム ジョブで使用できます。 各出力には、識別子、省略可能な description,、value. があります。呼び出し対象のワークフロー内のジョブからの出力の値には value を設定する必要があります。

次の例では、この再利用可能なワークフローに対して 2 つの出力 workflow_output1 と workflow_output2 が定義されています。 これらは、どちらも job_output1 というジョブから job_output2 と my_job という出力にマップされます。

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

ジョブ出力を参照する方法については、jobs.<job_id>.outputs を参照してください。 詳しくは、「ワークフローを再利用する」をご覧ください。

on.workflow_call.secrets

呼び出し対象のワークフローで使用できるシークレットのマップ。

呼び出し対象のワークフロー内で secrets コンテキストを使ってシークレットを参照できます。

呼び出し対象のワークフローで指定されていないシークレットが呼び出し元ワークフローによって渡されると、エラーが発生します。

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

シークレットに関連付ける文字列識別子。

on.workflow_call.secrets.<secret_id>.required

シークレットを指定する必要があるかどうかを指定するブール値。

on.workflow_run.<branches|branches-ignore>

on.workflow_dispatch

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

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

on.workflow_dispatch.inputs

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

          `inputs`の最上位のプロパティの最大数は、25 それ以外の %}10  です。 

          `inputs` のペイロードの最大数は 65,535 文字です。

          `on.workflow_dispatch.inputs` の例

データの再利用可能性.actions.workflow-dispatch-inputs-example %}

on.workflow_dispatch.inputs.<input_id>.required

入力を指定する必要があるかどうかを指定するブール値。

on.workflow_dispatch.inputs.<input_id>.type

このパラメーターの値は、入力のデータ型を指定する文字列です。 これは、boolean、choice、number、environmentまたはstring. のいずれかである必要があります。

permissions

データ 再利用可能.actions.jobs.ジョブに権限を割り当てるセクション %}

          `GITHUB_TOKEN` スコープのアクセスの定義

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

permissions:
  actions: read|write|none
  artifact-metadata: read|write|none
  attestations: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: write|none
  issues: read|write|none
  models: read|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: {}

フォークされたリポジトリのアクセス許可を変更する

データ再利用可能アクション.forked-書き込み許可 %}

ワークフロー ジョブのアクセス許可の計算方法

          `GITHUB_TOKEN` のアクセス許可は最初に、エンタープライズ、組織、またはリポジトリの既定値に設定されます。 デフォルトがこれらのレベルのいずれかで制限付きの権限に設定されている場合、これは関連するリポジトリに適用されます。 たとえば、Organization レベルで制限付きのデフォルトを選択した場合、その Organization 内のすべてのリポジトリは、制限付きの権限をデフォルトとして使用します。 次に、ワークフローファイル内の構成に基づいて、最初にワークフローレベルで、次にジョブレベルで権限が調整されます。 最後に、ワークフローがフォークされたリポジトリからの pull request によってトリガーされ、 **[pull request からワークフローに書き込みトークンを送信する]** 設定が選択されていない場合、アクセス許可が調整され、書き込みアクセス許可はすべて読み取り専用に変更されます。

ワークフロー内のすべてのジョブの GITHUB_TOKEN アクセス許可の設定

設定がワークフロー内のすべてのジョブに適用されるように、ワークフローの最上位レベルで permissions を指定できます。

例: ワークフロー全体の GITHUB_TOKEN アクセス許可の設定

データ 再利用可能なもの.actions.jobs.全ジョブのアクセス許可を設定する例 %}

フォークされたリポジトリに対する permissions キーの使用

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

ワークフロー実行のアクセス許可（トリガー: Dependabot）

Dependabot pull request によってトリガーされるワークフロー実行は、フォークされたリポジトリからのものであるかのように実行されるため、読み取り専用の GITHUB_TOKEN を使用します。 それらのワークフローの実行は、シークレットにはアクセスできません。 これらのワークフローをセキュリティで保護するための戦略については、「セキュリティで保護された使用に関するリファレンス」を参照してください。

env

ワークフロー中のすべてのジョブのステップで使うことができる変数の map です。 1 つのジョブのステップか 1 つのステップでしか使うことができない変数を設定することもできます。 詳細については、jobs.<job_id>.env および jobs.<job_id>.steps[*].env を参照してください。

          `env` マップ内の変数は、マップ内の他の変数の観点からは定義できません。

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

          `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

データ 再利用可能なアクション.ジョブ.セクション-同時実行の使用 %}

jobs

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

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

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

ワークフロー実行で実行中のジョブの一意識別子を確認する必要がある場合は、GitHub API を使用できます。 詳しくは、「GitHub Actionsの REST API エンドポイント」をご覧ください。

jobs.<job_id>

データの再利用可能なアクション.jobs.ワークフロー内でジョブを使用するセクション-ID %}

jobs.<job_id>.name

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

jobs.<job_id>.permissions

データ再利用可能アクション関連ジョブセクションにジョブ固有の権限を割り当てる %}

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

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

| 権限 | GITHUB_TOKEN を使ってアクションに許可する内容 | | --- | --- | | actions | GitHub Actions を操作します。 たとえば、actions: write は、アクションによるワークフロー実行の取り消しを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | artifact-metadata | 成果物メタデータを操作します。 たとえば、 artifact-metadata: write は、ビルド成果物に代わってストレージ レコードを作成するアクションを許可します。 詳しくは、「アーティファクト メタデータの REST API エンドポイント」をご覧ください。 | | | | | | attestations | 構成証明の認証作業 たとえば、 attestations: write ビルドの成果物構成証明を生成するアクションが許可されます。 詳細については、「アーティファクトの構成証明を使用して構築の実績を確立する」を参照してください | | | | checks | チェック実行とチェック スイートを操作します。 たとえば、checks: write は、アクションによるチェック実行の作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | contents | リポジトリの内容を操作します。 たとえば、contents: read はアクションによるコミットの一覧表示を許可し、contents: write はアクションによるリリースの作成を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | deployments | デプロイを操作します。 たとえば、deployments: write は、アクションによる新しいデプロイの作成アクションを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | discussions | GitHub ディスカッションで作業します。 たとえば、discussions: write は、アクションがディスカッションを閉じるか削除することを許可します。 詳しくは、「ディスカッションでのGraphQL APIの利用」をご覧ください。 | | | | id-token | OpenID Connect (OIDC) トークンをフェッチします。 これには id-token: write が必要です。 詳細については、「OpenID Connect」を参照してください | | | | issues | 問題に取り組みます。 たとえば、issues: write は、アクションがイシューにコメントを追加することを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | models | GitHub Models を使用して AI 推論応答を生成します。 たとえば、models: read は、GitHub Models 推論 API を使用するアクションを許可します。 「AI モデルを使用したプロトタイプ作成」を参照してください。 | | | | packages | GitHub Packages を操作します。 たとえば、packages: write は、アクションによる GitHub Packages でのパッケージのアップロードと発行を許可します。 詳しくは、「GitHub Packagesの権限について」をご覧ください。 | | pages | GitHub Pages を操作します。 たとえば、pages: write は、アクションによる GitHub Pages のビルドの要求を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | pull-requests | pull request を操作します。 たとえば、pull-requests: write は、アクションによる pull request へのラベルの追加を許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 | | | | security-events | GitHub のコード スキャン アラートを操作します。 たとえば、security-events: read を指定すると、アクションでリポジトリ内のコード スキャン アラートを一覧表示できるようになります。また、security-events: write を指定すると、アクションでコード スキャン アラートの状態を更新できるようになります。 詳細については、「"コード スキャン アラート" に関するリポジトリのアクセス許可」を参照してください。

このアクセス許可では、Dependabot およびシークレット スキャン アラートを読み取ることができないため、GitHub App または personal access token が必要です。 詳細については、「GitHub Apps に必要なアクセス許可」の「"Dependabot アラート" に関するリポジトリのアクセス許可」と「"シークレット スキャン アラート" に関するリポジトリのアクセス許可」を参照してください。 | | statuses | コミットの状態を操作します。 たとえば、statuses:read は、アクションが特定の参照のコミット状態を一覧表示することを許可します。 詳しくは、「GitHub Apps に必要なアクセス許可」をご覧ください。 |

          `GITHUB_TOKEN` スコープのアクセスの定義

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

permissions:
  actions: read|write|none
  artifact-metadata: read|write|none
  attestations: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  id-token: write|none
  issues: read|write|none
  models: read|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: {}

フォークされたリポジトリのアクセス許可を変更する

データ再利用可能アクション.forked-書き込み許可 %}

例: ワークフロー内の 1 つのジョブに対する GITHUB_TOKEN アクセス許可の設定

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

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v10

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 が成功したかどうかに関係なく、完了後に常に実行されます。 詳しくは、「ワークフロー内とアクション内で式を評価する」をご覧ください。

jobs.<job_id>.if

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

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

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

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

詳しくは、「ワークフロー内とアクション内で式を評価する」をご覧ください。

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

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

jobs.<job_id>.runs-on

データ再利用可能なアクション.ジョブ.ランナーを選択するための概要 %}

GitHub ホスト型ランナーの選択

GitHub ホストのランナーを選択する 方法についてのデータ詳細をご確認ください。

セルフホステッド ランナーの選択

データ 再利用可能.actions.jobs.自己ホスティングランナーを選択する %}

グループ内のランナーを選ぶ

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@v5
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

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

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

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

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-24.04-16core
    steps:
      - uses: actions/checkout@v5
      - 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>.snapshot

カスタムイメージを使用したランナーの選択に関する手順

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: https://github.com

url の値には式を指定できます。 使用できる式コンテキスト: github、inputs、vars、needs、strategy、matrix、job、runner、env、および steps。 式の詳細については、「ワークフロー内とアクション内で式を評価する」を参照してください。

例: 出力を URL として使う

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

name の値には式を指定できます。 使用できる式コンテキスト: github、inputs、vars、needs、strategy、matrix。 式の詳細については、「ワークフロー内とアクション内で式を評価する」を参照してください。

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

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

jobs.<job_id>.concurrency

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

ワークフロー レベルで 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

データ 再利用可能.actions.jobs.section-defining-outputs-for-jobs %}

jobs.<job_id>.env

ジョブ中のすべてのステップで使うことができる変数の map です。 ワークフロー全体または個々のステップの変数を設定できます。 詳細については、env および jobs.<job_id>.steps[*].env を参照してください。

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

          `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 の作業ディレクトリを定義します。 このキーワードは、複数のコンテキストを参照できます。 詳細については、「コンテキスト」を参照してください。

例: ジョブの既定の run ステップ オプションの設定

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

jobs.<job_id>.steps

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

GitHub には最初の 1,000 個のチェックのみが表示されますが、ワークフローの使用制限内であれば、無制限の数の手順を実行できます。 詳しくは、GitHub ホスト ランナーについて「課金と使用」、および自己ホストランナーの使用制限について「アクションの制限」をご覧ください。

          `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

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

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

          `if` 条件文を使って、条件が満たされなければ、ステップを実行しないようにすることができます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。 このキーでサポートされているコンテキストの詳細については、「[AUTOTITLE](/actions/learn-github-actions/contexts#context-availability)」を参照してください。

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

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

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

詳しくは、「ワークフロー内とアクション内で式を評価する」をご覧ください。

例: コンテキストの使用

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

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

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

          `my backup step` は、ジョブの前のステップが失敗した場合にのみ実行されます。 詳しくは、「[AUTOTITLE](/actions/learn-github-actions/expressions#status-check-functions)」をご覧ください。

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

例: シークレットの使用

          `if:` 条件文でシークレットを直接参照することはできません。 代わりに、シークレットをジョブ レベルの環境変数として設定し、ジョブのステップを条件付きで実行するために環境変数を参照することを検討してください。

シークレットが設定されていない場合、シークレットを参照する式の戻り値 (例では ${{ secrets.SuperSecret }} など) は空の文字列になります。

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

詳細については、「コンテキスト リファレンス」および「GitHub Actions でのシークレットの使用」を参照してください。

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

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

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

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

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

• リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
• アクションでメジャー バージョン タグが発行される場合は、互換性を維持しながら、重要な修正プログラムとセキュリティ パッチを受け取ることを予期する必要があります。 この動作は、アクションの作成者が判断するものであることに注意してください。
• アクションのデフォルトブランチを使用すると便利なこともありますが、別のユーザが破壊的変更を加えた新しいメジャーバージョンをリリースすると、ワークフローが動作しなくなる場合があります。

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

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

例: バージョン管理されたアクションの使用

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

例: パブリック アクションの使用

{owner}/{repo}@{ref}

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

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

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

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

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

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

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

./path/to/dir

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

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

|-- 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@v5
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

例: Docker Hub アクションの使用

docker://{image}:{tag}

          [Docker Hub](https://hub.docker.com/) で公開されている Docker イメージ。

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

例: GitHub Packages Container registry

の使用

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

GitHub Packages Container registry のパブリック Docker イメージ。

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

例: Docker パブリック レジストリ アクションの使用

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

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

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

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

ワークフローはプライベートリポジトリをチェックアウトし、アクションをローカルで参照する必要があります。 personal access token を生成し、シークレットとしてトークンを追加します。 詳細については、「個人用アクセス トークンを管理する」および「GitHub Actions でのシークレットの使用」を参照してください。

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

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v5
        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

あるいは、personal access token の所有者が去った後でもワークフローを実行し続けられるよう、personal access token の代わりに GitHub App を使います。 詳しくは、「GitHub Actions ワークフローでGitHub アプリを使用して認証済み API 要求を作成する」をご覧ください。

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

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

コマンドは、デフォルトでは非ログインシェルを使用して実行されます。 別のシェルを選択して、コマンドを実行するシェルをカスタマイズできます。 詳細については、「jobs.<job_id>.steps[*].shell」を参照してください。

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

• 1行のコマンド：

  - name: Install Dependencies
    run: npm install
  

• 複数行のコマンド：

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

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

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

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

または、ジョブ内のすべてのrunステップまたはワークフロー全体のすべてのrunステップに既定の作業ディレクトリを指定することもできます。 詳細については、defaults.run.working-directory および jobs.<job_id>.defaults.run.working-directory を参照してください。

          `run`ステップを使用してスクリプトを実行することもできます。 詳しくは、「[AUTOTITLE](/actions/writing-workflows/choosing-what-your-workflow-does/adding-scripts-to-your-workflow)」をご覧ください。

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

          `shell` キーワードを使用して、ランナーのオペレーティング システムのデフォルト シェル設定とジョブのデフォルトをオーバーライドできます。 組み込みの `shell` キーワードを使いことも、カスタム セットのシェル オプションを定義することもできます。 内部で実行されるシェル コマンドによって、`run` キーワードで指定されたコマンドを含む一時ファイルが実行されます。

または、ジョブのすべての run ステップまたはワークフロー全体のすべての run ステップにデフォルト シェルを指定することもできます。 詳細については、defaults.run.shell および jobs.<job_id>.defaults.run.shell を参照してください。

例: Bash を使ったコマンドの実行

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

例: Windows cmd を使ったコマンドの実行

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

例: PowerShell Core を使ったコマンドの実行

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

PowerShell Desktopを使用してコマンドを実行する例

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

例: インライン Python スクリプトの実行

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

カスタムシェル

          `shell` を使って、テンプレート文字列に `command [options] {0} [more_options]` 値を設定できます。 GitHub では、空白区切りで最初の文字列をコマンドとして解釈し、`{0}` にある一時的なスクリプトのファイル名を挿入します。

次に例を示します。

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

使われるコマンド (この例では perl) は、ランナーにインストールされている必要があります。

GitHub ホスト ランナーに含まれるソフトウェアについては、「GitHub ホステッド ランナー」をご覧ください。

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

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

•         `bash`
          /
          `sh`:
  

  • 既定では、フェイルファスト動作は、set -e と sh の両方に bash を使用して強制されます。 shell: bash が指定されている場合、ゼロ以外の終了ステータスを生成するパイプラインからの早期終了を強制するために -o pipefail も適用されます。
  • シェル オプションにテンプレート文字列を指定することで、シェル パラメーターを完全に制御できます。 たとえば、bash {0} のようにします。

  •       `sh` ライクのシェルは、スクリプトで実行された最後のコマンドの終了コードで終了します。これは、アクションの既定の動作でもあります。 runnerは、この終了コードに基づいてステップのステータスを失敗/成功としてレポートします。
    

• powershell/pwsh

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

• cmd

  • 各エラーコードをチェックしてそれぞれに対応するスクリプトを書く以外、フェイルファースト動作を完全にオプトインする方法はないようです。 デフォルトでその動作を指定することはできないため、この動作はスクリプトに記述する必要があります。

  •       `cmd.exe` は実行した最後のプログラムのエラー レベルで終了し、ランナーにエラー コードが返されます。 この動作は、内部的には前の `sh` と `pwsh` の既定の動作と一致しており、`cmd.exe` の既定であるため、この動作は変更されません。
    

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

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

Docker コンテナーに定義された入力パラメーターは args を使用する必要があります。 詳細については、「jobs.<job_id>.steps[*].with.args」を参照してください。

          `jobs.<job_id>.steps[*].with` の例

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

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

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

Docker コンテナーの入力を定義する string。 GitHub により、コンテナーの起動時に args がコンテナーのENTRYPOINT に渡されます。 array of strings はこのパラメーターではサポートされていません。 スペースを含む 1 つの引数は、二重引用符 "" で囲む必要があります。

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

          `args` は、`CMD` 内の `Dockerfile` 命令の代わりに使用されます。 ご自分の `CMD` で `Dockerfile` を使用する場合は、以下の優先順のガイドラインを使用してください。

1. アクションの README 中で必須の引数をドキュメント化し、CMD 命令から除外します。

2.        `args` を指定せずにアクションを利用できるよう、既定値を使用します。
   

3. アクションによって --help フラグなどが公開される場合、アクションを自己文書化するための既定としてこれを使います。

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

          `ENTRYPOINT` 内の Docker の `Dockerfile` をオーバーライドするか、まだ指定されていない場合は設定します。 shell や exec 形式を持つ Docker の `ENTRYPOINT` 命令とは異なり、`entrypoint` キーワードでは、実行する実行可能ファイルを定義する単一の文字列だけを受け付けます。

          `jobs.<job_id>.steps[*].with.entrypoint` の例

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

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

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

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

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

パブリックなアクションを実行すると、README ファイル内で想定されている変数が指定されることがあります。 シークレットまたは機密性の高い値 (パスワードやトークンなど) を設定している場合は、secrets コンテキストを使ってシークレットを設定する必要があります。 詳しくは、「コンテキスト リファレンス」をご覧ください。

          `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

ステップが失敗してもジョブが失敗にならないようにします。 true に設定すれば、このステップが失敗した場合にジョブを成功させることができます。

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

プロセスがkillされるまでにステップが実行できる最大の分数。 最大: GitHub ホステッド ランナーとセルフホステッド ランナーのどちらについても 360。

小数値はサポートされていません。 timeout-minutes は、正の整数にする必要があります。

jobs.<job_id>.timeout-minutes

GitHubで自動的にキャンセルされるまでジョブを実行する最長時間 (分)。 デフォルト: 360

タイムアウトがランナーのジョブ実行の制限時間を超えた場合、代わりに、実行の制限時間に達したときにジョブが取り消されます。 ジョブの実行時間制限について詳しくは、GitHub ホスト ランナーに関する「課金と使用」と、自己ホスト ランナーの使用制限に関する「アクションの制限」をご覧ください。

jobs.<job_id>.strategy

ジョブにマトリックス戦略を使うには、jobs.<job_id>.strategy を使用します。 マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。 たとえば、マトリックス戦略を使用して、複数バージョンの言語または複数のオペレーティング システムでコードをテストできます。詳しくは、「ワークフローでのジョブのバリエーションの実行」をご覧ください。

jobs.<job_id>.strategy.matrix

          `jobs.<job_id>.strategy.matrix` を使用して、さまざまなジョブの設定のマトリックスを定義します。 詳しくは、「[AUTOTITLE](/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow)」をご覧ください。

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

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

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

1 次元マトリックスの使用

次のワークフローでは、変数 version に値 [10, 12, 14] を定義しています。 このワークフローでは、変数の値ごとに 1 つずつ、3 つのジョブが実行されます。 各ジョブは、version コンテキストを通して matrix.version 値にアクセスし、node-version として actions/setup-node アクションにその値を渡します。

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

多次元マトリックスの使用

多次元マトリックスを作成するには、複数の変数を指定します。 ジョブは、変数の可能な組み合わせごとに実行されます。

たとえば、次のワークフローでは 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-24.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

マトリックス内の変数構成は、array の object として表現されることがあります。 たとえば、次のマトリックスでは、対応するコンテキストで 4 つのジョブが生成されます。

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

次に示すように、マトリックス内の各ジョブは、os と node の値の独自の組み合わせを持ちます。

- 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

jobs.<job_id>.strategy.matrix.include

          `include` リスト内の各オブジェクトに対して、キーと値のペアのいずれも元のマトリックス値を上書きしない場合、オブジェクト内のキーと値のペアが各マトリックスの組み合わせに追加されます。 オブジェクトをどのマトリックスの組み合わせにも追加できない場合は、代わりに新しいマトリックスの組み合わせが作成されます。 元のマトリックス値は上書きされませんが、追加されたマトリックス値は上書きできます。

例: 構成の展開

データ 可再利用actions.jobs.matrix-includeで展開 %}

例: 構成の追加

データ 再利用可能な.actions.jobs.マトリックス追加-含む %}

jobs.<job_id>.strategy.matrix.exclude

除外対象とするには、構成が部分一致していれば十分です。

          `include` のすべての組み合わせが、`exclude` の後で処理されます。 このため、`include` を使って以前に除外された組み合わせを追加し直すことができます。

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 の既定では、ランナーの可用性に応じて並列実行されるジョブの数が最大化されます。

jobs.<job_id>.continue-on-error

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

ジョブが失敗しても、ワークフローの実行が失敗とならないようにします。 true に設定すれば、このジョブが失敗したときにワークフローの実行を成功させることができます。

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

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

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

データの再利用可能.adocker-コンテナ-os-サポート %}

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

データの再利用可能.adocker-コンテナ-os-サポート %}

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

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

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

ネットワーク サービス コンテナー間の違いについて詳しくは、「Docker サービス コンテナーとの通信」をご覧ください。

例: localhost の使用

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

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

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

          `jobs.<job_id>.services.<service_id>.image` に空の文字列が割り当てられている場合、サービスが開始されません。 これを使用して次の例と同様な条件付きサービスを設定できます。

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

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

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

          `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

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

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

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

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

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

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

          `<source>:<destinationPath>`。

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

          `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

追加のDockerコンテナリソースのオプション。 オプションの一覧については、docker create のオプションに関するページを参照してください。

          `--network` オプションはサポートされていません。

jobs.<job_id>.uses

ジョブとして実行する再利用可能なワークフロー ファイルの場所とバージョン。 次のいずれかの構文を使用します。

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

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

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

          `jobs.<job_id>.uses` の例

データ 再利用可能.actions.uses-キーワード-例 %}

詳しくは、「ワークフローを再利用する」をご覧ください。

jobs.<job_id>.with

ジョブを使って再利用可能なワークフローを呼び出す場合は、with を使って、呼び出し対象のワークフローに渡される入力のマップを指定することができます。

渡す入力は、呼び出し対象のワークフローで定義されている入力仕様と一致する必要があります。

          [
          `jobs.<job_id>.steps[*].with`
          ](#jobsjob_idstepswith)とは異なり、`jobs.<job_id>.with`で渡した入力は、呼び出されたワークフローでは環境変数として利用できません。 代わりに、`inputs` コンテキストを使って入力を参照できます。

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

入力の文字列識別子と入力の値で構成されるペア。 識別子は、呼び出し対象のワークフローで on.workflow_call.inputs.<inputs_id> によって定義された入力の名前と一致する必要があります。 値のデータ型は、呼び出し対象のワークフローで on.workflow_call.inputs.<input_id>.type によって定義された型と一致する必要があります。

使用できる式コンテキスト: github と needs。

jobs.<job_id>.secrets

ジョブを使って再利用可能なワークフローを呼び出す場合は、secrets を使用して、呼び出し対象のワークフローに渡されるシークレットのマップを指定することができます。

渡すシークレットは、呼び出し対象のワークフローで定義されている名前と一致する必要があります。

          `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

          `inherit` キーワードは、呼び出し元ワークフローのすべてのシークレットを呼び出し対象のワークフローに渡すために使います。 これには、呼び出し元ワークフローからアクセスできるすべてのシークレット (つまりOrganization、リポジトリ、環境のシークレット) が含まれます。 
          `inherit` キーワードを使って、同じ Organization 内のリポジトリ間、または同じ Enterprise 内の Organization 間でシークレットを渡すことができます。

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

シークレットの文字列識別子とシークレットの値で構成されるペア。 識別子は、呼び出し対象のワークフローで on.workflow_call.secrets.<secret_id> によって定義されたシークレットの名前と一致する必要があります。

使用できる式コンテキスト: github、needs、secrets。

フィルター パターンの早見表

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

•         `*`: 0 個以上の文字と一致しますが、`/` 文字とは一致しません。 たとえば、`Octo*` は `Octocat` と一致します。
  

•         `**`: 0 個以上の任意の文字と一致します。
  

•         `?`: 直前の文字と0個または1個一致します。
  

•         `+`: 1 個以上の直前の文字と一致します。
  

•         `[]` 括弧内に一覧表示されているか、範囲に含まれている 1 つの英数字と一致します。 範囲には、`a-z`、`A-Z`、`0-9` のみを含めることができます。 たとえば、範囲 `[0-9a-z]` は任意の数字または小文字と一致します。 たとえば、`[CB]at` は `Cat` または`Bat` と、`[1-2]00` は `100` および `200` と一致します。
  

•         `!`: パターンの先頭に置くと、前の肯定のパターンを否定にします。 先頭のキャラクタではない場合は、特別な意味を持ちません。
  

文字 *、[、! は YAML の特殊文字です。 パターンを *、[、! で開始する場合は、パターンを引用符で囲む必要があります。 また、使用するフロー シーケンスに [ と ] の一方または両方を含むパターンがある場合は、パターンを引用符で囲む必要があります。

# 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] ]

ブランチ、タグ、パスのフィルター構文について詳しくは、「on.<push>.<branches|tags>」、「on.<pull_request>.<branches|tags>」、「on.<push|pull_request>.paths」をご覧ください。

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

          `*` 文字は YAML の特殊文字です。 パターンを `*` で開始する場合は、引用符を使う必要があります。 | `main`<br/><br/>`releases`                                                                    |

| '**' | すべてのブランチ及びタグ名にマッチします。 これは、branches または tags フィルターを使わない場合の既定の動作です。 | all/the/branches

every/tag | | '*feature' | * 文字は YAML の特殊文字です。 パターンを * で開始する場合は、引用符を使う必要があります。 | mona-feature

feature

ver-10-feature | | v2* | v2 で始まるブランチおよびタグ名と一致します。 | v2

v2.0

v2.9 | | v[12].[0-9]+.[0-9]+ | メジャー バージョンが 1 または 2 のすべてのセマンティック バージョニング ブランチおよびタグと一致します。 | v1.10.1

v2.0.0 |

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

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

          `*` 文字は YAML の特殊文字です。 パターンを `*` で開始する場合は、引用符を使う必要があります。             | `README.md`<br/><br/>`server.rb`                                                        |

| '*.jsx?' | ? 文字は 0 個または 1 個の直前の文字と一致します。 | page.js

page.jsx | | '**' | ワイルドカード ** は、スラッシュ (/) を含む任意の文字と一致します。 これは、path フィルターを使わない場合の既定の動作です。 | all/the/files.md | | '*.js' | ワイルドカード * は任意の文字と一致しますが、スラッシュ (/) とは一致しません。 リポジトリのルートにあるすべての .js ファイルと一致します。 | app.js

index.js | | '**.js' | リポジトリにあるすべての .js ファイルと一致します。 | index.js

js/index.js

src/js/app.js | | docs/* | リポジトリのルートにある docs ディレクトリのルート内のすべてのファイルのみ。 | docs/README.md

docs/file.txt | | docs/** | リポジトリのルートにある docs ディレクトリとそのサブディレクトリ内の任意のファイル。 | docs/README.md

docs/mona/octocat.txt | | docs/**/*.md | .md ディレクトリ内の任意の場所にある docs サフィックスが付いたファイル。 | docs/README.md

docs/mona/hello-world.md

docs/a/markdown/file.md | | '**/docs/**' | リポジトリの任意の場所にある docs ディレクトリ内の任意のファイル。 | docs/hello.md

dir/docs/my-file.txt

space/docs/plan/space.doc | | '**/README.md' | リポジトリ内のどこにでもあるREADME.mdファイル。 | README.md

js/README.md | | '**/*src/**' | リポジトリの任意の場所にある src サフィックスが付いたフォルダ内の任意のファイル。 | a/src/app.js

my-src/code/js/app.js | | '**/*-post.md' | リポジトリの任意の場所にあるサフィックス -post.md が付いたファイル。 | my-post.md

path/their-post.md | | '**/migrate-*.sql' | リポジトリの任意の場所にあるプレフィックス migrate- とサフィックス .sql が付いたファイル。 | migrate-10909.sql

db/migrate-v1.0.sql

db/sept/migrate-v1.sql | | '*.md'

'!README.md' | 感嘆符 (!) をパターンの前で使うと否定になります。 あるファイルがあるパターンにマッチし、ファイル中でその後に定義されている否定パターンにマッチした場合、そのファイルは含まれません。 | hello.md

一致しない

README.md

docs/hello.md | | '*.md'

'!README.md'

README* | パターンは順番にチェックされます。 先行するパターンを否定するパターンで、ファイルパスが再度含まれるようになります。 | hello.md

README.md

README.doc |