コンテンツにスキップ

0010. 環境分割 (Supabase dev / prod の 2 独立プロジェクト + CI デプロイ)

コンテキストと課題

本番と開発でデータ・認証・スキーマを確実に分離したい。当初は Supabase Branching (GitHub 連携で PR ごとに preview ブランチを自動作成・適用) を使っていたが、適用タイミングが不透明で、PR プレビューの 分離運用も過剰だった。マイグレーション適用を 明示的・予測可能 にし、dev でテストデータを自由に 扱える独立環境が欲しい。

決定

Supabase を本番 (prod) / 開発 (dev) の 2 つの完全独立プロジェクトに分け、適用は CI が明示実行する。 Supabase Branching は廃止した。

環境 git ブランチ Web (Cloudflare Pages) Supabase EAS
production main Production deployment 本番プロジェクト (独立) production
develop develop Preview (branch=develop) dev プロジェクト (独立) preview
PR プレビュー feature/* → develop branch Preview dev を共有参照 —
  • DB マイグレーション: .github/workflows/supabase-deploy.yml が supabase/migrations/** の push を契機に supabase db push --db-url "$DB_URL" を実行する。develop push → dev、main push → 本番。接続は env 別の Session pooler URI (SUPABASE_DEV_DB_URL / SUPABASE_PROD_DB_URL)。 db push は supabase_migrations.schema_migrations を見て 未適用分のみ 適用する。
    • 直接ホスト db.<ref>.supabase.co は IPv6 only で Actions から到達できないため pooler 必須。 ワークフローは URI 形式と直接ホストでないことをガードする。
  • API デプロイ: .github/workflows/deploy-api.yml が apps/api/** / packages/shared/** の push で wrangler deploy --env staging|production を実行 (develop → staging Worker、main → production Worker)。
  • Web デプロイ: Cloudflare Pages の Git Integration が直接実行 (GitHub Actions は使わない)。 ビルドは pnpm --filter @waste-link/web build、出力 apps/web/dist。env は Pages の Production / Preview で別管理 (Production=本番鍵 / Preview=dev 鍵)。
  • PR 時の検証: .github/workflows/supabase-migrations-check.yml がマイグレーションファイル検証
  • dev への dry-run を行う。ci.yml は lint/typecheck/test/build の品質ゲート (ADR 0015)。

影響 (Consequences)

良い点

  • 本番と dev が 完全独立。dev にテストデータを自由投入でき、本番を一切汚さない。
  • マイグレーション適用が CI の 明示ジョブ になり、いつ・どこへ適用されたかがログで追える。
  • Web (Pages Git Integration) / API (wrangler) / DB (db push) のデプロイ経路が分離し、変更点だけが 該当ワークフローで動く (path フィルタ)。

トレードオフ / 注意点

  • マイグレーションは forward only。ロールバックは手動で down マイグレーションを書く必要があり、 破壊的変更前は pg_dump バックアップが要る。
  • ドキュメントのドリフト: README.md (環境構成 / デプロイフロー節) と ci.yml のコメントは まだ旧 Supabase Branching を前提に書かれている。現行の正は docs/deployment.md と supabase-deploy.yml (「Branching を廃止し CI が db push」)。参照時は後者を優先すること。
  • Web デプロイは CI 外 (Pages Git Integration) のため、Web のデプロイ成否は CF ダッシュボードの Deployments で確認する。
  • Session pooler URI / service_role キーなど 接続秘密の管理 が GitHub Secrets / Cloudflare に 分散する。初期セットアップ手順は docs/deployment.md に集約している。

根拠 (典拠)

  • docs/deployment.md:1-31,34-61,65-83,137-177,181-205 — 2 独立プロジェクト方針、自動化/手動の切り分け、Pages は Git Integration、Secrets、Branching からのカットオーバー手順。
  • .github/workflows/supabase-deploy.yml:1-18,38-61 — 役割コメント (Branching 廃止・CI が db push)、トリガー (develop/main push + supabase/migrations/**)、supabase db push --db-url、pooler ガード。
  • .github/workflows/deploy-api.yml:1-29,62-82 — develop→staging / main→production の wrangler デプロイ。
  • .github/workflows/ci.yml:1-13 — lint/typecheck/test/build を main/develop の push と PR で実行。
  • README.md:112-153 / .github/workflows/ci.yml:3-7 — 旧 Supabase Branching を前提とした (現在は古い) 記述。
  • docs/superpowers/specs/2026-06-18-supabase-env-split-design.md — 環境分割の設計書。