diff --git a/docs/deployment/atomic-deployment.mdx b/docs/deployment/atomic-deployment.mdx index 5edcb090e30..fc72f1cea9d 100644 --- a/docs/deployment/atomic-deployment.mdx +++ b/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." --- + + **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. + + 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 diff --git a/docs/deployment/overview.mdx b/docs/deployment/overview.mdx index 103746ba09c..39036cf6434 100644 --- a/docs/deployment/overview.mdx +++ b/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 ``` + + 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). + + ### 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 diff --git a/docs/deployment/version-skew-protection.mdx b/docs/deployment/version-skew-protection.mdx new file mode 100644 index 00000000000..2ecd783a5ef --- /dev/null +++ b/docs/deployment/version-skew-protection.mdx @@ -0,0 +1,430 @@ +--- +title: "Version skew protection" +description: "Pin task runs to the deployment that matches the release of your app that triggered them." +--- + +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. + + + Version skew protection requires `@trigger.dev/sdk` and the `trigger.dev` CLI on [v4.5.12 or + later](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.12), the release that + introduced external deployment ids. On an older version no id is sent, and runs execute on the + current version with no warning. + + +## 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 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**. + + + + + +```bash +npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)" +``` + + + + + +Set this in your hosting platform's runtime environment variables, alongside `TRIGGER_SECRET_KEY`: + +```bash +TRIGGER_EXTERNAL_DEPLOYMENT_ID= +``` + + + + + + + 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. + + +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 +``` + +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. + + + 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. + + +`--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. + + + 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. + + +### 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 +``` + +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. + + + **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. + + +### 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 +``` + +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. + +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. + + + 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. + + +## The manual recipe + +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. + +Read the commit in the place where it *is* available, and write it into both halves: + +```bash +# 1. Deploy side — name the deployment after the commit. +npx trigger.dev@latest deploy --external-id "$(git rev-parse HEAD)" + +# 2. Application side — give the running app the same value. +TRIGGER_EXTERNAL_DEPLOYMENT_ID= +``` + +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: + +- **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. + +### Example: Netlify + +Netlify exposes `COMMIT_REF` to the build only, so forward it: + +```bash +# In your build command or CI step +npx trigger.dev@latest deploy --external-id "$COMMIT_REF" +``` + +Then set `TRIGGER_EXTERNAL_DEPLOYMENT_ID` to the same commit in your site's runtime environment variables — for example by writing it during the build, or by having your deploy pipeline set it through the Netlify API. + +## Setting the id in code + +Environment variables are the usual way, but you can also pass the id directly. Both forms always win over discovery. + +Per trigger call: + +```ts +import { myTask } from "./trigger/tasks"; + +await myTask.trigger( + { foo: "bar" }, + { externalDeploymentId: process.env.VERCEL_GIT_COMMIT_SHA } +); +``` + +Or once, for every trigger made by the process: + +```ts +import { configure } from "@trigger.dev/sdk"; + +configure({ + externalDeploymentId: process.env.MY_RELEASE_ID, +}); +``` + +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. + +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. + +## Waiting and expiry + +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. + +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. + +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. + + + 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). + + +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`. + + + 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. + + +## 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. + + + 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. + + +## 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 [atomic deploys](/deployment/atomic-deployment) 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. + + + **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. + + +```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. + +## Replacing automatic atomic deployments + + + **Automatic atomic deployments are deprecated.** The setting still exists in your Vercel + integration settings, is labelled Deprecated, and keeps working — nothing is being switched off + for you. New connections have it off by default. Version skew protection is the supported + mechanism. + + +[Atomic deployments](/vercel-integration#atomic-deployments) solved the same problem by gating your Vercel deployment on the Trigger.dev build, then spawning a **second** Vercel deployment with `TRIGGER_VERSION` baked in and promoting it. + +Version skew protection replaces it and is strictly less invasive: + +| | Automatic atomic deployments | Version skew protection | +| --- | --- | --- | +| Vercel deployments per release | Two — the original, then a redeploy | One | +| Blocks your Vercel deployment | Yes, until the task build finishes | Never | +| `Auto-assign Custom Production Domains` | Must be disabled | Untouched | +| Environments covered | Production only | Production, staging **and** preview | +| Configuration | A setting on the production environment | None — the id is the contract | +| Runs triggered before the build lands | Run on the previous version | Wait, then run on the right version | + +### Migrating + +1. Make sure your app and your deploys are on **v4.5.12 or later** — the release that introduced external deployment ids. The CLI (`trigger.dev`) and the SDK (`@trigger.dev/sdk`) version together, so `npx trigger.dev@latest update` moves both; see the [v4.5.12 release notes](https://github.com/triggerdotdev/trigger.dev/releases/tag/v4.5.12). +2. Confirm skew protection is working — deploy, then check that runs triggered by the new release are pinned to the new version. +3. Turn **Atomic deployments** off in your project's Vercel settings. +4. **Remove the `TRIGGER_VERSION` variable** from your Vercel project. Until you do, it outranks the external deployment id and keeps governing. +5. Decide who promotes. Under atomic deployments Trigger.dev promoted for you; without it, either re-enable `Auto-assign Custom Production Domains` in Vercel or promote deliberately from your own pipeline. + +Both mechanisms can run at the same time without conflict while the variable still names a live version — `TRIGGER_VERSION` simply keeps winning — so there is no broken intermediate state and no need to do all of this at once. + + + **Step 4 is not optional, and don't do it before step 2.** While `TRIGGER_VERSION` names a version + that exists in the environment being triggered, it simply keeps winning — safe, and why the two + mechanisms coexist. The moment it names a version that environment doesn't have, **every trigger + fails outright** with a `422`, and the external deployment id it suppresses can't catch it. + + + + If you want your Vercel deployment to stay **gated** on the Trigger.dev build, atomic deployments + remain the way to do that. Version skew protection never blocks a deployment; it makes blocking + unnecessary by making runs wait instead. + + +## Related + +- [Deployment overview](/deployment/overview) — versions, current version and version locking +- [Deploy CLI command](/cli-deploy-commands) — every deploy flag +- [Vercel integration](/vercel-integration) +- [Preview branches](/deployment/preview-branches) +- [Atomic deploys](/deployment/atomic-deployment) (deprecated for Vercel) diff --git a/docs/docs.json b/docs/docs.json index ed6056f373f..98c3dc46322 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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 } ] } diff --git a/docs/github-actions.mdx b/docs/github-actions.mdx index 3f1c145926f..1bb6b316c30 100644 --- a/docs/github-actions.mdx +++ b/docs/github-actions.mdx @@ -11,11 +11,11 @@ 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. The deploy step will fail if any version mismatches are detected. Please see the [version - pinning](/github-actions#version-pinning) section for more details. + pinning](/github-actions#cli-version-pinning) section for more details. @@ -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 }} ``` 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= +``` + +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. + + + 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). + + ## 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,11 +133,15 @@ 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.event.pull_request.head.sha }} env: TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }} ``` +On `pull_request`, `github.sha` is the merge commit GitHub creates for the PR, not the commit your +app was built from. Use `github.event.pull_request.head.sha` so the id matches the one your preview +deployment sends. + **Include `closed`** in the `pull_request.types` list. Without it, preview branches won't be archived when PRs are merged or closed, and you may hit the limit on active preview branches. See [Preview branches](/deployment/preview-branches#preview-branches-with-github-actions-recommended) for more details. diff --git a/docs/github-integration.mdx b/docs/github-integration.mdx index f4becb0b4ff..ffbc91f4321 100644 --- a/docs/github-integration.mdx +++ b/docs/github-integration.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). +## 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= +``` + +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. diff --git a/docs/snippets/cli-commands-deploy.mdx b/docs/snippets/cli-commands-deploy.mdx index cc5e6120a8a..ce8125836aa 100644 --- a/docs/snippets/cli-commands-deploy.mdx +++ b/docs/snippets/cli-commands-deploy.mdx @@ -77,6 +77,27 @@ npx trigger.dev@latest deploy [path] Turn off syncing environment variables with the Trigger.dev instance. + + 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. + + + + 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`. + + Force building the deployment image locally using your local Docker. This is automatic when self-hosting. diff --git a/docs/vercel-integration.mdx b/docs/vercel-integration.mdx index 3c2cc1b9665..60574da8cf2 100644 --- a/docs/vercel-integration.mdx +++ b/docs/vercel-integration.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: - 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. @@ -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. + + + 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. + + +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 + + **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. + + 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. 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. -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) diff --git a/docs/versioning.mdx b/docs/versioning.mdx index 743e7c47485..6171c73db37 100644 --- a/docs/versioning.mdx +++ b/docs/versioning.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, once your app sends the id it was deployed with. + ## 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.