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

公開ツールYAML 検証・整形

目次
  1. CIデプロイが失敗する理由: なぜ起きるのか
  2. 確認方法: どの行が間違っているかを見つける
  3. よくつまずくポイント
  4. まとめ
  5. よくある質問

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のエラー行番号を確認

よくつまずくポイント

状況原因
エディタでは揃って見えるのにエラーが出るタブとスペースが混ざっているため、画面では同じに見えてもパーサーは別のインデントとして処理します
他の文書からコピーしたYAMLの断片を貼り付けたらエラーになったコピー元のインデントのスペース数が現在のファイルと異なり、前後の行と階層がずれます
リスト(-で始まる項目)の1つだけエラーになる兄弟項目同士でインデントのスペース数が1つでも違うと、その項目だけ別の階層に分離されます
CIログにエラーの行番号が出ないログはパースに失敗した事実だけを伝えるもので、原因の行はファイルを直接検証しないと見つけられません

表にまとめた状況はすべて、「インデントのスペース数が階層を決める」という同じルールから生じています。ファイルを検証ツールに通せば、人が見落としやすいこの違いを行番号ですぐに確認できます。

まとめ

CI/CD設定ファイルはほとんどがYAMLで書かれており、YAMLは中括弧ではなくインデントのスペース数で階層を表します。同じ階層の項目はスペース数が正確に同じでなければならず、1つずれるだけでも別の階層として解釈されたり、パース自体が失敗したりします。

エディタの空白表示機能で目視したり、スペース数を直接数えたりする方法もありますが、ファイルが長くなるほど、検証ツールに通して行番号ですぐに確認するほうが速くて正確です。

YAML 検証・整形

無料・登録不要・ブラウザですぐにYAMLのエラー行番号を確認

よくある質問

CIログにエラーの行番号が出ないときは、どうやって探せばよいですか?

CIツール自体のログは、ほとんどが「パースに失敗した」という事実だけを知らせ、正確な行番号までは教えてくれないことが多いです。設定ファイルをそのまま別のYAML検証ツールに貼り付ければ、パーサーがどの行から階層の解釈がずれたのかを行番号で示してくれます。

インデントはスペース2つと4つのどちらが正しいですか?

YAMLの仕様自体は、スペースの数を強制していません。ただし、1つのファイルの中では同じ階層同士で必ず同じ数を使う必要があるため、プロジェクト全体で2つでも4つでも1つに統一して使うことが重要です。GitHub ActionsやGitLab CIのサンプルドキュメントでは、おおむね2つを使っています。

タブとスペースを混ぜて使ってもいいですか?

いいえ、できません。YAMLの仕様では、インデントにタブ文字を使えません。エディタによってタブが画面上で何個分のスペースに見えるかが異なるため、タブ1つがスペース何個分のインデントに当たるのかをパーサーが一貫して判断できないからです。

この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む

関連記事

  1. YouTube字幕をSRT・VTTで保存 — 自動生成と手動の違いYouTubeの自動生成字幕が人名や専門用語で誤る理由、手動字幕との違い、SRT・VTT・TXTの使い分けをまとめました。
  2. テキストの各行に行番号を付ける方法 5形式と桁揃え複数行のテキストやコードの先頭に、1. や [1]、01. など5つの形式で行番号を自動で付けられます。空行を除く方法と、桁数を揃える計算の仕組みも解説します。
  3. アナグラム判定の方法 4ステップで一致を確認2つの単語や文がアナグラムかどうかを、大文字小文字・空白・記号を除いて文字を並べ替え、4ステップで確かめる方法を解説します。文字の出現回数を数える高速な判定の仕組みと、身近な例もあわせて紹介します。
  4. NGワードの伏字変換 誤検出を防ぐ判定の仕組み部分一致と完全一致の違い、長い単語を優先するマッチング、スカンソープ問題の避け方まで、誤検出の少ない伏字処理の考え方を整理して解説します。
  5. Base32エンコードの仕組みとOTPシークレットキーのデコードRFC 4648準拠のBase32が5ビット単位で変換される仕組み、0・1・8・9を使わない理由、=パディングの計算方法、そしてGoogle OTPのシークレットキーをデコードする手順までを解説します。
  6. Base64 エンコード・デコードの仕組みと文字化け対策Base64が8ビットを6ビットに分ける仕組み、容量が33%増える理由、末尾の=パディングの規則、日本語が文字化けしないUTF-8変換、暗号化との違いをまとめて解説します。

関連ツール