Environment Promotion

Code promotion follows a linear path: local development, CI validation, production deploy. There is currently no staging environment -- that is planned for Month 2 when traffic justifies the additional infrastructure cost.

Current Promotion Path

Local development
  |
  | git push (PR branch)
  v
CI -- quality + docs jobs (PR checks)
  |
  | merge to main
  v
CI -- quality + migrate-prod + build-push + deploy-prod
  |
  v
Production (trovella.ai)

Local Development

Developers run against local Docker services (Postgres 18, Redis 8, Typesense 27.1) started via pnpm docker:up. The local environment uses:

• DATABASE_URL pointing to localhost:5433 (Docker Postgres)
• REDIS_URL pointing to localhost:6379 (Docker Redis)
• TYPESENSE_URL pointing to http://localhost:8108 (Docker Typesense)
• Inngest dev server on localhost:8288

Before pushing, developers run pnpm ci:check (or the full pnpm ci:full which includes the build) to catch issues that CI would catch.

PR Validation

When a PR is opened against main, two CI jobs run in parallel:

• quality -- lint, typecheck, test, build against ephemeral service containers
• docs -- Vale prose lint, broken link check, freshness check

The PR cannot be merged until quality passes. The docs job is informational.

Production Deploy

Merging to main triggers the full pipeline described in Deploy Pipeline. There is no approval gate between CI passing and production deploy -- the quality gates are the approval.

Pre-Deploy Checklist

Before merging a PR that deploys to production, verify:

1. CI is green on the PR branch
2. pnpm ci:full passes locally (catches build-time issues that ci:check misses)
3. New environment variables are set up in all locations:
   • apps/web/.env.example
   • Terraform (infra/environments/prod/main.tf)
   • infra/sync-secrets-vm.sh and scripts/sync-secrets.sh
   • CI env block in .github/workflows/ci.yml
   • GCP Secret Manager (with actual value)
   • If NEXT_PUBLIC_*: build args in apps/web/Dockerfile and the build-push job
4. Database migrations reviewed (see Data & Storage -- Migrations)
5. Architecture review completed for structural changes (new packages, new services, new auth flows)

GCP Project Structure

Trovella uses three GCP projects:

Project	Purpose	Status
trovella-prod	Production VM, Cloud SQL, monitoring, secrets	Active
trovella-staging	Staging environment (mirror of prod)	Deferred to Month 2
trovella-shared	Artifact Registry, Workload Identity Federation	Active

The trovella-shared project holds resources used by both environments:

• Artifact Registry -- Docker images at us-central1-docker.pkg.dev/trovella-shared/trovella/web
• Workload Identity Federation -- GitHub Actions authenticates here, then accesses prod/staging resources via cross-project IAM

Future: Staging Environment

The staging environment is planned for approximately Month 2, when user traffic justifies the cost of a second VM and Cloud SQL instance. The design:

• Separate VM in trovella-staging project
• Separate Cloud SQL instance with its own database
• Same Docker image -- staging deploys the same image that will later go to prod
• Promotion model: merge to main deploys to staging; manual approval (or timed gate) promotes to production
• Branch strategy: unchanged -- main remains the single integration branch

Until staging is added, production is the only deployed environment. The CI quality gates and the rollback procedures documented in Rollback Procedures are the safety net.