docs/preview-environment-plan.md

Preview Environment Plan

Preview Environment Plan

Goal

Provide pragmatic per-PR previews with dependency-aware deploys:

  • portal always previewed
  • core-api and learning-api previewed only when needed
  • fall back to UAT resources when previews are unnecessary

Keep

  • Keep Supabase GitHub integration as the source of truth for preview branch lifecycle.
  • Keep Supabase integration responsible for preview branch migrations and baseline seeding.
  • Keep .github/workflows/deploy_preview_env.yaml as the app preview orchestrator.
  • Keep preview app deploys stateless and environment-driven.

Clean Up

  • Remove implicit fallback from preview deploys to staging Supabase credentials.
  • Standardize Supabase preview secret names in GitHub workflows:
    • SUPABASE_CLI_ACCESS_TOKEN
    • UAT_SUPABASE_PROJECT_ID
  • Keep apps/supabase/scripts/deploy-preview.sh and apps/supabase/scripts/postdeploy-preview.sh as no-ops for now, but treat them as legacy paths and avoid building new behavior there.

Seeding Policy

  • Seed only the Supabase preview branch, never app previews directly.
  • Keep baseline preview seed data in Supabase-managed seed flow (seed.sql / integration flow).
  • Do not run destructive custom seed scripts on every push (synchronize).
  • If custom seeding is needed later, run it only on branch creation events (opened / reopened) and make it idempotent.

Rollout Plan

  1. Detect changed scopes in deploy_preview_env:
    • apps/core-api/**
    • apps/learning-api/**
    • apps/supabase/migrations/** or apps/supabase/schemas/**
  2. Compute deploy chain:
    • deploy_learning_preview = learning_changed OR supabase_changed
    • deploy_core_preview = core_changed OR deploy_learning_preview
  3. Always deploy portal preview.
  4. Deploy learning-api preview only when deploy_learning_preview=true.
  5. Deploy core-api preview only when deploy_core_preview=true.
  6. Reuse UAT URLs when preview deploy is skipped.
  7. Use Supabase preview branch only when learning/supabase-dependent preview chain is active.
  8. Export Infisical secrets from staging for both services:
    • /learning-api/ uses staging.
    • /backend/ uses staging.
  9. Force internal learning-api service wiring in preview runtime:
    • API_URL=http://api:8000
    • REDIS_URL=redis://redis:6379/0
    • CELERY_BROKER_URL=redis://redis:6379/0
    • CELERY_RESULT_BACKEND=redis://redis:6379/0

Out of Scope (Current Pass)

  • Marketing/email preview fixes.
  • Dependency/version mismatch cleanup.
  • Custom GitHub Action seeding pipeline.