YAMLのヒアドキュメントとは？解説

YAMLのヒアドキュメントとは、YAMLの複数行ブロック内に書かれたシェルのヒアドキュメントであり、CIステップがテキストの塊をコマンドに渡すことを可能にします。

ヒアドキュメントは、テキストのブロックをコマンドに渡すためのシェルの機能であり、YAMLのrunステップ内で使いたい場面がよくあります - 設定ファイルを書き出したり、スクリプトをツールにパイプしたり、SQLブロックを渡したりするためです。シェルのヒアドキュメントとYAMLのブロックスカラーの組み合わせはうまく機能しますが、両方のレイヤーのインデントと変数展開のルールに引っかかることがあります。

ヒアドキュメントとYAMLブロック

ヒアドキュメントは、選んだマーカー語で終わる入力ブロックを開始します。YAMLのrunステップ内では、シェルが行をそのまま受け取れるように、リテラルブロックスカラーの中にヒアドキュメントを書きます。YAMLレイヤーは改行を保持し、シェルレイヤーはそれをヒアドキュメントの入力として消費します。

インデントの相互作用

ここでは2つのインデントシステムが重なります: YAMLはブロック全体をrunの下にインデントすることを要求し、一方でシェルのヒアドキュメントの終端マーカーは独自のルールに従う必要があります。ヒアドキュメント演算子のダッシュ形式を使うと、読みやすさのために本文をタブでインデントできますが、スペースは除去されません - これは"marker not found"エラーの頻繁な原因です。

マーカーのクォートが展開を制御する

ヒアドキュメント内のシェル変数が展開されるかどうかはマーカーによって決まります。クォートされていないマーカーは変数とコマンド置換を展開し、クォートされたマーカーはテキストをリテラルのまま通します。選択を誤ると、展開されないリテラルか、意図せず補間された値のどちらかになります。

CIにおけるヒアドキュメント

よくあるパターンは、ヒアドキュメントを使ってrunステップから設定ファイルを書き出すことです。多くの場合、GitHub Actionsの複数行出力や環境ファイルの構文と組み合わせられ、それ自体もヒアドキュメント形式の区切り文字を使ってステップ間で複数行の値を安全に渡します。

A heredoc in a run step

# Heredoc inside a YAML run block to write a file
steps:
  - run: |
      cat > config.yml <<'EOF'
      server: prod
      retries: 3
      EOF

Latchkeyに関する注記

ヒアドキュメントと複数行の環境ファイル構文は、Latchkeyのランナー上でも同一に動作するため、設定ファイルの書き出しや複数行のジョブ出力の受け渡しといったパターンは、何の変更もなく機能します。

重要なポイント

YAMLのヒアドキュメントとは、runステップ内のリテラルブロックスカラーの中に書かれたシェルのヒアドキュメントです。
YAMLのインデントとヒアドキュメントの終端マーカーのルールが重なるため、インデントのミスがよく起こります。
ヒアドキュメントのマーカーをクォートするかどうかが、その中のシェル変数を展開するかリテラルのまま残すかを決めます。