目次
社内で動かしている自動化の「失敗したときの知らせ方」を棚卸ししたところ、ほぼすべてが、失敗しても誰にも知らせない作りになっていました。そこで失敗通知を共通化し、全ワークフローに付けました。
すると、付けたその日に1件の通知が届きました。誤報ではなく、以前から潜んでいた実バグです。原因は、GitHub Actionsの中で「コマンドがPATHにあるか」を判定してから動く処理が、npx vercelでは想定どおりに動いていなかったことでした。
この記事では、棚卸しの経緯ではなく、このバグそのものと、失敗通知を付けたことで初めて見えたことを扱います。
この記事の結論
- PATH判定はnpx経由で呼ぶコマンドには効かない
- 存在確認は実際に呼ぶ形のコマンドで行う
- 無言の自動化は、失敗が見えていないだけかもしれない
失敗通知を付けた初日に見つかったバグ
やったことはシンプルです。失敗時に通知を送る処理を、GitHub Actionsのcomposite action（複数のステップを1つの部品にまとめて使い回す仕組み）として1つ作り、全ワークフローの末尾に付けました。
通知が届いたのは、Vercel関連の処理を含むワークフローでした。中身を確認すると、ある処理が「コマンドがPATHにあるか」の判定を前提に組まれていて、npx vercelについてはその判定が想定どおりの結果になっていませんでした。
重要なのは、このバグが失敗通知を付けた日に生まれたわけではない点です。以前から同じ動きをしていたはずで、ただ誰にも見えていなかった。通知を付けたことで、初めて表に出てきたのです。
npx vercelの存在確認が効かない原因
原因は、判定している対象と、実際の呼び方のずれです。
シェルの command -v や which は、PATHに並んだディレクトリの中から、指定した名前の実行ファイルを探します。一方、npx vercel は「npxがvercelパッケージを呼び出して実行する」という形です。vercelという実行ファイルがPATH上に置かれていなくても、npxがあれば動くことがあります。
# PATH上に「vercel」という実行ファイルがあるかを見ている
command -v vercel
# 実際の処理はnpx経由で呼んでいる
npx vercel ...
つまり「PATHにvercelがあるか」を確かめても、「npx vercelが動くか」を確かめたことにはなりません。判定の結果をもとに処理を分岐させていると、実際には動かせる状態でも、意図とは違う分岐に進んでしまいます。
厄介なのは、この種のずれはエラーで止まるとは限らないことです。分岐の先が「何もしないで終了」に近い作りだと、ワークフロー全体は成功のように見えることもあります。失敗を拾う仕組みが無ければ、なおさら気づけません。
PATH判定の対策：実際に使うコマンドで確かめる
対策の考え方は「確かめる形と、使う形をそろえる」です。代表的な選択肢を整理します。
| 対策 | 考え方 | 向くケース |
|---|---|---|
| npx経由で動作確認する | 実際と同じ形で呼び、バージョン表示などが返るかを見る | npx経由の運用を続けたい |
| CLIを明示的にインストールする | 先にインストールしてから、PATH判定を使う | PATH上にあることを前提にしたい |
| 判定そのものをやめる | 必要なコマンドは必ずある前提で、無ければ失敗させる | 判定で分岐する必然性が薄い |
どれを選ぶにしても、ポイントは2つです。判定の対象を実際の呼び方に合わせること。そして、前提が崩れたときは黙って先に進むのではなく、はっきり失敗させることです。失敗させれば、次に説明する失敗通知が拾ってくれます。
なお、GitHub Actionsの実行環境やnpx・Vercel CLIの挙動は更新されることがあります。仕様は変わるため、最新は公式ドキュメントで確認してください。
GitHub Actionsの失敗通知の使い方：composite actionで共通化する
今回の発見のきっかけになった失敗通知の付け方も紹介します。考え方は「失敗したときだけ動く通知部品を1つ作り、全ワークフローから呼ぶ」です。
各ワークフローの側では、失敗時だけ動く条件を付けて、共通の部品を呼ぶだけにします（以下は書き方のイメージです）。
- name: 失敗を通知
if: failure()
uses: ./.github/actions/notify-failure
composite actionにまとめる利点は、通知の書き方が1か所にそろうことです。ワークフローごとに通知処理をコピーすると、書き方がばらつき、付け忘れも見落としやすくなります。部品が1つなら「全ワークフローがこれを呼んでいるか」を見るだけで、付け漏れを確認できます。
無言の自動化は正常とは限らない
今回いちばん持ち帰りたいのは、技術的な対策よりも判断軸のほうです。
自動化が何も言わずに動いているとき、私たちはつい「問題なく動いている」と受け取ります。しかし、失敗を知らせる仕組みが無い状態では、その静けさは何の証拠にもなりません。
| 状態 | 通知が来ないとき意味すること |
|---|---|
| 失敗通知なし | 正常か、失敗が見えていないだけか区別できない |
| 失敗通知あり | 少なくとも失敗としては検知されていない |
今回のバグも、通知が無い間はずっと「静かに動いている自動化」の1つでした。通知を付けた途端に姿を現したということは、裏を返せば、通知が無かった期間は見えていなかったということです。
自動化を増やすほど、1本ずつ目で確かめることはできなくなります。だからこそ、作るときに「失敗したら誰に、どう知らせるか」までをセットで用意することが、自動化を任せて手放すための前提になります。
まとめ
- 失敗通知を全ワークフローに付けた初日に、以前から潜んでいた実バグが見つかった
- 原因は、PATH判定の対象と実際の呼び方（npx vercel）のずれ
- 対策は、確かめる形と使う形をそろえ、前提が崩れたら黙らず失敗させること
- 失敗通知はcomposite actionで共通化すると、付け漏れを確認しやすい
- 無言で動いている自動化は、正常なのではなく失敗が見えていないだけかもしれない
よくある質問
Q. GitHub Actionsでnpx vercelがcommand -vで見つからないのはなぜ？ command -v はPATH上にある実行ファイル名を探す仕組みです。一方のnpx vercelは、npxがパッケージを呼び出して実行する形のため、vercelという名前がPATHに無くても動くことがあります。判定の対象と実際の呼び方がずれているのが原因です。
Q. GitHub Actionsでジョブが失敗したときに通知する方法は？ 失敗時だけ動く条件（if: failure()）を付けた通知ステップを用意します。複数のワークフローで使うなら、通知処理をcomposite actionにまとめて各ワークフローから呼ぶと、書き方がそろい、付け漏れも見つけやすくなります。
Q. エラー通知が来ない自動化は、正常に動いていると考えてよい？ そうとは限りません。失敗を知らせる仕組みが無ければ、止まっていても無言のままです。まず失敗したときに通知が届くことを確かめ、そのうえで初めて「通知が来ない＝正常」と判断できる、という順序で考えるのが安全です。
RENOYでは、業務自動化を作るだけでなく、失敗したときに気づける仕組みまで含めて設計しています。「いま動いている自動化が本当に動いているのか分からない」という段階のご相談も歓迎です。まずはお気軽に無料個別相談（オンライン・60分）をご利用ください。サービス内容をまとめた資料は資料請求からご覧いただけます。