docs: task version skew protection, --external-id, and the atomic deployments deprecation by 0ski · Pull Request #4742 · triggerdotdev/trigger.dev

0ski · 2026-08-20T18:51:40Z

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).

changeset-bot · 2026-08-20T18:51:46Z

⚠️ No Changeset found

Latest commit: ad60814

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2026-08-20T18:52:10Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 08efec25-2a40-4abc-b85d-702eece6910e

📥 Commits

Reviewing files that changed from the base of the PR and between a87c128 and ad60814.

📒 Files selected for processing (1)

docs/deployment/version-skew-protection.mdx

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

GitHub Check: code-quality / code-quality
GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (2)

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/CLAUDE.md)

docs/**/*.mdx: MDX documentation pages must include frontmatter with title (required), description (required), and sidebarTitle (optional) in YAML format
Use Mintlify components for structured content: , , , , , , /, /
Always import from @trigger.dev/sdk in code examples (never from @trigger.dev/sdk/v3)
Code examples must be complete and runnable where possible
Use language tags in code fences: typescript, bash, json

Files:

docs/deployment/version-skew-protection.mdx

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Add crumbs as you write code — not just when debugging. Mark lines with
// @Crumbs or wrap blocks in `// `#region` `@crumbs. They stay on the
branch throughout development and are stripped by agentcrumbs strip
before merge.
Do not invent new namespaces — pick from this table or ask first.
Do not flag // @Crumbs markers, `#region `@crumbs blocks, or agentcrumbs
imports in reviews. These are temporary debug instrumentation stripped
before merge. Data logged in crumbs (IDs, names, values) never reaches
production.

Files:

docs/deployment/version-skew-protection.mdx

🧠 Learnings (1)

📚 Learning: 2026-04-30T20:30:29.458Z

Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3226
File: docs/ai-chat/quick-start.mdx:13-13
Timestamp: 2026-04-30T20:30:29.458Z
Learning: In this repo’s documentation MDX files (`docs/**/*.mdx`), use `ts` and `tsx` (not `typescript`) as the code-fence language tags for TypeScript/TSX snippets. Do not flag `ts`/`tsx` code-fence language tags as incorrect in any docs MDX file, since this is the site-wide Mintlify-compatible convention.

Applied to files:

docs/deployment/version-skew-protection.mdx

🪛 LanguageTool

docs/deployment/version-skew-protection.mdx

[style] ~6-~6: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...d separately, so they are never live at exactly the same instant. In the window between them, an...

(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)

[style] ~28-~28: Consider an alternative for the overused word “exactly”.
Context: ...s honoured. If it doesn't, behaviour is exactly what it is today. This works identical...

(EXACTLY_PRECISELY)

[style] ~109-~109: ‘with respect to’ might be wordy. Consider a shorter alternative.
Context: ... already has one. It is non-destructive with respect to deployments that already succeeded ...

(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)

[style] ~109-~109: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ve two live builds racing to define it. It requires --external-id: on its own th...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

[style] ~143-~143: ‘whether or not’ might be wordy. Consider a shorter alternative.
Context: ...quires one, because that value is there whether or not anyone asked for this feature. ```bash...

(EN_WORDINESS_PREMIUM_WHETHER_OR_NOT)

[grammar] ~149-~149: Ensure spelling is correct
Context: ...atic discovery off. The variable gates discovery only; an id you set explicitly is alwa...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

[style] ~309-~309: ‘by accident’ might be wordy. Consider a shorter alternative.
Context: ...damaging one, and the easiest to create by accident. If your deploy workflow is filtered on...

(EN_WORDINESS_PREMIUM_BY_ACCIDENT)

[style] ~343-~343: To elevate your writing, try using more formal phrasing here.
Context: ...atomic-deployment) safe: the legacy pin keeps governing until you remove the variable. - An ext...

(CONTINUE_TO_VB)

🔇 Additional comments (1)

docs/deployment/version-skew-protection.mdx (1)

1-430: LGTM!

Walkthrough

The documentation adds version skew protection guidance and defines external deployment ID behavior, discovery, waiting, expiry, idempotency, and version precedence. GitHub Actions, GitHub integration, and Vercel integration documentation now describe commit-based deployment matching and configuration. Deployment guides add CLI options and migration guidance from atomic deployments. Documentation navigation includes the new page and a permanent redirect.

Merge Risk: 🔵 Low · up to ad608

The documentation changes explain deployment version-skew protection, but the Vercel guidance still presents conflicting rules about whether an opt-out setting is overwritten. This could mislead users configuring deployments, so the PR is mergeable with explicit owner follow-up to clarify that behavior.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the documentation changes but omits the required issue closure, checklist, testing, changelog, and screenshots sections.	Complete the repository template by adding the issue closure, checklist, testing steps, changelog entry, and screenshots section.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation changes: version skew protection, deployment identifiers, and atomic deployment deprecation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch oskar/feat-skew-protection-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

pkg-pr-new · 2026-08-21T13:54:11Z

Open in StackBlitz

@trigger.dev/build

npm i https://pkg.pr.new/@trigger.dev/build@656bb63

trigger.dev

npm i https://pkg.pr.new/trigger.dev@656bb63

@trigger.dev/core

npm i https://pkg.pr.new/@trigger.dev/core@656bb63

@trigger.dev/python

npm i https://pkg.pr.new/@trigger.dev/python@656bb63

@trigger.dev/react-hooks

npm i https://pkg.pr.new/@trigger.dev/react-hooks@656bb63

@trigger.dev/redis-worker

npm i https://pkg.pr.new/@trigger.dev/redis-worker@656bb63

@trigger.dev/rsc

npm i https://pkg.pr.new/@trigger.dev/rsc@656bb63

@trigger.dev/schema-to-json

npm i https://pkg.pr.new/@trigger.dev/schema-to-json@656bb63

@trigger.dev/sdk

npm i https://pkg.pr.new/@trigger.dev/sdk@656bb63

commit: 656bb63

…loyments 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).