Deploy

# 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:

```bash
pnpm lint        # ESLint + Prettier checks
pnpm typecheck   # App-code TypeScript strict mode compilation
pnpm typecheck:tests # Test/e2e 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

| Variable                               | Purpose                                                           |
| -------------------------------------- | ----------------------------------------------------------------- |
| `NEXT_PUBLIC_SUPABASE_URL`             | Supabase project URL                                              |
| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Supabase anon key (fallback: `NEXT_PUBLIC_SUPABASE_ANON_KEY`)     |
| `SUPABASE_SECRET_KEY`                  | Supabase service role key (fallback: `SUPABASE_SERVICE_ROLE_KEY`) |

### AI providers (at least one required)

| Variable                       | Provider                                     |
| ------------------------------ | -------------------------------------------- |
| `ANTHROPIC_API_KEY`            | Anthropic (Claude models)                    |
| `OPENAI_API_KEY`               | OpenAI (GPT, o-series, DALL-E, image models) |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Google (Gemini models)                       |
| `XAI_API_KEY`                  | xAI (Grok models)                            |
| `DEEPSEEK_API_KEY`             | DeepSeek models                              |

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

| Variable                 | Purpose                                                    |
| ------------------------ | ---------------------------------------------------------- |
| `NEXT_PUBLIC_SENTRY_DSN` | Sentry client-side DSN                                     |
| `SENTRY_DSN`             | Sentry server-side DSN                                     |
| `SENTRY_AUTH_TOKEN`      | Source map upload token                                    |
| `SENTRY_ORG`             | Sentry organization slug                                   |
| `SENTRY_PROJECT`         | Sentry project name                                        |
| `LANGFUSE_PUBLIC_KEY`    | Langfuse public key for AI trace export                    |
| `LANGFUSE_SECRET_KEY`    | Langfuse secret key for AI trace export                    |
| `LANGFUSE_BASE_URL`      | Langfuse host, for example `https://us.cloud.langfuse.com` |

`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

| Variable              | Purpose                                  |
| --------------------- | ---------------------------------------- |
| `INNGEST_EVENT_KEY`   | Inngest event key (production)           |
| `INNGEST_SIGNING_KEY` | Inngest webhook signing key (production) |

### Optional

| Variable                    | Purpose                                            |
| --------------------------- | -------------------------------------------------- |
| `EXA_API_KEY`               | Exa API for web search tool                        |
| `CREDENTIAL_ENCRYPTION_KEY` | AES key for agent connection credential encryption |

## 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:

```bash
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:

```bash
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:

```typescript
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:

```bash
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:

```bash
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.