Deploy

The Sprinter Platform deploys to Vercel via Git push. This runbook covers the full deployment lifecycle from pre-deploy validation to rollback.

Pre-deploy checklist

Every deployment must pass the release floor. Run these in order -- each step must succeed before proceeding:

pnpm lint        # ESLint + Prettier checks
pnpm typecheck   # TypeScript strict mode compilation
pnpm test        # Vitest unit + integration tests
pnpm build       # Next.js production build

For important releases, the release bar also requires:

• Smoke tests pass (pnpm e2e)
• Visual verification via Playwright MCP or qa-tester sub-agent
• Verified production telemetry on critical flows

Never force-push. Never skip the pre-deploy checklist.

Environment variables

Set these in Vercel > Project > Settings > Environment Variables. Scope to the appropriate environment (Production, Preview, Development).

Required

AI providers (at least one required)

Model ids must exist as enabled rows in the ai_models registry and match a configured provider. For example, if ANTHROPIC_API_KEY is not set, set AI_CHAT_MODEL and any per-call-site model env vars or tenant overrides to an enabled OpenAI, Google, xAI, or DeepSeek model that is actually configured; runtime AI calls intentionally fail instead of silently falling back across providers and mislabeling Langfuse/cost data.

Per-call-site model env vars are optional infrastructure-level defaults. Tenant admin overrides in Admin > Costs take precedence, then these env vars, then the registry-backed platform default. Current call-site env vars: AI_CAPTURE_MODEL, AI_AUTOMATION_PARSE_MODEL, AI_CHAT_TITLE_MODEL, AI_FILTER_EXTRACTION_MODEL, AI_TOOL_FILL_MODEL, AI_ENTITY_CREATE_MODEL, AI_VIEW_DATA_SOURCE_MODEL, AI_TASK_BREAKDOWN_MODEL, AI_SCHEMA_REPAIR_MODEL, AI_IMAGE_MODEL, and AI_EMBEDDING_MODEL.

Monitoring

LANGFUSE_HOST and legacy LANGFUSE_BASEURL are normalized to LANGFUSE_BASE_URL at server startup, but new deployments should set LANGFUSE_BASE_URL directly.

Background jobs

Optional

Deployment flow

Standard deployment (Vercel Git integration)

1. Push to main branch (or merge a PR)
2. Vercel detects the push and starts a build
3. pnpm build runs in CI (CI=true is set automatically)
4. Sentry source maps upload during build (when SENTRY_AUTH_TOKEN is set)
5. Vercel deploys the build to production
6. Verify the deployment at the production URL

Preview deployments

Every PR gets a preview deployment automatically. Preview deployments use the same environment variables scoped to the Preview environment. Use these to verify changes before merging to main.

Database migrations

Database migrations must be applied before deploying code that depends on new schema. The order matters:

1. Apply migrations to the remote Supabase project:

pnpm db:push

This pushes all pending migrations from supabase/migrations/ to the remote database.

2. Verify the migration applied correctly by checking the Supabase dashboard or running a test query.

3. Deploy the application code that uses the new schema.

4. Regenerate types if you haven't already:

pnpm db:types

This updates lib/supabase/database.types.ts to match the remote schema.

Migration safety

• Migrations must be additive (add columns, tables, indexes) whenever possible
• Destructive changes (drop column, rename table) require a two-phase deployment: first deploy code that handles both old and new schema, then apply the migration
• Always test migrations locally first with pnpm db:reset
• Include down migration comments in the SQL file for reversibility

Sentry source maps

Source maps upload automatically in Vercel builds because CI=true is set. The config at next.config.ts controls this:

sourcemaps: {
  disable: process.env.CI !== "true" && process.env.SENTRY_UPLOAD_MAPS !== "true",
  deleteSourcemapsAfterUpload: true,
}

After upload, source maps are deleted from the build output so they are not served publicly.

To upload source maps from a local build:

SENTRY_UPLOAD_MAPS=true pnpm build

Rollback procedures

Vercel instant rollback

Vercel keeps previous deployments available. To rollback:

1. Go to Vercel > Project > Deployments
2. Find the last known good deployment
3. Click the three-dot menu > Promote to Production

This is instant (no rebuild) and is the preferred rollback method.

Git revert

If the rollback needs to persist in source control:

git revert <bad-commit-hash>
git push origin main

Vercel will build and deploy the reverted code automatically.

Database rollback

If a migration needs to be reverted:

1. Write a reverse migration SQL file
2. Apply it via pnpm db:push
3. Regenerate types with pnpm db:types

There is no automated rollback for migrations. Always test migrations locally before pushing to production.

Post-deploy verification

After every production deployment:

1. Check the Vercel deployment logs for build errors
2. Open the production URL and verify the app loads
3. Check Sentry for new errors in the release
4. Verify Inngest functions are registered (Inngest dashboard > Functions tab)
5. For critical changes, run a quick smoke test on the affected pages

Deployment frequency

The platform supports continuous deployment. Merge to main when:

• All checklist items pass
• PR review is complete (if required)
• Database migrations are applied (if any)

There is no deployment freeze or maintenance window required for standard deployments.