CircleCI の requires はデフォルトで上流ジョブの success のみを待ちます。そのため、上流が失敗またはキャンセルされると、後処理ジョブ（テスト用 DB の削除、一時リソースの解放、Slack 通知など）が動かないという問題が生じることがあります。
2026年2月のリリースで、requires に terminal と not_run の2つのステータス値が追加されました。本記事では、全ステータス値の意味と、後処理ジョブの条件別の書き方を解説します。
requires のステータス値一覧
requires で指定できるステータス値は6種類あります。
| ステータス値 | 意味 |
terminal に含まれるか |
|---|---|---|
success |
ジョブが成功した（デフォルト） | ✓ |
failed |
ジョブが失敗した（タイムアウト含む） | ✓ |
canceled |
ジョブがキャンセルされた | ✓ |
unauthorized |
restricted context の権限がなく実行できなかった | ✓ |
not_run |
ジョブの依存が永久に満たされなかった（2026/02 追加） | ✓ |
terminal |
上記5つすべての集約値（2026/02 追加） | — |
not_run は、上流ジョブが失敗したり unauthorized になったりして依存が永久に満たされなくなった場合に設定されるステータスです。terminal は success・failed・canceled・unauthorized・not_run の5つをまとめた集約値で、「上流がどんな終端状態になっても実行する」という意図を1語で表現できます。
ステータス値の指定方法
ステータス値は requires のジョブ名に対してマップ形式で指定します。1つのみ指定する場合と複数指定する場合で構文が異なります。
workflows:
example:
jobs:
- upstream-job
# 1つのみ指定
- single-condition:
requires:
- upstream-job: failed
# 複数指定（OR 条件）
- multi-condition:
requires:
- upstream-job:
- failed
- canceled
ユースケース別の設定例
後で行うジョブの条件によって、使うステータス値が変わります。ここからは5つのパターンについて紹介します。
パターン1：上流がどう終わっても後処理を動かす（クリーンアップ）
テスト用 DB の削除や一時クラウドリソースの解放など、上流の結果に関わらず必ず実行したい場合は terminal を使います。
通常の書き方では、対象となるステータスを全て列挙する必要がありました。
# 旧来の書き方（terminal 追加前）
- teardown-db:
requires:
- run-tests:
- success
- failed
- canceled
- unauthorized
- not_run
terminal を使うと1行で同じ意味を表現できます。
# terminal を使った書き方
- teardown-db:
requires:
- run-tests: terminal
terminal は success・failed・canceled・unauthorized・not_run の5つを1語で表現できるため、全ステータスを列挙するより意図が明確になります。
実際の挙動を上流ジョブの成否別に見てみましょう。上流の run-tests-fail が failed で終わった場合でも、teardown-db は requires: run-tests-fail: terminal の条件を満たすため実行されます。
上流が success の場合も同様に teardown-db が実行されます。terminal は success を含む5つの終端状態すべてをカバーするため、上流の結果に関わらず後処理が走ることを1つのステータス値で保証できます。
パターン2：失敗時だけ通知する
デプロイが失敗した場合のみ Slack に通知するといった条件には、failed を単独で指定します。
workflows:
deploy:
jobs:
- build
- deploy:
requires:
- build
- notify-failure:
requires:
- deploy: failed # deploy が失敗した場合のみ実行
deploy が成功した場合、notify-failure は requires の条件（deploy: failed）を満たせないため not_run となり実行されません。
deploy が failed の場合にのみ notify-failure が実行されます。ステータス集計にも Failed 1 / Success 2 と表示され、失敗ジョブ1件と通知を含む成功ジョブ2件が内訳から読み取れます。
パターン3：キャンセル時だけ通知する
長時間かかるデプロイジョブが手動キャンセルされた場合のみ通知するケースには、canceled を使います。
workflows:
deploy:
jobs:
- deploy
- notify-canceled:
requires:
- deploy: canceled # deploy がキャンセルされた場合のみ実行
パターン4：上流の失敗で実行されなかったジョブをフォローする
上流ジョブが失敗するなどして依存が満たされなかったジョブは、not_run ステータスになります。not_run を requires で指定すると、「上流の失敗によって実行されなかったジョブを後処理でフォローする」ユースケースを記述できます。
workflows:
deploy:
jobs:
- build
- deploy:
requires:
- build # build が failed → deploy は依存未充足で not_run になる
- fallback:
requires:
- deploy: not_run # deploy が not_run のとき実行
上の例では、build が失敗すると deploy は依存が満たせないため not_run になります。fallback は deploy: not_run を条件にしているため、このとき実行されます。
実際のワークフロー画面では、build が失敗、deploy が not_run（ダッシュアイコン）、fallback が成功となり、右上のステータス集計にも Not_run 1 が表示されます。
パターン2（deploy: failed）との使い分けは、どのジョブが実行されたかで判断します。
-
deploy: failed：deployが実行されて失敗した場合 -
deploy: not_run：deploy自体が実行されず、さらに上流のジョブの失敗が原因となった場合
チェーンのどこかで失敗が起きた結果、特定のジョブが実行されなかったことを検知したい場合に not_run が有用です。
パターン5：ブランチごとに後処理を切り替える
「main ブランチでは deploy を動かし、それ以外のブランチでは別の通知を流したい」といったブランチ依存の後処理には、後処理ジョブ自身に branch filter を付けるのが idiomatic です。
workflows:
deploy:
jobs:
- build
- deploy:
requires:
- build
filters:
branches:
only: main
- notify-non-main:
requires:
- build
filters:
branches:
ignore: main
main ブランチでは build → deploy が実行され、notify-non-main は filter で除外されます。
main 以外のブランチでは deploy が filter で除外され、notify-non-main が実行されます。
requires: ジョブ名: not_run を使って branch filter によるスキップを検知する書き方（下記）は期待通りには動きません。
- deploy:
filters:
branches:
only: main
- notify-skipped:
requires:
- deploy: not_run # ← 期待通り動かない
公式ドキュメントの Configuration reference: requires には次のように記載されています。
When jobs you list as dependencies don't execute (due to filters, for example), CircleCI ignores them as dependencies for other jobs. However, if all dependencies of a job are filtered, that job doesn't execute either.
branch filter で除外されたジョブは requires の依存解決上「無視される」ため、not_run としてはマッチしません。さらに依存先がすべて除外された場合、その下流ジョブ自体も実行されません。そのため、ブランチごとの後処理は上の例のように後処理ジョブ側に直接 filter を付けてください。
使い分けの基準
ユースケースに応じた選択の基準をまとめます。
| 目的 | 使うステータス値 |
|---|---|
| 上流がどう終わっても実行する（クリーンアップ等） | terminal |
| 失敗時のみ実行する（失敗通知等） | failed |
| キャンセル時のみ実行する | canceled |
| 上流の失敗で実行されなかったジョブをフォローする | not_run |
| 成功・失敗どちらでも実行する（スキップ時は除く） | [success, failed] |
| ブランチごとに後処理を切り替える | 後処理ジョブに filters.branches を付ける |
「何が起きても後処理を動かしたい」場合は terminal が最適です。特定の終端状態にのみ反応させたい場合は、対応するステータス値を個別に指定してください。
requires の複数ジョブ指定は AND 条件になります。次の例では、job-a が failed かつ job-b が failed の場合にのみ notify が実行されます。
- notify:
requires:
- job-a: failed
- job-b: failed
片方のジョブしか failed にならなかった場合、notify は依存条件を満たせず not_run になります。
上の例では and-job-a-fail が failed、and-job-b-success が success となっており、AND 条件（両方 failed）が満たされないため and-notify-both-failed は not_run になっています。
「どちらか一方が失敗したら通知する」OR 条件は、requires の構文だけでは表現できません。
まとめ
terminal と not_run の追加により、後処理ジョブの条件を config に直接記述できるようになりました。terminal はクリーンアップ・リソース解放のような「必ず実行したい」処理に、not_run は上流チェーンの失敗によって実行されなかったジョブを検知したい場合に使います。
参考リンク