exit code 127の解説: CIでのコマンドが見つからない

exit code 127は、shellが「そのコマンドが見つからなかった」と言っているのだ - 実行ファイルがインストールされていない、PATHにない、あるいはスペルミス。

CIのstepが127で終わるとき、コマンドは実際には一度も動いていない。shellはそれを探し、見つけられず、プログラム自身のロジックが何も実行される前に諦めた。

127の意味

shellは、コマンド名を実行ファイルに解決できないとき127を返す。これは「コマンドが動いて失敗した」とは異なる - 何も動いていない。通常、それとともにcommand not foundメッセージが表示される。

CIでよくある原因

ローカルにはインストールされているが、runnerのイメージにないツール。
PATHにないディレクトリにインストールされたツール。
コマンド名のタイプミス、または誤ったバイナリ名。
前のセットアップstepが静かに失敗し、ツールが一度もインストールされなかった。

修正方法

ツールがjob内にインストールされていること(明示的なインストールstepを追加する)を確認し、PATHにあること(which <tool>またはcommand -v <tool>)を確認する。エフェメラルrunnerではjob間で何も永続しないため、stepが必要とするすべてのツールは、そのjob内でインストールするか、runnerイメージに焼き込む必要がある。

Guarded install

- run: command -v jq || sudo apt-get install -y jq
- run: jq --version

127 vs 126

混同しないこと: 127はコマンドが見つからなかったことを意味し、126は見つかったが実行不可(権限が誤っている、またはインタプリタ行が壊れている)を意味する。修正は異なる - 127はインストール/PATH、126はchmod/shebang。

重要なポイント

exit 127 = コマンドが見つからない; 実際には何も動いていない。
原因: ツールがインストールされていない、PATHにない、スペルミス。
エフェメラルrunnerでは、必要なツールをすべてjob内でインストールするか、イメージに焼き込む。
127(見つからない)は126(見つかるが実行不可)とは異なる。