ワークフローとジョブの並行処理を制御する

さまざまなシナリオでのコンカレンシーの使用

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

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

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

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

複数の pending ジョブまたはワークフロー実行が同じコンカレンシーグループ内で待機できるようにするには、オプションの queue プロパティを使用します。 queue プロパティは、次の値を受け入れます。

single (既定値): 最大 1 つのジョブまたはワークフロー実行をコンカレンシーグループに含めることができます。新しいジョブまたはワークフローの実行がキューに登録されると、同じグループ内の既存の pending ジョブまたはワークフローの実行が取り消され、置き換えられます。
max: コンカレンシーグループには、最大 100 個のジョブまたはワークフロー実行を pending できます。キューがいっぱいになると、追加のジョブまたはワークフローの実行が取り消されます。

queue: maxとcancel-in-progress: trueの組み合わせは許可されず、ワークフロー検証エラーが発生します。

メモ

コンカレンシーグループ名では大文字と小文字が区別されません。たとえば、prod と Prod は同じコンカレンシーグループとして扱われます。
同じコンカレンシーグループ内のジョブまたはワークフローの実行は、各ワークフローがディスパッチされた時間ではなく、同時実行グループの待機を開始した時刻に従って先入れ先出し (FIFO) 順に処理されます。ジョブまたは実行の実際の開始時刻は異なる場合があるため、順序付けは保証されません。

例：コンカレンシーとデフォルト動作の使用

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

例: 複数の保留中の実行をキューする

既定では、同時実行グループに一度に pending できるジョブまたはワークフローの実行は 1 つだけです。取り消されずに複数の実行をキューに入れるようにするには、 queue: max設定します。 queue: maxでは、最大 100 個のジョブまたはワークフロー実行がコンカレンシーグループで待機できます。キューがいっぱいになると、追加の実行はすべて取り消されます。

たとえば、次のワークフローは、 production 環境へのデプロイをキューに入れ、各実行がコンカレンシーグループの待機を開始したタイミングに基づいて順番に 1 つずつ処理します。

on:
  push:
    branches:
      - main

concurrency:
  group: production-deploy
  queue: max

queue: max cancel-in-progress: trueと組み合わせることはできません。2 つのオプションでは、進行中の実行を処理するための競合する動作が記述されているためです。

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

コンカレンシーを使用して進行中のジョブを取り消したり、 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 などの別のブランチにプッシュすると、進行中の実行が取り消されます。

組織や企業での現在のタスクの監視

コンカレンシーまたはキューに関する制約を特定するには、組織や企業で GitHub ホステッドランナーで現在処理されているジョブの数を確認できます。詳しくは、「現在の作業の表示」をご覧ください。

ワークフローとジョブの並行処理を制御する

この記事で