Environments and deployment

QA Sync’s production runtime is a static single-page app on Vercel plus a production Supabase project. There’s no application server to deploy.

Environments

Environment	Frontend	Supabase
Local	npm run dev on port 3000	Local stack in Docker (supabase start)
Preview	Vercel preview deployments	As configured in the Vercel project
Production	Vercel production deployment	Production Supabase project

Browser environment variables

The frontend needs only two public, browser-safe values:

VITE_SUPABASE_URL="https://<project-ref>.supabase.co"
VITE_SUPABASE_ANON_KEY="<production anon key>"

Set them in the Vercel project settings (or in a local .env.production when validating a release build).

Danger

• Never put SUPABASE_SERVICE_ROLE_KEY in any Vite env file or in Vercel’s browser env. Every VITE_ variable is bundled into the browser.
• Never define VITE_DEV_LOGIN_SHORTCUTS in .env, .env.local, .env.production or the hosting provider.

Set up the production Supabase project

1. Create the Supabase project.

2. Link the repository to it:

   supabase link --project-ref <project-ref>

3. Apply migrations (this targets the linked production project; run it only when you intend to):

   supabase db push

4. Configure Auth:

   • Site URL and Redirect URLs: the production frontend origin.
   • Sign-up: disabled. QA Sync never offers public sign-up.
   • Email confirmation: choose the policy deliberately.

5. Verify the storage buckets created by migrations exist: feedback-attachments, task-request-attachments and qa-evidence.

First admin

Signing in never makes anyone an admin: an account gets a role only when an admin provisions it (or, later, from an accepted organisation invitation). Make the first QA Sync platform operator by hand in the Supabase SQL editor with insert into public.platform_admins (user_id) select id from auth.users where email = '<operator email>';, give the first organisation admin their role deliberately, confirm they can reach /app/admin, and provision everyone else from the admin workspace.

Deploy the frontend

1. Set the production env vars in Vercel.

2. Validate the env contract:

   npm run validate:prod-env

3. Build:

   npm run build

4. Deploy. One Vercel project serves everything from the repository root: vercel.json runs npm run build, which builds both apps and assembles dist/ with the landing page at /, these docs at /docs/ and the web app at /app/. Every /app/... path is rewritten to the app’s index.html so direct refreshes on /app/admin, /app/tester and the other workspace routes load the SPA. The old paths (/app/login, /app/admin, /app/tester, …) redirect to their /app/... equivalents.

The landing page and these docs are the apps/landing workspace (Astro Starlight). They ship in the same Vercel project as the app, and the request form reuses the app’s VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY, so no extra variables are needed. Set the production Supabase Site URL (Authentication → URL Configuration) to https://<your-domain>/app so auth emails link into the app. Run npm run preview to check the assembled site locally with the same redirects and rewrites.

Website forms and email

Get started (/get-started) and Book a demo (/book-demo) post to the public-forms Supabase Edge Function, which validates and rate-limits the request, stores it (access_requests or demo_requests) and emails the QA Sync team through Resend. Deploy it with supabase functions deploy public-forms and set its secrets with supabase secrets set RESEND_API_KEY=<key> NOTIFY_EMAIL=<address>. Locally, run supabase functions serve next to npm run dev; without a Resend key the forms still work and the email is logged. The full guide is docs/website-forms-and-email.md in the repository.

Release gates

Don’t publish if any of these are true:

• the production login shows dev-only login shortcuts;
• a direct route refresh returns a host 404;
• admin access depends on manual table patching after login;
• a task-request publish changes status without creating a real task outcome;
• critical flows only work against local Supabase.

Also confirm before release:

• npm run validate:prod-env passes and the production build succeeds;
• public sign-up is disabled;
• Supabase diagnostics don’t appear on the login page or non-admin screens;
• immutable audit logging is enabled for privileged access and workflow mutations;
• local demo accounts aren’t used for production access.

Smoke test after deploy

1. Open the production login page. Confirm no dev login shortcuts or Supabase diagnostics are shown.
2. Sign in as an admin and confirm you reach /app/admin.
3. Create or check one tester and one developer through Users, with explicit app access.
4. Confirm the tester and developer reach their own workspaces and see only their apps.
5. As admin, create or update a task with instructions and an expected result.
6. Move it to Staging; as the tester, record one passing and one failing QA run.
7. As the developer, triage an issue and send one suggestion for admin review.
8. As admin, review and publish the resulting task request.

Caution

Never point npm run validate:core at production. It signs in with seeded credentials and writes temporary records with a service-role key.