Preview Environment Testing

What it is

Every PR can receive its own Vercel preview deployment, but previews do not receive isolated Neon branches. Preview branching was disabled to control Neon storage usage. All previews share the persistent demo database (ep-silent-recipe) and its Hope Foundation dataset.

That makes a preview useful for testing code and UI against realistic shared data, but it is not a database sandbox:

Rows created through one preview are visible through other previews, local sessions targeting demo, and demo.givelink.ai.
Destructive testing can damage the shared demo story.
A preview build never applies migrations or seeds.

Build lifecycle

Push to PR branch
    |
    v
Vercel starts a preview build
    |
    v
scripts/vercel-build.sh:
  1. Requires DATABASE_URL_UNPOOLED or DATABASE_URL
  2. Parses and logs the database host
  3. Aborts if the host is production (ep-restless-pond)
  4. Builds the widget loader
  5. Builds the Next.js application
    |
    v
Preview URL is live

The build script does not run drizzle-kit migrate, db:push, or seed.ts. A missing preview database URL or a production host fails the build before application compilation.

Closing or merging the PR removes only the Vercel preview deployment on Vercel's schedule. The shared demo database and any test rows written to it persist.

Environment comparison

	Production	Demo	Preview
URL	`givelink.ai` / `app.givelink.ai`	`demo.givelink.ai`	Vercel preview URL
Database	Neon production (`ep-restless-pond`)	Neon demo (`ep-silent-recipe`)	Same persistent demo database
Data	Real customer data	Shared Hope Foundation dataset	Shared Hope Foundation dataset
Schema changes	Approved production procedure	Reviewed migrations via the demo sync workflow or an explicitly verified manual application	Must already exist on demo before preview testing
Persistence	Permanent	Permanent	Database writes are permanent on demo

Schema-changing previews

Before opening or relying on a preview that needs a schema change:

Edit the Drizzle schema and run pnpm db:generate.
Review the numbered migration SQL in full.
Verify the exact Neon endpoint for the intended demo database. Never assume .env.local points to demo; vercel env pull can change it.
Apply the reviewed migration through the approved environment-specific procedure.
Run pnpm db:check-rls after application when tenant policies are involved.
Open the preview only after the demo schema is ready.

Never use pnpm db:push for GiveLink schema work. Preview builds will not repair a missing migration.

After a schema-changing merge reaches main, .github/workflows/sync-demo-schema.yml applies committed migrations to demo with pnpm db:migrate and runs pnpm db:check-rls.

Testing safely

Shared-data rules

Prefer existing Hope Foundation records when the scenario permits.
Give new test records unmistakable names that include the issue or PR number.
Do not truncate tables, reset the database, re-run pnpm db:seed, or delete shared canonical records.
Clean up only records you created and only when their ownership is unambiguous.
Use org_seed_sunrise only as the tenant-isolation tripwire; never add demo content there.

Authentication

Generic previews use the preview-scoped Clerk configuration. DEV_AUTH_BYPASS is reserved for the demo/showcase deployment, so do not expect a normal PR preview to bypass sign-in.

Money-path testing

Preview and demo use shared test-mode integrations. Keep payment tests in provider test mode, use documented test credentials, and verify that the organization under test is connected to the intended test account before creating a payment.

Troubleshooting

Preview build reports a missing database URL

scripts/vercel-build.sh requires DATABASE_URL_UNPOOLED or DATABASE_URL for previews. Restore the Preview-scoped demo connection in Vercel, redeploy, and confirm the logged host.

Preview build resolves to production

The build fails when the parsed host contains ep-restless-pond. Correct the Preview-scoped database variables to the persistent demo branch and redeploy. Do not bypass or weaken the guard.

Preview returns a missing-table or missing-column error

The reviewed migration has not reached the shared demo database. Verify the exact endpoint, apply the migration through the approved demo procedure, run the relevant checks, and redeploy. Pushing another commit does not apply migrations during the build.

Demo schema sync fails after merge

Inspect .github/workflows/sync-demo-schema.yml. It applies committed migrations with pnpm db:migrate and then runs pnpm db:check-rls. Fix the migration or endpoint configuration; never replace the workflow with db:push.

References

scripts/vercel-build.sh — preview host guard and application build
.github/workflows/sync-demo-schema.yml — post-merge demo migration workflow
scripts/check-rls-polqual.ts — live malformed-policy check
Demo Environment runbook — shared dataset operations
ADR-0045 — automatic demo schema sync
ADR-0047 — generate-and-review migration decision