CIが緑でも、ランナーごとに実行環境が違うことがある
今回やったこと
セルフホスト型のCIランナーは、同じワークフローを実行していても、どのマシンに割り当てられたかで異なるコマンドやロケールを使うことがある。ジョブが失敗するとは限らず、すべて成功しているのに、結果だけがランナーごとに変わるリスクがある。
この問題に対して、期待する環境をリポジトリ内の台帳に置き、実機の設定・起動状態・実際のコマンド解決先と突き合わせる監査を用意した。この記事では、差が生まれる仕組みと、設定ファイルを置くだけで終わらせない確認方法を整理する。
「成功しているのに違う」をどう見つけるか
macOS上の3台のself-hostedランナーを調べた際、環境ファイル .env の内容が揃っていなかった。1台には PATH が書かれていたが、残り2台には無かった。ランナーは起動時に .env を読み、PATH が無い場合は登録時に記録された .path を使う。この .path では /usr/bin が Homebrew のコマンド置き場より先に並んでいた。
その結果、同じ git 呼び出しが、1台ではHomebrew版の2.54.0、残る2台ではApple同梱版の2.39.2へ解決されていた。言語設定 LANG も ja_JP.UTF-8 と C.UTF-8 に分かれていた。これらはCIを必ず失敗させる差ではない。たとえばロケールは、シェルの sort の並びや日付整形に影響する可能性がある。ジョブが緑でも、実行条件は均一とは限らない。
| 点検対象 | 見落としやすい状態 | 確認すること |
|---|---|---|
.env | 期待するキーが無い、余分なキーがある | 台帳の値と完全に照合する |
| 常駐状態 | ランナーが停止し、残りにジョブが寄る | 登録だけでなくプロセスが起動中かを見る |
| 設定反映 | .env を直したがプロセスは古いまま | ファイル更新時刻とプロセス起動時刻を比べる |
| コマンド解決 | PATHの順序で別の実体を使う | 期待PATHから実際の解決先を調べる |
台帳と実機を同じ監査で照合する
.env は各ランナーのホームディレクトリにあり、通常はリポジトリで管理されない。そのため、実機だけを直しても「本来どうあるべきか」が残らず、後から設定が戻るおそれがある。リポジトリ内の設定ファイルに期待値を置き、監査スクリプトが台帳と実機を照合する構成にした。
監査は、.env の値、常駐プロセスの有無、設定更新後の再起動、台帳と実機のランナー構成、PATH上でのコマンド解決先を確認する。設定ファイルが正しくても、実行中プロセスが古い環境を保持していれば問題は残るため、更新時刻と起動時刻も比べる。環境ファイルを直しただけでは、既に起動しているランナーへ変更は反映されない。
この点検には二つの層がある。実機監査は実際の環境を調べる。回帰テストで台帳やゲートの振る舞いを検証し、壊れた設定を与えたときに検出できるかを確認する。さらに、self-hostedのワークフローが直接呼ぶコマンドも台帳と照合する。こうして「監査スクリプトがある」だけでなく、必要な確認が実際に検査経路へ入っていることを確かめる。
台帳は機体ごとの違いも表現する
複数のOSを使う場合、すべてのホストで同じ PATH を要求するのは適切ではない。macOSとLinuxではツールの配置が異なるため、PATHはホストごとに定義する。一方、同じホスト上のランナー同士は、意図した環境へ揃える。共通に揃える項目と、ホスト固有の項目を台帳で区別しておくことが重要になる。
また、台帳にホストを追加するだけでは点検は完了しない。そのホスト上で監査を走らせるCIジョブも必要だ。テストでは台帳内の全ホストを走査し、設定だけ増えて実行側の配線を忘れた状態も検出する。期待値を記録したことと、その値を実際に検査したことは別の完了条件である。
運用に入れるときの要点
セルフホストランナーの環境差は、失敗ログが出ないまま再現性を損なう。確認の軸は、設定値、起動状態、設定変更の反映、コマンドの解決先の四つに分けると整理しやすい。どれか一つだけを見ても、「ファイルには正しい値があるがプロセスは古い」といった状態を取りこぼす。
監査結果を通知するだけでなく、期待値の正本を一か所に置き、実機の差を継続的に照合する。環境を変更したときは、台帳・実機・CIの監査経路を一組として更新する。この運用なら、CIの緑色だけでは分からないランナー間のずれを、原因調査が必要になる前に見つけやすくなる。
更新履歴
- 2026-10-06: 初稿作成。