YAMLのインデントエラーでCIデプロイが失敗する原因と直し方

GitHub ActionsやGitLab CIの設定ファイルを少し直してコミットしただけなのに、デプロイに失敗したというメッセージを受け取った経験があるでしょう。コードのdiffをいくら見てもコマンドは1文字も変わっていないのに、実際の原因は目に見えにくいスペース1つだった、ということはよくあります。YAMLは中括弧ではなくインデントのスペース数で階層を区別する文法なので、空白1つもそれ自体が文法の一部なのです。
要点 ① YAMLは中括弧やカンマではなく、改行とインデントのスペース数だけで階層を表す文法です ② 同じ階層に属する項目はインデントのスペース数が正確に同じでなければならず、1つでもずれると別の階層として解釈されたり、構造自体が壊れたりします ③ 画面には整って表示されても、実際のスペースの数やタブの混在は、パーサーに通してみないと正確にはわかりません
CIデプロイが失敗する理由: なぜ起きるのか
GitHub Actions、GitLab CI、Kubernetesマニフェスト、docker-composeなど、ほとんどのCI/CD設定ファイルはYAMLで書かれています。YAMLはJSONのように中括弧や角括弧で下位項目の始まりと終わりを示さず、行のインデントのスペース数だけで階層を表します。
同じスペース数を持つ行は同じ階層に属し、より深くインデントされた行は直前の行の下位項目になります。このルールによってスペースの数そのものが文法の一部となり、1つでも数が違えばまったく別の構造として解釈されます。
問題は、この違いが目に見えにくいことです。エディタの画面ではスペースが何個でも同じように整って見えますし、別の文書や他の人のコードからコピー&ペーストした行は、元のインデントのスペース数をそのまま引き継いで周囲の行とずれやすいものです。
たとえば、複数のステップで構成されるstepsリストのうち1つだけスペースが1つ足りないと、その項目が意図しない階層に移動したり、パーサーが構造自体を解釈できずにエラーを出したりします。CIログには短い失敗メッセージしか残らないことが多く、何行目が原因なのかはログだけではわかりにくいです。
確認方法: どの行が間違っているかを見つける
エディタの「空白表示(invisible characters)」機能をオンにすると、スペースとタブを異なる記号で表示してくれるため、画面だけでは区別できなかった文字を見分けられます。「インデントガイドライン」の表示も、同じ階層の行が縦線で揃っているかを一目で比較するのに役立ちます。
この方法でも見つからない場合は、ファイルを先頭の行から1行ずつ数えていく手があります。親の行を基準に、子の行が何個分インデントされているかを手で合わせていけば、ずれている箇所を見つけられますが、ファイルが長くなるほど時間がかかり、数えている途中で間違えやすくもなります。
無料ツール「YAML 検証・整形」で確認する。 YAMLをそのまま貼り付けるか、ファイルを読み込むと、独自のパーサーが構造を再解釈し、インデントがずれている行の番号をすぐに知らせてくれます。
無料・登録不要・ブラウザですぐにYAMLのエラー行番号を確認

よくつまずくポイント
| 状況 | 原因 |
|---|---|
| エディタでは揃って見えるのにエラーが出る | タブとスペースが混ざっているため、画面では同じに見えてもパーサーは別のインデントとして処理します |
| 他の文書からコピーしたYAMLの断片を貼り付けたらエラーになった | コピー元のインデントのスペース数が現在のファイルと異なり、前後の行と階層がずれます |
| リスト(-で始まる項目)の1つだけエラーになる | 兄弟項目同士でインデントのスペース数が1つでも違うと、その項目だけ別の階層に分離されます |
| CIログにエラーの行番号が出ない | ログはパースに失敗した事実だけを伝えるもので、原因の行はファイルを直接検証しないと見つけられません |
表にまとめた状況はすべて、「インデントのスペース数が階層を決める」という同じルールから生じています。ファイルを検証ツールに通せば、人が見落としやすいこの違いを行番号ですぐに確認できます。
まとめ
CI/CD設定ファイルはほとんどがYAMLで書かれており、YAMLは中括弧ではなくインデントのスペース数で階層を表します。同じ階層の項目はスペース数が正確に同じでなければならず、1つずれるだけでも別の階層として解釈されたり、パース自体が失敗したりします。
エディタの空白表示機能で目視したり、スペース数を直接数えたりする方法もありますが、ファイルが長くなるほど、検証ツールに通して行番号ですぐに確認するほうが速くて正確です。
無料・登録不要・ブラウザですぐにYAMLのエラー行番号を確認
よくある質問
CIログにエラーの行番号が出ないときは、どうやって探せばよいですか?
CIツール自体のログは、ほとんどが「パースに失敗した」という事実だけを知らせ、正確な行番号までは教えてくれないことが多いです。設定ファイルをそのまま別のYAML検証ツールに貼り付ければ、パーサーがどの行から階層の解釈がずれたのかを行番号で示してくれます。
インデントはスペース2つと4つのどちらが正しいですか?
YAMLの仕様自体は、スペースの数を強制していません。ただし、1つのファイルの中では同じ階層同士で必ず同じ数を使う必要があるため、プロジェクト全体で2つでも4つでも1つに統一して使うことが重要です。GitHub ActionsやGitLab CIのサンプルドキュメントでは、おおむね2つを使っています。
タブとスペースを混ぜて使ってもいいですか?
いいえ、できません。YAMLの仕様では、インデントにタブ文字を使えません。エディタによってタブが画面上で何個分のスペースに見えるかが異なるため、タブ1つがスペース何個分のインデントに当たるのかをパーサーが一貫して判断できないからです。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む