Magentoデプロイ自動化 — GitHub Actions を見送り Mac→SSH 直結にした理由

Magento + Hyvä のデプロイを自動化する記録。GitHub Actions を真剣に検討した末に見送り、Mac から SSH 直結に落ち着いた。手動トリガー + メインリポジトリがない状況なら、この構成が合う。

TL;DR

[맥] Raycast 버튼 ──ssh -t (직결)──▶ [서버] deploy.sh → 각 모듈/테마 git pull → 빌드

# 맥: Raycast Script Command 한 줄 (사이트는 드롭다운)
ssh -t "$SSH_HOST" "cd '$REMOTE_PATH' && ./deploy.sh"

# 서버 deploy.sh — 핵심 2가지
# 1) trap으로 실패해도 점검모드 자동 해제
cleanup() {
  local code=$?
  if [ "$code" -ne 0 ]; then
    echo "✖ 실패(exit $code) — 유지보수 모드 해제"
    bin/magento maintenance:disable || true
  fi
}
trap cleanup EXIT
 
# 2) 모듈/테마는 배열 하나가 단일 레지스트리. 새 모듈은 여기 한 줄 추가
GIT_DIRS=(
  "app/code/Yohan/ModuleA"
  "app/code/Yohan/ModuleB"
  "app/design/frontend/Hyva/Hyva_K-SALE"
)
for d in "${GIT_DIRS[@]}"; do git -C "$d" pull --ff-only; done

デプロイのコマンドチェーンは composer update ではなく composer install（lock そのまま、再現可能）。GitHub Secrets・デプロイキー・ワークフロー YAML は一切ない。

なぜ GitHub Actions を見送ったか

1回のデプロイはこの長いチェーンだ: maintenance:enable → composer install → setup:upgrade → di:compile → tailwind build → static 整理 → static-content:deploy（ロケール9個）→ cache:flush → maintenance:disable。手で打つには長すぎるので自動化は必須。候補は GitHub Actions vs SSH スクリプト（Mac アプリは論外 — Raycast の alias が1秒で代替する）で、しばらく見栄えのいい Actions に傾いたが、見送った。

• メインリポジトリがない。 Magento ルートではなく、カスタムモジュールがそれぞれ別の git リポジトリだ。「どのリポジトリの push でトリガーするか」からして曖昧で、YAML を置く場所も定まらない。
• 承認ゲートも自動トリガーも要らない。 Actions が与える価値（push 自動トリガー、承認ゲート、中央ログ）のうち、このワークフローに必要なものがない。トリガーはどうせ意図的な手動だ。
• **そうなると GitHub は「SSH 一行を代わりに実行する中継所」**にすぎない。その中継のためにデプロイキーを発行し、Secrets を登録し、YAML の置き場所に悩むのは純粋なオーバーヘッド — 手動デプロイひとつに決裁システムを作るようなものだ。

落とし穴 2つ

• && チェーンはサイトを点検モードに閉じ込める。 症状: 中間ステップ（特にロケール9個の static deploy）がひとつ失敗 → チェーンがそこで止まり maintenance:disable が永遠に実行されない → サイトが点検画面に閉じ込められる。解決: スクリプトに trap cleanup EXIT（上の TL;DR）を仕込み、失敗しても終了時に点検を解除する。
• 本番で composer update は危険。 症状: update は composer.json の制約範囲内の依存をすべて最新に上げるので、コアやサードパーティが予告なく変わりうる。解決: 再現可能な composer install（lock 固定）。自分のモジュールだけ上げたいときはターゲットする: composer update yohan/* --with-dependencies。

ワークフローはモジュールごとに置くものではない

デプロイの「トリガー」はソースリポジトリに紐づいていない。すべてのモジュールを git pull する主体は サーバーの deploy.sh ひとつ であり、その中の GIT_DIRS 配列が「このサイトはこれらのモジュール + テーマで構成される」という単一のレジストリだ。モジュールが10個でもトリガーは1個、新しいモジュールは配列に一行追加するだけ。個々のモジュールリポジトリは単なるコード置き場で、CI もワークフローも要らない。

では GitHub Actions はいつ使うのか

次の2つの条件のどちらかが生じたら導入する: 複数人がデプロイに関わり「誰がいつデプロイしたか」の記録・承認が必要なとき、または push するとステージングに自動デプロイされるパイプラインが欲しいとき。 それまでは直結が正解だ。

学んだこと

• 流行りのツールが自分の状況の正解とは限らない。そのツールが解く問題（チーム協業・自動トリガー・追跡性）を自分が持っていなければ、純粋なコストだ。
• 「定石」に従う前に、その定石が解く問題が自分にあるかをまず問う。要らない問題にツールを持ち込むオーバーエンジニアリングが最大の敵だ。
• 手で打っていた && チェーンをスクリプト（trap）に移すだけで、点検モードのロックという事故をひとつ防げる。