CI/CD & Deployment

Status: Active Owner: @bilal @deen Last Updated: 2026-02-24 (unified infra→deploy pattern across all services)

Infrastructure and deployment planning. Detailed configs and scripts live in the repo.

Pipeline Overview

PR → Lint + Type-Check → Unit Tests → Build → Security Scan → AI Code Review
  → DB Migrations → Deploy to Cloudflare Workers → Smoke Tests → Live

Environment Strategy

Environment	Database	Hosting	Status
Local	Supabase local (Docker)	localhost:3000	Active
Production	Supabase Cloud	Cloudflare Workers	Active
Staging	Supabase Cloud (separate)	Cloudflare Workers	Future

Branch Strategy

main                → Production
├── staging         → Staging (future)
└── feature/*       → Development
    └── claude/*    → AI-generated branches

Local Development

Requires: Docker 24+, Node.js 20+, pnpm, Supabase CLI 1.150+.

supabase start            # Start local Supabase (first run downloads ~2GB)
pnpm install && pnpm dev  # Start Next.js

Local services: App (:3000), Supabase API (:54321), Studio (:54323), PostgreSQL (:54322), Inbucket (:54324).

Seed users: admin@test.local, landlord@test.local, staff@test.local (all password123).

Cloudflare Workers Preview

pnpm build:cf      # Build for Cloudflare Workers (via @opennextjs/cloudflare)
pnpm preview:cf    # Run locally on workerd runtime (wrangler dev)

Environment Variables

Required for Production

Category	Variables
Supabase	NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
Database	Via Hyperdrive binding (not a plain env var)
LLM	ANTHROPIC_API_KEY, OPENAI_API_KEY
Comms	TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_WHATSAPP_NUMBER, VOICE_WEBHOOK_SECRET
WhatsApp	META_WHATSAPP_PHONE_NUMBER_ID, META_WHATSAPP_ACCESS_TOKEN, META_WHATSAPP_VERIFY_TOKEN, META_WHATSAPP_APP_SECRET
Email	SENDGRID_API_KEY, SENDGRID_FROM_EMAIL
Optional	SENTRY_DSN, UPTIME_ROBOT_KEY, KIMI_API_KEY, GLM_API_KEY

Where secrets are stored

Type	Location
Non-secret vars	wrangler.jsonc [vars] section (committed)
Secrets	Cloudflare Worker secrets (via wrangler secret put)
Terraform vars	Terraform Cloud workspace variables
CI/CD secrets	GitHub Actions secrets

CI Pipeline (GitHub Actions)

Step	Tool	Runs On
Lint + type-check	ESLint, tsc	Every PR
Unit tests	Vitest (42 tests)	Every PR
Build	Next.js	Every PR
Secret scanning	Trufflehog	Every PR
SAST	Semgrep	Every PR
Dependency audit	pnpm audit	Every PR
AI code review	CodeRabbit	PRs only

CD Pipeline

Step	Tool
Build	pnpm build:cf (@opennextjs/cloudflare)
Deploy	wrangler deploy (via GitHub Actions on push to main)
DB migrations	Supabase CLI (supabase db push)
Smoke tests	curl health + message endpoints
Rollback	wrangler rollback

Deploy triggers

All three services follow the same infra → deploy dependency pattern:

1. deploy-*.yml — Two-job pipeline: infra (Terraform apply) → deploy (needs: [infra]). Terraform always runs before content is pushed. On subsequent runs where infra hasn’t changed, Terraform is a no-op (~10s).
2. terraform-*.yml — PR plan only + manual dispatch apply. No push-apply on main (that’s handled by the deploy workflow). This avoids race conditions where Terraform and deploy run in parallel.

Workflow	Trigger	Working Directory	Notes
deploy-marketing.yml	Push to main on envo-marketing/** or infra/marketing/**	Both	infra → deploy pipeline
terraform-marketing.yml	PR on infra/marketing/**, or manual dispatch	infra/marketing/	Plan on PR, apply on manual dispatch only
deploy-dashboard.yml	Push to main on envo-dashboard/** or infra/dashboard/**	Both	infra → deploy pipeline
terraform-dashboard.yml	PR on infra/dashboard/**, or manual dispatch	infra/dashboard/	Plan on PR, apply on manual dispatch only
deploy-brain.yml	Push to main on docs/** or infra/brain/**	Both	infra → deploy pipeline
terraform-brain.yml	PR on infra/brain/**, or manual dispatch	infra/brain/	Plan on PR, apply on manual dispatch only

Security Tooling

Tool	Purpose	Frequency
Trufflehog	Secret detection	Every PR
Semgrep	SAST / code analysis	Every PR
Trivy	Dependency scanning	Every PR
OWASP ZAP	DAST / web scanning	Weekly
pnpm audit	Dependency vulnerabilities	Every PR + Dependabot

Local Isolation Strategy

External services are stubbed for local development:

Component	Local	Production
PostgreSQL	Supabase local	Supabase Cloud (via Hyperdrive)
Auth	Supabase local (seeded users)	Supabase Auth
LLM	Stub provider (LLM_PROVIDER=stub)	Real API keys
Embeddings	Deterministic stub (content hashing)	OpenAI
Twilio	Test credentials (no send)	Real API
Email	Inbucket (port 54324)	SendGrid
Voice	Fixture payloads	VAPI/Retell

Implementation Phases

Phase 0: Local Isolation — DONE (partial)

• Supabase local stack
• Seed auth users
• .env.example with local defaults
• LLM stub provider
• Embedding stub
• Webhook test fixtures

Phase 1: Foundation — DONE

• Basic CI (lint + test on PR)
• Cloudflare Workers deployment
• Cloudflare Access (ZTNA)
• Hyperdrive connection pooling
• Type-check + build in CI
• Health check endpoint

Phase 2: Security — PLANNED

• Trufflehog
• Semgrep
• pnpm audit
• CodeRabbit AI review

Phase 3: Automation — PLANNED

• OWASP ZAP scheduled scans
• Slack notifications
• Rollback automation

Phase 4: Staging — FUTURE

• Staging Supabase project
• Staging environment config
• Data sync scripts

Related

• Infrastructure
• Dashboard Deployment Guide
• ADR-009 Application Framework Stack
• ADR-019 Authentication & Session Management
• ADR-020 Background Jobs & Scheduled Tasks
• ADR-021 Observability & Error Handling