main ブランチのCIが通ったら本番へ——自動デプロイ「ゲート」の落とし穴と設計手順
akinori手動デプロイを卒業し、「main にマージ → CIグリーン → 本番へ自動反映」というCD（継続的デリバリー）を組む案件は多い。だが実際にやってみると、パイプラインそのものより 「どのマージを本番反映の対象とみなすか」を判定するゲート で足を取られる。今回はその設計で得た教訓を、再現可能な手順として一般化する。
何を作りたかったか
やりたいことは単純だ。
- ステージング（stg）で検証済みのコミットだけを本番へ流す
mainへの push で CI が通ったら、人手を介さず本番サーバーへ反映する- 反映は複数台のWebサーバーに対して ローリング（1〜2台ずつ）で行い、全滅を避ける
- いつでも安全に戻せる
この「単純なはず」の要件が、マージの形式差とSHAの扱いで一気に複雑になる。
落とし穴1：squashマージとマージコミットで「ゲート」が誤爆する
多くのチームは stg→main の昇格を Pull Request で行うが、その マージ方式が混在 する。squash マージなら親コミットは1つ、通常マージなら親が2つになる。
自動デプロイのトリガーを「特定パス配下の変更があったら」というパスフィルタで組むと、マージコミットではパス差分の見え方が変わり、意図せず発火したり、逆に発火しなかったりする。squash 昇格を許容する条件を明示しないと、「stg で検証したはずのコミットがゲートに弾かれて本番に出ない」という事故が起きる。
教訓は次の通り。
- トリガー条件は「パスの有無」だけに頼らず、マージ元・マージ先ブランチの組み合わせを明示的に判定する
- squash マージと通常マージの両方を受理する条件を書く（片方だけだと運用途中で必ず漏れる）
- マージコミット（親が複数）のケースを最初からテストケースに含める
落とし穴2：short SHA で checkout が失敗する
「stg で検証済みのコミットSHA」をパイプライン間で受け渡すと、渡す側が 短縮SHA（7〜8桁） を出力し、受け取る側が完全SHA前提で checkout して失敗する、という地味な事故が起きる。
対策はシンプルだが、最初から入れておく価値がある。
- 受け渡すSHAは完全SHAに正規化するか、受け取り側で短縮SHAも解決できるようにする
- checkout 前に「そのSHAが存在するか」を検証し、無ければ明示的に失敗させる（黙って別コミットを反映しない）
落とし穴3：デプロイの「成否」を人間が信じられない
自動化して一番怖いのは「グリーンなのに実際は反映されていない」状態だ。ビルド成果物にバージョンや説明メタデータのマーカーを埋め込み、デプロイ後に本番から取得して照合すれば、E2Eレベルで「たしかにこのコミットが載っている」と機械的に確認できる。
- ビルド時に一意なマーカー（バージョン文字列や説明メタ）を埋め込む
- デプロイ後、稼働中サーバーから同じマーカーを読み出して照合する
- 照合が一致したときだけ「成功」とみなす。ログイン疎通などユーザー観点のスモークテストも併せて自動化する
再現手順（要約）
- CI を先に整える：命名規則・設定の整合性チェック・Releaseビルド・テストを層に分け、
mainへの push で必ず走らせる。本番反映ワークフローの変更自体もCIでゲートする - 昇格判定を明示化：stg→main のマージを、squash / 通常マージの両方について受理する条件で書く。マージコミットをテストする
- SHA を正規化：検証済みSHAを完全SHAで受け渡し、checkout 前に存在確認する
- ローリングで反映：複数台へ一斉ではなく1〜2台ずつ反映し、各段でヘルスチェック
- マーカーで検証：成果物メタデータを本番から読み出して照合し、疎通確認まで自動化
- 戻し方を先に書く：手動ロールバック手順をドキュメント化してから自動化を有効にする
得られた学び
自動デプロイの本質はスクリプトではなく 「何を本番へ出してよいかの判定ロジック」 にある。そしてその判定は、マージ方式・SHAの表現・成果物の同一性という、普段は意識しない差異の上に立っている。
だからこそ、まず戻せるようにしてから前に進める、成功を人間の目視ではなく機械照合で担保する、この2点を最初に用意しておくと、自動化は「怖いもの」から「手放せるもの」に変わる。CDは速さのためだけでなく、再現性と説明可能性のために組むのだと考えると設計が素直になる。
＼ 最新情報をチェック ／
