triggerdotdev--trigger.dev/docs/vercel-integration.mdx

---
title: "Vercel integration"
description: "Automatically deploy your tasks whenever you deploy to Vercel."
---

## How it works

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](/deployment/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.

<Note>
  The Vercel integration requires the [GitHub integration](/github-integration) to be connected as
  well, since Trigger.dev builds your tasks from your GitHub repository.
</Note>

## Installation

You can connect Vercel from two entry points:

### From the Trigger.dev dashboard

<Steps>

<Step title="Connect Vercel">
  Go to your project's **Settings** page and click **Connect Vercel**. This will redirect you to
  Vercel to authorize the Trigger.dev app.
</Step>

<Step title="Select a Vercel project">
  Choose which Vercel project to connect to your Trigger.dev project.
</Step>

<Step title="Map environments">
  If your Vercel project has custom environments, choose which one maps to your Trigger.dev staging
  environment.
</Step>

<Step title="Sync environment variables">
  Review the environment variables that will be pulled from Vercel into Trigger.dev. You can
  deselect any variables you don't want to sync.
</Step>

<Step title="Configure build options">
  Optionally adjust [build options](#build-options) for env var pulling and new env var discovery.
</Step>

<Step title="Connect GitHub">
  If your GitHub repository isn't already connected, you'll be prompted to connect it.
</Step>

</Steps>

### From the Vercel Marketplace

<Steps>

<Step title="Install the integration">
  Install the [Trigger.dev integration from the Vercel
  Marketplace](https://vercel.com/marketplace/trigger). This will redirect you to Trigger.dev to
  complete setup.
</Step>

<Step title="Select your Trigger.dev organization and project">
  Choose which Trigger.dev organization and project to connect. If you're new to Trigger.dev, you'll
  be guided through creating an organization and project.
</Step>

<Step title="Connect GitHub">
  If your GitHub repository isn't already connected, you'll be prompted to connect it.
</Step>

</Steps>

<Note>
  When installing from the Vercel Marketplace, default Build options are applied automatically. You
  can adjust them later in your project settings.
</Note>

<Warning>
  **Vercel Root Directory:** If your Vercel project uses a **Root Directory** (e.g. you deploy a
  single subfolder such as `app` or `web`), you may see "The specified Root Directory does not
  exist" after connecting the integration. If you see this error, try using the **repository root**
  (leave Root Directory empty) in your Vercel project settings. If your Vercel frontend build
  requires a Root Directory (e.g. in a monorepo), keep that setting in Vercel and instead point
  Trigger.dev to the subfolder by setting the **Trigger config file** path (and other [Build
  options](#build-options)) in your Trigger.dev project configuration. Trigger.dev always builds
  from the repo root.
</Warning>

## Environment variable sync

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)
- Sensitive/secret-type variables (Vercel API limitation)

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>

### Supabase and Neon database branching

If you use [Supabase Branching](https://supabase.com/docs/guides/deployment/branching) or [Neon Database Branching](https://neon.tech/docs/guides/branching-intro) for preview environments, disable syncing for database env vars on the Environment Variables page and use the [syncSupabaseEnvVars](/config/extensions/syncEnvVars#syncsupabaseenvvars) or [syncNeonEnvVars](/config/extensions/syncEnvVars#syncneonenvvars) build extensions instead. These extensions automatically resolve the correct branch-specific credentials at build time.

## Version skew protection

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](/deployment/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:

- It sets `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.
- It passes your commit SHA as the deployment's external id.
- `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.

## Atomic deployments

<Warning>
  **Automatic atomic deployments are deprecated.** Use [version skew
  protection](/deployment/version-skew-protection) instead — it needs no second Vercel deployment,
  never gates your app's deploy, doesn't touch `Auto-assign Custom Production Domains`, and covers
  staging and preview as well as production.

  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.

```mermaid
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](/deployment/atomic-deployment). For how to move off them, see [replacing automatic atomic deployments](/deployment/version-skew-protection#replacing-automatic-atomic-deployments).

## Environment mapping

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>

## Build options

You can configure the following settings per-environment from your project's Vercel settings:

- **Atomic deployments** (deprecated): Controls whether Trigger.dev gates and redeploys your Vercel deployment to keep it in sync. Off by default for new connections — use [version skew protection](/deployment/version-skew-protection) instead.
- **Pull env vars before build**: When enabled, Trigger.dev pulls the latest environment variables from Vercel before each build. Enabled for production, staging, and preview by default.
- **Discover new env vars**: When enabled, new environment variables found in Vercel that don't yet exist in Trigger.dev are created automatically during builds. Only available for environments that also have env var pulling enabled. Enabled for production, staging, and preview by default.

To change build options that would normally go in `trigger.config.ts` (such as [extensions](/config/config-file#extensions) or other build configuration), use **Build options** on your project's configuration page in the Trigger.dev dashboard.

## Disconnecting

You can disconnect the Vercel integration from either side:

- **From Trigger.dev**: Go to your project **Settings** and disconnect Vercel.
- **From Vercel**: Uninstall the Trigger.dev integration from your Vercel dashboard. This is automatically detected and the connection is removed on the Trigger.dev side.

Disconnecting stops automatic deployments, environment variable syncing, and deployment checks. Your existing deployments and environment variables are not affected.

## Related

- [Version skew protection](/deployment/version-skew-protection)
- [GitHub integration](/github-integration)
- [Atomic deploys](/deployment/atomic-deployment) (deprecated for Vercel)
- [Environment variables](/deploy-environment-variables)
- [Preview branches](/deployment/preview-branches)