docs: task version skew protection, --external-id, and the atomic deployments deprecation

New deployment/version-skew-protection page: the skew problem, the
--external-id primitive and its reuse behaviour, runtime discovery (call
option, configure(), TRIGGER_EXTERNAL_DEPLOYMENT_ID, and the gated
platform/CI/generic commit-SHA variables with the build-time caveat), the
manual any-platform recipe, waiting/expiry semantics, precedence, and
automatic skew protection on Vercel. Deprecation callouts on the atomic
deployments page and the Vercel integration page; --external-id/--force
added to the CLI deploy reference; redirect from
deployment/vercel-skew-protection so existing webapp links resolve
(TRI-13002).

Author: 0ski

docs/deployment/atomic-deployment.mdx

@@ -4,6 +4,18 @@ sidebarTitle: "Atomic deploys"
 description: "Use atomic deploys to coordinate changes to your tasks and your application."
 ---
 
+<Warning>
+  **There's now a simpler way to do this.** [Version skew
+  protection](/deployment/version-skew-protection) solves the same problem without a second
+  deployment, without gating your app's deploy, and without setting `TRIGGER_VERSION` — and it covers
+  staging and preview as well as production. If you use the [Vercel
+  integration](/vercel-integration), its **automatic atomic deployments** setting is now deprecated
+  in favour of skew protection.
+
+  The manual workflows on this page still work, and remain the right answer if you specifically want
+  your application's deployment held back until your tasks have finished building.
+</Warning>
+
 Atomic deploys in Trigger.dev allow you to synchronize the deployment of your application with a specific version of your tasks. This ensures that your application always uses the correct version of its associated tasks, preventing inconsistencies or errors due to version mismatches.
 
 ## How it works

docs/deployment/overview.mdx

@@ -122,6 +122,12 @@ If you want to set a global version to run all tasks against, you can use the `T
 TRIGGER_VERSION=20250228.1
 ```
 
+<Tip>
+  If what you actually want is for each release of your app to run against the tasks built from the
+  same commit, you don't need to plumb version numbers around by hand. See [version skew
+  protection](/deployment/version-skew-protection).
+</Tip>
+
 ### Child tasks and auto-version locking
 
 Trigger and wait functions version lock child task runs to the parent task run version. This ensures the results from child runs match what the parent task is expecting. If you don't wait then version locking doesn't apply.
@@ -155,7 +161,7 @@ Or from the dashboard:
 
 ![Trigger.dev dashboard showing the promote button](/deployment/promote-button.png)
 
-To learn more about skipping promotion and how this enables atomic deployments, see our [Atomic deployment](/deployment/atomic-deployment) guide.
+To learn more about skipping promotion and how this enables atomic deployments, see our [Atomic deployment](/deployment/atomic-deployment) guide. To keep your app and tasks in sync without coordinating promotion at all, see [version skew protection](/deployment/version-skew-protection).
 
 ## Staging deploys
 

docs/deployment/version-skew-protection.mdx

@@ -187,6 +187,7 @@
               "github-actions",
               "deployment/preview-branches",
               "deployment/dev-branches",
+              "deployment/version-skew-protection",
               "deployment/atomic-deployment",
               {
                 "group": "Deployment integrations",
@@ -893,6 +894,11 @@
     {
       "source": "/guides/ai-chat",
       "destination": "/ai-chat/overview"
+    },
+    {
+      "source": "/deployment/vercel-skew-protection",
+      "destination": "/deployment/version-skew-protection",
+      "permanent": true
     }
   ]
 }

docs/docs.json

@@ -11,7 +11,7 @@ The instructions below are specific to GitHub Actions, but the same concepts can
 
 ## GitHub Actions example
 
-This simple GitHub action workflow will deploy your Trigger.dev tasks when new code is pushed to the `main` branch and the `trigger` directory has changes in it.
+This simple GitHub action workflow will deploy your Trigger.dev tasks when new code is pushed to the `main` branch.
 
 <Warning>
   The deploy step will fail if any version mismatches are detected. Please see the [version
@@ -47,7 +47,7 @@ jobs:
         env:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
         run: |
-          npx trigger.dev@latest deploy
+          npx trigger.dev@latest deploy --external-id ${{ github.sha }}
 ```
 
 ```yaml .github/workflows/release-trigger-staging.yml
@@ -76,13 +76,37 @@ jobs:
         env:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
         run: |
-          npx trigger.dev@latest deploy --env staging
+          npx trigger.dev@latest deploy --env staging --external-id ${{ github.sha }}
 ```
 
 </CodeGroup>
 
 If you already have a GitHub action file, you can just add the final step "🚀 Deploy Trigger.dev" to your existing file.
 
+### Pinning runs to the deployment you just built
+
+The `--external-id ${{ github.sha }}` above tags the deployment with the commit it was built from. That is the first half of [version skew protection](/deployment/version-skew-protection): to complete it, give your running application the **same value** so it sends that id when it triggers.
+
+```bash
+# In your application's runtime environment, for the release built from this commit
+TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-same-commit-sha>
+```
+
+Every task triggered by that release is then pinned to the deployment built from the same commit — and runs triggered before the task build finishes wait for it rather than executing on the previous version.
+
+<Note>
+  Tagging the deployment is harmless on its own: if nothing sends a matching id, runs behave exactly
+  as they do today. `--external-id` also makes repeat deploys idempotent — re-running the workflow
+  for a commit that is already deployed reports the existing version instead of building again.
+
+  Two things follow from that. Because no build runs, a re-run after changing a synced environment
+  variable won't pick the new value up — make an empty commit, or pass `--force`. And if you add a
+  `paths:` filter to this workflow, `${{ github.sha }}` stops being a safe id: commits that don't
+  touch your tasks never produce a deployment carrying that SHA, so every run from those releases
+  expires. See [when nothing ever
+  lands](/deployment/version-skew-protection#when-nothing-ever-lands).
+</Note>
+
 ## Preview branches
 
 To deploy to preview branches from Pull Requests and have them archived when PRs are merged or closed, use a workflow that runs on `pull_request` with **all four types** including `closed`:
@@ -109,7 +133,7 @@ jobs:
         run: npm install
 
       - name: Deploy preview branch
-        run: npx trigger.dev@latest deploy --env preview
+        run: npx trigger.dev@latest deploy --env preview --external-id ${{ github.sha }}
         env:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
 ```

docs/github-actions.mdx

@@ -72,6 +72,18 @@ The name of the preview branch matches the branch name of the pull request.
   Preview branch deployments require the preview environment to be enabled on your project. Learn more about [preview branches](/deployment/preview-branches).
 </Note>
 
+## Version skew protection
+
+Every deployment the GitHub integration creates is tagged with the commit SHA it was built from. That is the deploy half of [version skew protection](/deployment/version-skew-protection) — you get it for free.
+
+To complete it, give your running application the same value. Unlike the Vercel integration, we have no access to wherever your app is hosted, so this half is yours to set:
+
+```bash
+TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-commit-sha-this-release-was-built-from>
+```
+
+If your host already exposes the commit SHA at runtime, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1` instead and the SDK will find it — see the [platform table](/deployment/version-skew-protection#hosting-platforms).
+
 ## Disconnecting a repository
 
 You can disconnect a repository at any time from your project git settings. This will stop automatic deployments triggered from GitHub.

docs/github-integration.mdx

@@ -77,6 +77,27 @@ npx trigger.dev@latest deploy [path]
   Turn off syncing environment variables with the Trigger.dev instance.
 </ParamField>
 
+<ParamField body="External id" type="--external-id">
+  Attach your own identifier to this deployment — a commit SHA, release tag or CI run id, up to 128
+  characters. Your app can then send the same id when triggering, and runs are pinned to this
+  deployment. See [version skew protection](/deployment/version-skew-protection).
+
+  Repeating an id that is already deployed doesn't build again: the CLI reports the existing version,
+  sets the same outputs, and exits successfully. Repeating an id that has a build in flight is an
+  error. An id whose build failed rebuilds normally.
+
+  The short-circuit is keyed on the id, not on the build inputs — so redeploying the same id after
+  changing a synced environment variable produces no new build.
+</ParamField>
+
+<ParamField body="Force" type="--force">
+  Start a new build for an `--external-id` that already has one. Non-destructive with respect to
+  deployments that already succeeded — both remain and the newer version wins. If a build for that
+  id is still in flight, `--force` **cancels** it first, so one id never has two live builds. A
+  cancelled build usually stops within seconds, but one running on another machine can keep going
+  briefly before it notices. Requires `--external-id`.
+</ParamField>
+
 <ParamField body="Local build" type="--local-build">
   Force building the deployment image locally using your local Docker. This is automatic when self-hosting.
 </ParamField>

docs/snippets/cli-commands-deploy.mdx

@@ -5,7 +5,7 @@ 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 supports atomic deployments to keep your app and tasks in sync.
+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.
 
@@ -42,8 +42,7 @@ You can connect Vercel from two entry points:
 </Step>
 
 <Step title="Configure build options">
-  Optionally adjust [build options](#build-options) for atomic deployments, env var pulling, and new
-  env var discovery.
+  Optionally adjust [build options](#build-options) for env var pulling and new env var discovery.
 </Step>
 
 <Step title="Connect GitHub">
@@ -99,7 +98,7 @@ The integration syncs environment variables in both directions:
 
 The following variables are excluded from the Vercel → Trigger.dev sync:
 
-- `TRIGGER_SECRET_KEY`, `TRIGGER_VERSION`, `TRIGGER_PREVIEW_BRANCH` (managed by Trigger.dev)
+- `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.
@@ -120,8 +119,41 @@ You can control sync behavior per-variable from your project's Vercel settings.
 
 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
@@ -152,15 +184,16 @@ sequenceDiagram
   TD->>TD: Promote build
 ```
 
-Atomic deployments are enabled for the production environment by default.
+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.
+  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).
+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
 
@@ -184,7 +217,7 @@ If your Vercel project has a custom environment, you can select which one maps t
 
 You can configure the following settings per-environment from your project's Vercel settings:
 
-- **Atomic deployments**: Controls whether Trigger.dev and Vercel deployments are synchronized. Enabled for production by default.
+- **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.
 
@@ -201,7 +234,8 @@ Disconnecting stops automatic deployments, environment variable syncing, and dep
 
 ## Related
 
+- [Version skew protection](/deployment/version-skew-protection)
 - [GitHub integration](/github-integration)
-- [Atomic deploys](/deployment/atomic-deployment)
+- [Atomic deploys](/deployment/atomic-deployment) (deprecated for Vercel)
 - [Environment variables](/deploy-environment-variables)
 - [Preview branches](/deployment/preview-branches)

docs/vercel-integration.mdx

@@ -47,6 +47,8 @@ So a task run will continue running on the version it was locked to. We do this
 
 Every deployment creates a new version of all tasks for that environment.
 
+Because your application and your tasks deploy separately, a release of your app can briefly trigger tasks that belong to a different version. [Version skew protection](/deployment/version-skew-protection) pins each run to the deployment built from the same commit.
+
 ## Retries and reattempts
 
 When a task has an uncaught error it will [retry](/errors-retrying), assuming you have not set `maxAttempts` to 0. Retries are locked to the original version of the run.