docs: task version skew protection, --external-id, and the atomic deployments deprecation - #4742
docs: task version skew protection, --external-id, and the atomic deployments deprecation#47420ski wants to merge 1 commit into
Conversation
|
WalkthroughThe 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 The documentation adds version-skew protection guidance and CLI behavior, but a few details could mislead users about concurrent deployments, accepted configuration values, and over-length external IDs. The PR is mergeable with explicit owner follow-up to clarify these bounded documentation risks. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
…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).
ba90165 to
10fcdc2
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/deployment/version-skew-protection.mdx (1)
73-73: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winState that
deployrejects over-length IDs. The CLI trims--external-id, then fails with--external-id must be at most 128 characters.It does not drop the value.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: fa23f7d1-cbab-41bd-9fd2-a40919b5d3f4
📒 Files selected for processing (3)
docs/deployment/version-skew-protection.mdxdocs/github-actions.mdxdocs/versioning.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/versioning.mdx
Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: All PR Checks
🧰 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/sdkin 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/github-actions.mdxdocs/deployment/version-skew-protection.mdx
**/*
📄 CodeRabbit inference engine (AGENTS.md)
**/*: Add crumbs as you write code — not just when debugging. Mark lines with
//@Crumbsor wrap blocks in `// `#region` `@crumbs. They stay on the
branch throughout development and are stripped byagentcrumbs strip
before merge.
Do not invent new namespaces — pick from this table or ask first.
Do not flag//@Crumbsmarkers, `#region `@crumbsblocks, 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/github-actions.mdxdocs/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/github-actions.mdx
[uncategorized] ~88-~88: The official name of this software platform is spelled with a capital “H”.
Context: ...s to the deployment you just built The --external-id ${{ github.sha }} above tags the deployment with ...
(GITHUB)
[uncategorized] ~104-~104: The official name of this software platform is spelled with a capital “H”.
Context: ...d a paths: filter to this workflow, ${{ github.sha }} stops being a safe id: commits ...
(GITHUB)
[uncategorized] ~141-~141: The official name of this software platform is spelled with a capital “H”.
Context: ...ACCESS_TOKEN }} ``` On pull_request, `github.sha` is the merge commit GitHub creates...
(GITHUB)
[uncategorized] ~142-~142: The official name of this software platform is spelled with a capital “H”.
Context: ...the commit your app was built from. Use github.event.pull_request.head.sha so the id ...
(GITHUB)
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] ~107-~107: ‘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] ~107-~107: 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] ~141-~141: ‘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] ~147-~147: 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] ~307-~307: ‘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] ~341-~341: 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 (2)
docs/deployment/version-skew-protection.mdx (1)
1-68: LGTM!Also applies to: 99-138, 148-235, 248-430
docs/github-actions.mdx (1)
14-14: LGTM!Also applies to: 50-50, 79-109, 136-144
| | 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. Two runs genuinely in flight at the same moment both see "nothing deployed yet", so both build; the higher version wins. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Resolve the contradiction about two concurrent deploys for one id.
The table at Line 82 states that a deploy against an id that is already building fails with an error. Line 98 states that two runs in flight at the same moment both build. Both cannot be the general rule. The error path applies as soon as the first deploy has registered a building deployment; the "both build" path applies only in the narrow window before that registration.
State the window explicitly so the two rules do not conflict.
📝 Proposed wording
-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. Two runs genuinely in flight at the same moment both see "nothing deployed yet", so both build; the higher version wins.
+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.
+
+If the second run starts while the first is still building, it hits the **Building** row above and errors. Only in the brief window before the first deploy registers its build do both runs see "nothing deployed yet"; then both build and the higher version wins.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | 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. Two runs genuinely in flight at the same moment both see "nothing deployed yet", so both build; the higher version wins. | |
| | 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: | |
| 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 | ||
| ``` | ||
|
|
||
| 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. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the parsing of the automatic skew protection gate variable.
set -euo pipefail
rg -n -C 10 'AUTOMATIC_SKEW_PROTECTION_ENV_VAR|TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION' packages apps internal-packages --type=tsRepository: triggerdotdev/trigger.dev
Length of output: 13071
Document the normalized accepted values for TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION. The parser trims whitespace and compares case-insensitively, so 1, true, TRUE, and 1 enable discovery. Update this section and the opt-out instructions at line 374.
🧰 Tools
🪛 LanguageTool
[style] ~141-~141: ‘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] ~147-~147: 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)
1 participant
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).