@trigger.dev/sdk 4.6.4 → 4.7.1

package/docs/deployment/atomic-deployment.mdx

@@ -1,184 +1,468 @@
 ---
-title: "Atomic deploys"
-sidebarTitle: "Atomic deploys"
-description: "Use atomic deploys to coordinate changes to your tasks and your application."
+title: "Atomic deployments"
+sidebarTitle: "Atomic deployments"
+description: "Keep your app and your tasks in sync with version skew protection: pin every run to the deployment built for the release of your app that triggered it."
 ---
 
+**Atomic deployments are provided by version skew protection: every run is pinned to the deployment built for the release of your app that triggered it.**
+
+Your app and your tasks are deployed separately, so they are never live at exactly the same instant. In the window between them, an app running new code can trigger tasks built from old code — or the other way around. That's **version skew**.
+
+Version skew protection closes the window. You give a deployment an **external deployment id**, your app sends the same id when it triggers, and Trigger.dev pins the run to the deployment carrying that id.
+
+<Note>
+  Version skew protection is available from `@trigger.dev/sdk` and the `trigger.dev` CLI
+  [v4.5.12](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.12), the release that
+  introduced external deployment ids. Upgrade both with `npx trigger.dev@latest update`. On an older
+  version no id is sent, and runs execute on the current version with no warning.
+</Note>
+
+## The guarantee
+
+Once your app is sending an external deployment id, a triggered run has one of four outcomes:
+
+| Situation                                            | What happens                                                        |
+| ---------------------------------------------------- | ------------------------------------------------------------------- |
+| A deployment with that id is live                     | The run is **pinned** to it and executes immediately.                 |
+| A deployment with that id is still building           | The run **waits**, then executes pinned to it once the build lands.   |
+| No deployment with that id ever arrives               | The run waits up to **1 hour**, then expires.                         |
+| No id was sent at all                                 | Nothing changes — the run executes on the current version.            |
+
+The common case is your app going live a few seconds before your task build finishes. The run waits for the matching deployment instead of executing on the previous one:
+
+```mermaid
+sequenceDiagram
+    participant CI as Your CI
+    participant App as Your app (release abc123)
+    participant T as Trigger.dev
+    participant D as Deployment abc123
+
+    CI->>T: trigger deploy --external-id abc123
+    T->>D: Start building
+    CI->>App: Deploy app with TRIGGER_EXTERNAL_DEPLOYMENT_ID=abc123
+    App->>T: myTask.trigger(payload) carrying id abc123
+    Note over T: No deployment with abc123 is live yet<br/>Run status: Pending version
+    D-->>T: Build finishes, deployment is live
+    T->>D: Release the run, pinned to abc123
+    D-->>T: Run completes
+```
+
+**The id is the contract.** There is no dashboard setting and nothing to switch on: if a trigger carries an external deployment id, that id is honoured. If it doesn't, behaviour is exactly what it is today.
+
+This works identically in production, staging and preview (including per-branch preview deployments), with no per-environment configuration.
+
+## Quick start
+
+The id is free-form and opaque to Trigger.dev — a commit SHA, a release tag, a CI run id, anything up to **128 characters**. The only rule is that both halves carry the **same value**.
+
+<Steps>
+
+<Step title="Deploy your tasks with an external id">
+
+```bash
+npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
+```
+
+</Step>
+
+<Step title="Give your running app the same value">
+
+Set this in your hosting platform's runtime environment variables, alongside `TRIGGER_SECRET_KEY`:
+
+```bash
+TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-same-commit-sha>
+```
+
+</Step>
+
+</Steps>
+
 <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.
+  Whatever you use on both sides, make sure it can't expand to an empty string. An unset shell
+  variable deploys with no id at all, which silently gives you no protection rather than an error.
 </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.
+That's it. Every task triggered by that release of your app now runs on the deployment you built for it.
+
+This recipe works on **every platform**, needs no integration, and is not git-specific. If you deploy to Vercel with the [Vercel integration](/vercel-integration), both halves are filled in for you — see [Automatic skew protection on Vercel](#automatic-skew-protection-on-vercel).
+
+## Deploying with an external id
+
+```bash
+npx trigger.dev@latest deploy --external-id <value>
+```
+
+The value is stored on the deployment. It is never interpreted, parsed or validated beyond its length — the only constraint is **128 characters or fewer**.
+
+### Reusing an id
+
+Because deploys are often retried, redeployed and re-run by CI, repeating an id is a normal thing to do rather than an error. What happens depends on the state of the deployment that already holds it:
+
+| Existing deployment for this id           | Default behaviour                                                                                         | With `--force`     |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------ |
+| **Deployed**                              | **No build.** The CLI reports the existing version, sets the same outputs, and exits successfully.          | Builds a new one.  |
+| **Building** (a deploy is in flight)      | **Error**, naming the version that is already building. Two builds racing for one id is almost always an accident. | **Cancels the in-flight build**, then starts a new one. |
+| **Failed, cancelled or timed out**        | **Rebuilds.** No flag needed — builds fail for reasons that have nothing to do with your code.              | Rebuilds.          |
+| **None**                                  | Builds.                                                                                                     | Builds.            |
+
+Deploying an id that is already live prints the existing version and stops:
+
+```bash
+Version 20250228.1 was already deployed for --external-id abc123 — nothing to build
+```
+
+Deploying an id that is mid-build fails, telling you which version is already building:
+
+```bash
+A deployment for external id "abc123" is already in progress (version 20250228.1). Wait for it to finish, or deploy again with --force to cancel it and start a new one.
+```
+
+The short-circuit on an already-deployed id makes `--external-id` useful on its own as **deploy idempotency**: a CI job that runs twice for the same commit builds once — provided the second run starts after the first has finished — and the short-circuited run still gets the version number in its output.
+
+A second run that starts while the first is still building hits the **Building** row above and errors. Only in the brief window before the first run has registered its build do both see "nothing deployed yet"; then both build, and the higher version wins.
+
+<Tip>
+  In GitHub Actions, the short-circuited run sets the same step outputs (such as
+  `deploymentVersion`) as a real build, so downstream steps work unchanged. One exception:
+  `needsPromotion` is always `false` on a short-circuit, because a reused version is never promoted —
+  so a workflow that gates a promote step on that output will skip promotion on the repeat run.
+</Tip>
+
+`--force` starts a new build for an id that already has one. It is non-destructive with respect to deployments that already **succeeded** — both remain, and the newer version wins. It *is* destructive to a build still in flight, which it cancels, because one id should not have two live builds racing to define it. It requires `--external-id`: on its own there is no previous deployment for it to build over, so it errors.
+
+<Note>
+  A cancelled deployment can never be deployed, so the build it replaces can't land. The build
+  itself is signalled to stop and usually does within seconds — but one running elsewhere (a
+  `--local-build`, or a deploy from someone else's machine) can keep going for a few minutes before
+  it notices.
+</Note>
+
+### Redeploying the same commit
+
+The short-circuit is keyed on the id alone, not on what went into the build. If you use the commit SHA as your id and then change something the commit doesn't capture — a synced environment variable, a secret, a dependency resolved at build time — redeploying that commit produces **no new build**, and the deployed image keeps the older inputs.
+
+Three ways out, in order of preference:
+
+- **Make a new commit.** `git commit --allow-empty -m "redeploy"` gives you a new SHA, which is a new id, which builds. This is the only remedy that also works for the Vercel and GitHub integrations, which never pass `--force`.
+- **Pass `--force`**, if you drive deploys yourself.
+- **Use an id that captures more than the commit** — `${GITHUB_SHA}-${GITHUB_RUN_ID}`, say — if your builds legitimately depend on inputs outside the tree. You lose idempotency in exchange.
+
+See the [deploy command reference](/cli-deploy-commands) for all deploy flags.
+
+## Automatic discovery
+
+Setting the id yourself is the explicit path, and it always works. The SDK can also **discover** an id from the variables your hosting platform or CI system already injects, so you don't have to wire anything up.
+
+Discovery happens at **runtime**, on each trigger call — never at module load — so a prebuilt bundle can't pin a stale value.
+
+The SDK takes the first of these that yields a value:
+
+1. **`externalDeploymentId` passed to the trigger call** — always honoured.
+2. **`externalDeploymentId` passed to `configure()`** — always honoured.
+3. **`TRIGGER_EXTERNAL_DEPLOYMENT_ID`** — always honoured.
+4. **Platform and CI variables** — read **only** when `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` is set to `1` or `true`.
+
+The first three are explicit acts on your part, so they need no opt-in. Only the fourth — reading a commit SHA your platform injected on its own — requires one, because that value is there whether or not anyone asked for this feature.
+
+```bash
+TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1
+```
 
-## How it works
+The value is trimmed and matched case-insensitively, so `true`, `TRUE` and `True` are all the same thing. Any other value — including `0`, an empty string, or the variable being absent — leaves automatic discovery off. The variable gates *discovery* only; an id you set explicitly is always honoured either way.
 
-Atomic deploys achieve synchronization by deploying your tasks to Trigger.dev without promoting them to the default version. Instead, you explicitly specify the deployed task version in your application’s environment. Here’s the process at a glance:
+<Warning>
+  **Most platforms expose the commit SHA to the build, not to the running process.** Discovery reads
+  `process.env` inside your live application, so a variable that only exists during the build is a
+  variable the SDK cannot see. On those platforms nothing is discovered and **nothing breaks** — your
+  runs simply execute on the current version, silently, as they do today. If your platform is marked
+  "Build only" below, use the [manual recipe](#the-manual-recipe) instead.
+</Warning>
 
-1. **Deploy Tasks to Trigger.dev**: Use the Trigger.dev CLI to deploy your tasks with the `--skip-promotion` flag. This creates a new task version without making it the default.
-2. **Capture the Deployment Version**: The CLI outputs the version of the deployed tasks, which you’ll use in the next step.
-3. **Deploy Your Application**: Deploy your application (e.g., to Vercel), setting an environment variable like `TRIGGER_VERSION` to the captured task version.
+### Hosting platforms
+
+Read first, because a hosting variable describes the deployment that is *running*.
+
+| Platform                      | Variable                                        | Available in the running app?                                                                                            |
+| ----------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **Vercel**                    | `VERCEL_GIT_COMMIT_SHA`                         | **Yes** — build and runtime, provided "Automatically expose System Environment Variables" is on for the project.           |
+| **Railway**                   | `RAILWAY_GIT_COMMIT_SHA`                        | **Yes** — injected at build and runtime, no configuration.                                                                 |
+| **Render**                    | `RENDER_GIT_COMMIT`                             | **Yes** — exposed in both build and runtime environments.                                                                  |
+| **Cloudflare Pages**          | `CF_PAGES_COMMIT_SHA`                           | **Yes** for Pages Functions; also present during the build.                                                                |
+| **Cloudflare Workers Builds** | `WORKERS_CI_COMMIT_SHA`                         | **Build only** — not injected into the deployed Worker. Must be forwarded.                                                 |
+| **Netlify**                   | `COMMIT_REF`                                    | **Build only** in the general case. Must be forwarded. (`CACHED_COMMIT_REF` is the *previous* build's SHA and is not read.) |
+| **AWS Amplify Hosting**       | `AWS_COMMIT_ID`                                 | **Build only.** Must be forwarded.                                                                                         |
+| **Heroku**                    | `HEROKU_BUILD_COMMIT`, then `HEROKU_SLUG_COMMIT` | **Runtime, opt-in** — requires dyno metadata.                                                                              |
+| **Koyeb**                     | `KOYEB_GIT_SHA`                                 | **Runtime only** (not available during the build).                                                                         |
+| **DigitalOcean App Platform** | —                                               | No fixed variable. Bind `${_self.COMMIT_HASH}` to a variable named `COMMIT_HASH` and the generic tier below picks it up.    |
+| **Fly.io**                    | —                                               | Nothing is injected. Set one of the generic names below at deploy time.                                                    |
+
+### CI systems
+
+Read second. These are correct when your application *is* the CI job, and they are the natural source for `--external-id` in a pipeline. Once the job has ended they no longer exist, so they cannot be discovered from a long-running app.
+
+| System              | Variable             |
+| ------------------- | -------------------- |
+| GitHub Actions      | `GITHUB_SHA`         |
+| GitLab CI           | `CI_COMMIT_SHA`      |
+| CircleCI            | `CIRCLE_SHA1`        |
+| Bitbucket Pipelines | `BITBUCKET_COMMIT`   |
+| Buildkite           | `BUILDKITE_COMMIT`   |
+| Azure Pipelines     | `BUILD_SOURCEVERSION` |
+| Google Cloud Build  | `COMMIT_SHA`         |
+| Drone / Woodpecker  | `DRONE_COMMIT_SHA`   |
+| Jenkins (git plugin) | `GIT_COMMIT`        |
+| TeamCity            | `BUILD_VCS_NUMBER`   |
+| Travis CI           | `TRAVIS_COMMIT`      |
+
+### Generic fallbacks
+
+Read last, after every named source above is exhausted:
+
+```text
+COMMIT_SHA  →  COMMIT_HASH  →  GIT_COMMIT  →  GIT_SHA  →  GIT_HASH
+```
 
-## Vercel CLI & GitHub Actions
+These are the answer for any platform not listed: set one of them and you get pinning with no other changes. They go last precisely because they are unnamespaced and could plausibly be set by something other than your deploy.
 
-If you deploy to Vercel via their CLI, you can use this sample workflow that demonstrates performing atomic deploys with GitHub Actions, Trigger.dev, and Vercel:
+Empty and whitespace-only values are skipped rather than treated as a match, and a value longer than 128 characters is skipped rather than sent — so a generic name holding something that isn't a deployment id degrades to "no id discovered" instead of an error.
 
-```yml
-name: Deploy to Trigger.dev (prod)
-on:
-  push:
-    branches:
-      - main
-concurrency:
-  group: ${{ github.workflow }}
-  cancel-in-progress: true
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
+<Tip>
+  If a generic name means something else in your environment, you have two clean escapes: set
+  `TRIGGER_EXTERNAL_DEPLOYMENT_ID` explicitly (it outranks all discovery), or leave
+  `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` off and use the manual recipe.
+</Tip>
 
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20.x"
+## The manual recipe
 
-      - name: Install dependencies
-        run: npm install
+If your platform only exposes the commit at build time — or injects nothing at all — set the id yourself. This is not a lesser mode: it is the same mechanism, and the same code path the Vercel integration uses with both halves filled in automatically.
 
-      - name: Deploy Trigger.dev
-        id: deploy-trigger
-        env:
-          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
-        run: |
-          npx trigger.dev@latest deploy --skip-promotion
+Read the commit in the place where it *is* available, and write it into both halves:
 
-      - name: Deploy to Vercel
-        run: npx vercel --yes --prod -e TRIGGER_VERSION=$TRIGGER_VERSION --token $VERCEL_TOKEN
-        env:
-          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
-          TRIGGER_VERSION: ${{ steps.deploy-trigger.outputs.deploymentVersion }}
+```bash
+# 1. Deploy side — name the deployment after the commit.
+npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)"
 
-      - name: Promote Trigger.dev Version
-        run: npx trigger.dev@latest promote $TRIGGER_VERSION
-        env:
-          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
-          TRIGGER_VERSION: ${{ steps.deploy-trigger.outputs.deploymentVersion }}
+# 2. Application side — give the running app the same value.
+TRIGGER_EXTERNAL_DEPLOYMENT_ID=<the-same-commit-sha>
 ```
 
-- Deploy to Trigger.dev
+Substitute a real value on both sides — and prefer something that fails loudly over a bare shell variable. On the platforms this section is about, the platform's own commit variable is usually **not** set in the shell you are deploying from, so `--external-id "$COMMIT_SHA"` would quietly deploy with no id and leave you unprotected.
+
+Whatever your platform calls its build-time commit variable — `COMMIT_REF` on Netlify, `AWS_COMMIT_ID` on Amplify, `WORKERS_CI_COMMIT_SHA` on Cloudflare Workers Builds, `$(git rev-parse HEAD)` in a bespoke pipeline — read it there and forward it.
+
+Half two can be a runtime environment variable set in your platform's configuration, or a build-time constant inlined into your bundle. Either works.
+
+Three things are worth knowing:
 
-  - The `npx trigger.dev deploy` command uses `--skip-promotion` to deploy the tasks without setting the version as the default.
-  - The step’s id: `deploy-trigger` allows us to capture the deployment version in the output (deploymentVersion).
+- **It needs no `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION`.** That variable gates discovery, not pinning, and an explicitly set id is always honoured.
+- **It is not Vercel-specific, or even git-specific.** A release tag or CI run id is fine — the value only has to match on both sides.
+- **Any name the SDK reads works.** `TRIGGER_EXTERNAL_DEPLOYMENT_ID` is the clearest, but one of the [generic fallbacks](#generic-fallbacks) does the same job.
 
-- Deploy to Vercel:
-  - The `npx vercel` command deploys the application, setting the `TRIGGER_VERSION` environment variable to the task version from the previous step.
-  - The --prod flag ensures a production deployment, and -e passes the environment variable.
-  - The `@trigger.dev/sdk` automatically uses the `TRIGGER_VERSION` environment variable to trigger the correct version of the tasks.
+## Setting the id in code
 
-For this workflow to work, you need to set up the following secrets in your GitHub repository:
+Environment variables are the usual way, but you can also pass the id directly. Both forms always win over discovery.
 
-- `TRIGGER_ACCESS_TOKEN`: Your Trigger.dev personal access token. View the instructions [here](/github-actions) to learn more.
-- `VERCEL_TOKEN`: Your Vercel personal access token. You can find this in your Vercel account settings.
+Per trigger call:
 
-## Vercel GitHub integration
+```ts
+import { myTask } from "./trigger/tasks";
 
-If you're are using Vercel, chances are you are using their GitHub integration and deploying your application directly from pushes to GitHub. This section covers how to achieve atomic deploys with Trigger.dev in this setup.
+await myTask.trigger(
+  { foo: "bar" },
+  { externalDeploymentId: process.env.VERCEL_GIT_COMMIT_SHA }
+);
+```
+
+Or once, for every trigger made by the process:
 
-### Turn off automatic promotion
+```ts
+import { configure } from "@trigger.dev/sdk";
+
+configure({
+  externalDeploymentId: process.env.MY_RELEASE_ID,
+});
+```
 
-By default, Vercel automatically promotes new deployments to production. To prevent this, you need to disable the auto-promotion feature in your Vercel project settings:
+An empty or whitespace-only value counts as "not supplied" rather than an error, so wiring up a variable that isn't always present is safe.
 
-1. Go to your Production environment settings in Vercel at `https://vercel.com/<team-slug>/<project-slug>/settings/environments/production`
-2. Disable the "Auto-assign Custom Production Domains" setting:
+Batch triggers carry the id too. `batchTrigger` resolves it per item exactly as `trigger` does, and it survives the asynchronous materialisation of batch items — so a large batch triggered during a deploy waits and releases item by item, each pinned to the deployment its calling code came from.
 
-![Vercel project settings showing the auto-promotion setting](/deployment/auto-assign-production-domains.png)
+## Chat sessions
 
-3. Hit the "Save" button to apply the changes.
+[Chat agents](/ai-chat/overview) are covered by the same mechanism, with one difference: the id belongs to the **session**, not to a single trigger. It is resolved wherever you start the session — your server action, your route handler, `sessions.start()` — using the same order of precedence as a task trigger, and stored on the session. Every run that session goes on to schedule carries it: the first run, each continuation after an idle suspend, and each recovery after a crash.
 
-Now whenever you push to your main branch, Vercel will deploy your application to the production environment without promoting it, and you can control the promotion manually.
+That is what you want for a conversation. A chat started by one release of your app keeps talking to the agent build that release shipped with, however many turns and however many runs that takes.
 
-### Deploy with Trigger.dev
+Chats need the same two halves as tasks, and no more: a deployment carrying an id, and an app that sends the same one (explicitly, through `TRIGGER_EXTERNAL_DEPLOYMENT_ID`, or through [automatic discovery](#automatic-discovery)). There is nothing chat-specific to switch on, so an app already pinning its task runs gets pinned chats with no code change.
 
-Now we want to deploy that same commit to Trigger.dev, and then promote the Vercel deployment when that completes. Here's a sample GitHub Actions workflow that does this:
+```ts
+// app/actions.ts
+"use server";
+import { chat } from "@trigger.dev/sdk/ai";
+import type { myChat } from "@/trigger/chat";
 
-```yml
-name: Deploy to Trigger.dev (prod)
+// No chat-specific setup: the id is discovered per call, exactly as it is for `trigger()`.
+export const startChatSession = chat.createStartSessionAction<typeof myChat>("my-chat");
+```
+
+Three things follow from the pin living on the session:
+
+- **Starting the session again refreshes it, and the conversation follows.** `sessions.start()` is idempotent on `chatId` and rewrites the stored config, so when your transport calls `startSession` after a redeploy, the session re-pins. A **running** agent then hands the conversation over at the next turn boundary, so the next message is answered by the deployment you just named — not several turns later when the old run happens to end. The turn already in flight finishes on the code it started on. Set [`versionSkew: "hold"`](/ai-chat/patterns/version-upgrades#staying-put) on an agent that should stay put instead.
+- **There is one pin per `chatId`.** If the same conversation is open in two tabs on two different releases of your app, whichever called `startSession` most recently sets the pin for both.
+- **A parked chat is waiting, not broken.** A run pinned to a deployment that hasn't landed parks, and every message sent meanwhile is stored durably and delivered once the deployment arrives. Nothing is lost — but nothing answers either, so tell the user. Re-pinning does not release a parked run: it keeps waiting for the deployment it was created for. If that deployment never lands, the run waits until its park deadline elapses, and the next message after that starts a fresh run on the session's current pin. Pass `pendingVersion` through your `startSession` callback and the transport emits a `run-pending-version` event:
+
+```tsx
+const transport = useTriggerChatTransport({
+  task: "my-chat",
+  accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+  startSession: ({ chatId, clientData }) => startChatSession({ chatId, clientData }),
+  onEvent: (event) => {
+    if (event.type === "run-pending-version") setDeploying(true);
+    if (event.type === "first-chunk") setDeploying(false);
+  },
+});
+```
 
-on:
-  push:
-    branches:
-      - main
+The event repeats on every message sent while the chat is parked, so a notice driven off it stays accurate. Its `source` says where the park was learned: `start` from creating the session, `send` from an append, `head-start` from the route's response header, and `upgrade` when a session followed its pin onto a deployment that hasn't landed yet — that last one arrives as soon as the handoff happens, without waiting for another message.
 
-concurrency:
-  group: ${{ github.workflow }}
-  cancel-in-progress: true
+[Head Start](/ai-chat/fast-starts#head-start) softens this considerably: turn 1 runs in your own warm process, so a parked deployment costs nothing until step 2. The handover signal is durable, so the agent picks the turn up where it left off once the deployment lands. The transport emits `run-pending-version` with `source: "head-start"` for that case, and `chat.startHeadStart` returns `pendingVersion` for the detached flow.
 
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
+### Opting a chat out
 
-    steps:
-      - uses: actions/checkout@v4
+Pass `null` and that chat is never pinned, whatever the environment says:
 
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20.x"
+```ts
+export const startChatSession = chat.createStartSessionAction<typeof myChat>("my-chat", {
+  triggerConfig: { externalDeploymentId: null },
+});
+```
 
-      - name: Install dependencies
-        run: npm install
+Use this for a conversation that should always run on the current version — a long-lived support thread, say — while the rest of your chats stay pinned. To turn pinning off everywhere instead, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` and don't set `TRIGGER_EXTERNAL_DEPLOYMENT_ID`.
 
-      - name: Wait for vercel deployment (push)
-        id: wait-for-vercel
-        uses: ludalex/vercel-wait@v1
-        with:
-          project-id: ${{ secrets.VERCEL_PROJECT_ID }}
-          team-id: ${{ secrets.VERCEL_SCOPE_NAME }}
-          token: ${{ secrets.VERCEL_TOKEN }}
-          sha: ${{ github.sha }}
+### Escaping the pin from inside the agent
 
-      - name: 🚀 Deploy Trigger.dev
-        id: deploy-trigger
-        env:
-          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
-        run: |
-          npx trigger.dev@latest deploy
+[`chat.requestUpgrade()`](/ai-chat/patterns/version-upgrades) clears the session's external deployment id as part of the handoff, so the new run is free to land on the current version. Pass a target to move to a specific deployment instead:
 
-      - name: Promote Vercel deploy
-        run: npx vercel promote $VERCEL_DEPLOYMENT_ID --yes --token $VERCEL_TOKEN --scope $VERCEL_SCOPE_NAME
-        env:
-          VERCEL_DEPLOYMENT_ID: ${{ steps.wait-for-vercel.outputs.deployment-id }}
-          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
-          VERCEL_SCOPE_NAME: ${{ secrets.VERCEL_SCOPE_NAME }}
+```ts
+chat.requestUpgrade({ externalDeploymentId: clientData.commitSha });
 ```
 
-This workflow does the following:
+Either way the change is persisted on the session, so the next continuation doesn't fall back to the id the agent just rejected. `lockToVersion` is a separate, explicit pin and is never cleared — `requestUpgrade()` cannot escape it, which is also why a session using it never follows its external deployment id automatically.
+
+## Waiting and expiry
 
-1. Waits for the Vercel deployment to complete using the `ludalex/vercel-wait` action.
-2. Deploys the tasks to Trigger.dev using the `npx trigger.dev deploy` command. There's no need to use the `--skip-promotion` flag because we want to promote the deployment.
-3. Promotes the Vercel deployment using the `npx vercel promote` command.
+When a run arrives with an id that isn't deployed yet, it doesn't fail — it **waits**. This is the ordinary case, not an edge case: your app frequently goes live a few seconds before your task build finishes.
 
-For this workflow to work, you need to set up the following secrets in your GitHub repository:
+A waiting run shows in the dashboard with the status **Pending version** and the reason _"Waiting for a deployment with this run's external deployment id"_. As soon as a deployment carrying that id is deployed, the run is released and executes pinned to it.
 
-- `TRIGGER_ACCESS_TOKEN`: Your Trigger.dev personal access token. View the instructions [here](/github-actions) to learn more.
-- `VERCEL_TOKEN`: Your Vercel personal access token. You can find this in your Vercel account settings.
-- `VERCEL_PROJECT_ID`: Your Vercel project ID. You can find this in your Vercel project settings.
-- `VERCEL_SCOPE_NAME`: Your Vercel team slug.
+An unknown id waits too, for the same reason: "we haven't seen this deployment" and "this deployment hasn't been created yet" look identical from the outside, and the second is common — your app often goes live before your deploy pipeline has even claimed a runner.
 
-Checkout our [example repo](https://github.com/ericallam/vercel-atomic-deploys) to see this workflow in action.
+<Warning>
+  A run waiting on an external deployment id that never arrives **expires after 1 hour**. It moves
+  to `EXPIRED` with a message naming the id it waited for — `Run expired because no deployment with
+  external id 'abc123' became available`. This bounds — but does not diagnose — the configuration
+  mistakes that produce a deployment which never lands. See [When nothing ever
+  lands](#when-nothing-ever-lands).
+</Warning>
+
+A shorter [run-level `ttl`](/triggering#ttl) that you set yourself still wins — the one-hour deadline is a backstop, not an extension. Note that the run still expires *as* an external-deployment expiry: the status reason and message name the id it was waiting for, not the `ttl`.
 
 <Note>
-  We are using the `ludalex/vercel-wait` action above as a fork of the [official
-  tj-actions/vercel-wait](https://github.com/tj-actions/vercel-wait) action because there is a bug
-  in the official action that exits early if the deployment isn't found in the first check and due
-  to the fact that it supports treating skipped (cancelled) Vercel deployments as valid (on by default). 
-  I've opened a PR for this issue [here](https://github.com/tj-actions/vercel-wait/pull/106).
+  This deadline applies only to runs waiting on an external deployment id. Runs that wait for the
+  reasons that already exist — such as triggering a task before your first deploy — keep waiting
+  indefinitely, unchanged.
 </Note>
+
+## When nothing ever lands
+
+Waiting is the right answer to a race and the wrong answer to a misconfiguration, and for the first hour the two look identical. Three setups produce an id that will never be deployed, and each expires **every** run from the affected release.
+
+### The commit didn't build any tasks
+
+The most damaging one, and the easiest to create by accident. If your deploy workflow is filtered on paths — `paths: ['trigger/**']` in a monorepo is the usual shape — a commit that only touches your application produces **no Trigger.dev deployment at all**. Your app still sends that commit's SHA, nothing ever holds it, and every run from that release waits an hour and expires.
+
+If you filter deploys by path, derive the id from the same filter on both sides — the SHA of the last commit that touched your task directory, not the commit being deployed:
+
+```bash
+TASK_ID=$(git log -1 --format=%H -- trigger/)
+npx trigger.dev@latest deploy --external-id "$TASK_ID"
+```
+
+Compute the same value where you set your app's variable. In GitHub Actions this needs `fetch-depth: 0` on `actions/checkout` — the default shallow clone can't see far enough back.
+
+### Two applications, one Trigger.dev project
+
+If two deployables share one Trigger.dev project and only one of them deploys tasks, the other still sends its own commit SHA — an id nothing will ever hold. Give the application that doesn't build tasks either no id, or the id of the deployment it should run against.
+
+### A preview deployment promoted to production
+
+Ids resolve **within a single environment**. An id deployed to a preview branch does not exist in production, so promoting that preview build in your hosting platform — without a production deploy carrying the same id — parks and expires every production run. Deploy to production the normal way rather than promoting a preview artifact.
+
+<Tip>
+  A run that hit one of these shows as `EXPIRED` with `Run expired because no deployment with
+  external id '…' became available`. An environment producing nothing but that message has a
+  configuration problem, not a timing problem.
+</Tip>
+
+## Precedence
+
+Several things can pin a run. The SDK sends an **explicit version** — the `version` option if you passed one, otherwise `TRIGGER_VERSION` — and the external deployment id, whenever it has them. The server then prefers the explicit version, then the id, then the current version:
+
+```text
+explicit version (version option, else TRIGGER_VERSION)  >  external deployment id  >  current version
+```
+
+- An explicit `version` passed to `trigger()` always wins. Because the SDK folds the option and the variable into a single value before sending, the `version` option overrides `TRIGGER_VERSION` on the client, and the server only ever sees the winner.
+- An explicit version therefore beats an external deployment id. This is what makes migration from [legacy atomic deployments](#legacy-atomic-deployments) safe: the legacy pin keeps governing until you remove the variable.
+- An external deployment id sent alongside an explicit version is **ignored, not an error**.
+- A trigger carrying neither runs on the current version.
+
+<Warning>
+  **Don't leave a stale `TRIGGER_VERSION` behind.** A `TRIGGER_VERSION` naming a version that
+  doesn't exist *in the environment being triggered* is not a soft failure and not a fallback —
+  **every trigger fails** with a `422`, wherever the trigger came from. It also suppresses the
+  external deployment id, so skew protection can't rescue it.
+
+  The usual way to hit this is setting `TRIGGER_VERSION` at the project level on your hosting
+  platform: a version built in production doesn't exist in preview, so every preview trigger fails.
+  Remove the variable once you've confirmed skew protection is working.
+</Warning>
+
+```ts
+// Explicit version wins, even if an external deployment id is discovered.
+await myTask.trigger({ foo: "bar" }, { version: "20250228.1" });
+```
+
+## Automatic skew protection on Vercel
+
+If you use the [Vercel integration](/vercel-integration), version skew protection is set up for you and both halves are automatic:
+
+- The integration sets **`TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION=1`** on your Vercel project when you connect it, and adds it on the next build if it is missing — so projects connected before this existed pick it up without reconnecting. It only ever adds the variable, never overwrites one that is already there.
+- The integration passes **your commit SHA** as the deploy's external id.
+- `VERCEL_GIT_COMMIT_SHA` is available at runtime on Vercel, so the SDK discovers the matching id with no work from you.
+
+This covers production, staging and preview alike.
+
+### Opting out
+
+Set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` on your Vercel project. A `0` you set today stays `0` through every subsequent build.
+
+Opting out only disables automatic *discovery*. You can still pin explicitly at any time by setting `TRIGGER_EXTERNAL_DEPLOYMENT_ID` yourself.
+
+## Legacy atomic deployments
+
+Before version skew protection, the [Vercel integration](/vercel-integration#atomic-deployments) kept your app and tasks in sync by gating your Vercel deployment until the Trigger.dev build finished, then creating a **second** Vercel deployment with `TRIGGER_VERSION` set to the new task version and promoting it. This needed two Vercel deployments per release, required `Auto-assign Custom Production Domains` to be disabled, and covered production only. The same pattern could be built by hand with `trigger deploy --skip-promotion` and `TRIGGER_VERSION`.
+
+<Warning>
+  Legacy atomic deployments are **deprecated and not advised** for new setups. The setting still
+  works for projects that already have it enabled, and is off by default for new connections. Use
+  version skew protection instead.
+</Warning>
+
+To migrate:
+
+1. Upgrade your app and deploys to **v4.5.12 or later**.
+2. Verify on a preview deployment. Atomic deployments only set `TRIGGER_VERSION` on production, so a preview run is pinned by its external deployment id alone. Push a branch, trigger a task from the preview deployment, and check that the run's **External deployment ID** matches the commit SHA and that it ran on that branch's deployment.
+3. Turn **Atomic deployments** off in your project's Vercel integration settings, and remove `TRIGGER_VERSION` from your Vercel production environment. Until you remove it, it outranks the external deployment id.
+4. Put production promotion back in place: re-enable `Auto-assign Custom Production Domains` in Vercel, or promote from your own pipeline. Atomic deployments turned auto-assign off, so without this a new production deployment is never served on your domain.
+5. Deploy to production and run the same check there.

package/docs/deployment/overview.mdx

@@ -121,7 +121,7 @@ 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).
+  protection](/deployment/atomic-deployment).
 </Tip>
 
 ### Child tasks and auto-version locking
@@ -157,7 +157,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 keep your app and tasks in sync without coordinating promotion at all, see [version skew protection](/deployment/version-skew-protection).
+To keep your app and tasks in sync without coordinating promotion at all, see [atomic deployments](/deployment/atomic-deployment).
 
 ## Staging deploys