docs/vercel-integration.mdx
The Vercel integration connects your Vercel project to your Trigger.dev project so that every Vercel deployment automatically triggers a Trigger.dev deployment. It also syncs environment variables from Vercel into Trigger.dev, and sets up version skew protection so your app and tasks stay in sync.
This eliminates the need to manually run the trigger.dev deploy command or maintain custom CI/CD workflows for Vercel-based projects.
You can connect Vercel from two entry points:
The integration syncs environment variables in both directions:
Vercel → Trigger.dev: Environment variables from your Vercel project are pulled into Trigger.dev. This happens during the initial setup and optionally before each build. Variables are synced per-environment (production, staging, preview).
Trigger.dev → Vercel: Trigger.dev syncs API keys (like TRIGGER_SECRET_KEY) to your Vercel project so your app can communicate with Trigger.dev.
The following variables are excluded from the Vercel → Trigger.dev sync:
TRIGGER_SECRET_KEY, TRIGGER_API_URL, TRIGGER_VERSION, TRIGGER_PREVIEW_BRANCH, TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION (managed by Trigger.dev)You can control sync behavior per-variable from your project's Vercel settings. Deselecting a variable prevents its value from being updated during future syncs.
<Note> Environment variables are pulled from Vercel before each build. To sync updated values into Trigger.dev, trigger a new Vercel deployment — either by pushing a commit to your connected branch or by redeploying from the Vercel dashboard. </Note> <Warning> If you are experiencing incorrectly populated environment variables, check that you are not using the `syncVercelEnvVars` build extension in your `trigger.config.ts`. This extension is deprecated and conflicts with the Vercel integration's built-in env var syncing. Remove it if present. </Warning>If you use Supabase Branching or Neon Database Branching for preview environments, disable syncing for database env vars on the Environment Variables page and use the syncSupabaseEnvVars or syncNeonEnvVars build extensions instead. These extensions automatically resolve the correct branch-specific credentials at build time.
Your Vercel app and your tasks are deployed separately, so there is always a window where a new app can trigger tasks built from older code. Version skew protection closes that window: each Trigger.dev deployment is tagged with your commit SHA, your app sends the same SHA when it triggers, and every run is pinned to the deployment built from the same commit. Runs triggered before the task build finishes wait for it rather than running on the previous version.
The integration sets this up for you:
TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1 on your Vercel project when you connect it, and re-asserts it on every build — so existing projects pick it up on their next deployment.VERCEL_GIT_COMMIT_SHA is available at runtime on Vercel, so the SDK finds the matching id with no work from you.There is nothing to enable, and it works in production, staging and preview alike. Nothing is gated: your Vercel deployment is never held back.
<Note> Version skew protection requires the `@trigger.dev/sdk` release that introduces external deployment ids. Check the [release notes](https://github.com/triggerdotdev/trigger.dev/releases) for the exact version, or just use the latest. On an older SDK no id is sent and your runs execute on the current version, with no warning. </Note>To opt out, set TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION to 0 on your Vercel project. The integration only writes the variable when it is absent, so a value you set is never overwritten.
Nothing is being switched off. The setting stays in your project's Vercel settings, keeps working, and remains the way to hold your Vercel deployment back until your tasks have built. New connections have it off by default. </Warning>
Atomic deployments ensure your Vercel app and Trigger.dev tasks are deployed in sync. When enabled, Trigger.dev gates your Vercel deployment until the task build completes, then triggers a Vercel redeployment with the correct TRIGGER_VERSION set. This guarantees your app always uses the matching version of your tasks.
sequenceDiagram
participant Dev as Developer
participant GH as GitHub
participant V as Vercel
participant TD as Trigger.dev
Dev->>GH: Push code
GH->>V: Webhook: new commit
V->>V: Start deployment
V->>TD: Deployment created
Dev->>GH: Create pull request
GH->>TD: Pull request created
TD->>TD: Start task build
V->>TD: Deployment check
TD-->>V: Check pending (gate deployment)
TD->>TD: Build completes
TD->>V: Set TRIGGER_VERSION env var
TD->>V: Trigger redeployment
V->>V: Redeploy with correct TRIGGER_VERSION
V->>TD: Deployment check (redeployment)
TD-->>V: Check passed
V->>V: Promote deployment
V->>TD: Deployment promoted
TD->>TD: Promote build
Atomic deployments are off by default for new connections. Projects that already had them enabled keep them enabled until you turn them off. Enabling them asks you to confirm first.
<Note> When atomic deployments are enabled, the integration automatically disables `Auto-assign Custom Production Domains` on your Vercel project. This is required so that Vercel doesn't promote a deployment before the Trigger.dev build is ready. If you turn atomic deployments off, re-enable that setting in Vercel or promote deployments yourself. </Note>Previously, setting up atomic deployments with Vercel required custom GitHub Actions workflows. The Vercel integration automates this entirely. For more details on how atomic deployments work, see Atomic deploys. For how to move off them, see replacing automatic atomic deployments.
The integration maps Vercel environments to Trigger.dev environments:
| Vercel environment | Trigger.dev environment |
|---|---|
| Production | Production |
| Custom environment | Staging (you choose which one) |
| Preview | Preview |
| Development | Development |
If your Vercel project has a custom environment, you can select which one maps to your Trigger.dev staging environment during setup or in your project settings.
<Note> Preview deployments require the preview environment to be enabled on your project. Learn more about [preview branches](/deployment/preview-branches). </Note>You can configure the following settings per-environment from your project's Vercel settings:
To change build options that would normally go in trigger.config.ts (such as extensions or other build configuration), use Build options on your project's configuration page in the Trigger.dev dashboard.
You can disconnect the Vercel integration from either side:
Disconnecting stops automatic deployments, environment variable syncing, and deployment checks. Your existing deployments and environment variables are not affected.