docs: improve deployment docs and add atomic deploy guide #1748
Conversation
|
|
Warning Rate limit exceeded@ericallam has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 21 minutes and 43 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughThis pull request updates various documentation files related to CLI commands and deployment processes. The changes include revisions to titles, descriptions, and formatting in existing docs, along with the introduction of new documentation files covering the CLI promote command, atomic deployment processes, and an overall deployment overview. Adjustments in the JSON docs configuration and command snippet details—such as replacing a build platform option with a skip promotion flag—are also included. Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer
participant GA as GitHub Actions
participant CLI as Trigger.dev CLI
participant Vercel as Vercel
participant Wait as VercelWait
Dev->>GA: Trigger deployment workflow
GA->>CLI: Execute deploy command (--skip-promotion)
CLI->>Trigger.dev: Deploy tasks without promoting
GA->>Vercel: Start Vercel deployment
Vercel-->>GA: Return deployment status
GA->>Wait: Monitor Vercel deployment
Wait-->>GA: Signal deployment complete
GA->>CLI: Trigger promotion step
CLI->>Trigger.dev: Promote deployed version
Suggested reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
ericallam
force-pushed
the
vercel-atomic-deploys
branch
from
435d24a to
fbcb7ad
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/deployment/overview.mdx (2)
134-142: Skipping Promotion Section: Minor Grammatical Fix Needed
The section explains the use of the--skip-promotionflag effectively. However, the sentence “…the new version is automatically promoted be the current version…” contains a grammatical error. Consider revising it to:
- “...the new version is automatically promoted to be the current version…”
This small change will improve clarity.🧰 Tools
🪛 LanguageTool
[uncategorized] ~136-~136: Possible missing preposition found.
Context: ...e new version is automatically promoted be the current version. If you want to ski...(AI_HYDRA_LEO_MISSING_TO)
[uncategorized] ~142-~142: Possible missing comma found.
Context: ...his will create a new deployment version but not promote it to the current version: ...(AI_HYDRA_LEO_MISSING_COMMA)
189-234: Troubleshooting Section: Comprehensive and User-Friendly
The troubleshooting section covers a range of scenarios—from dry runs to issues with native code bundles—and provides actionable advice. A quick copy-edit pass (especially for comma usage and minor wordiness) could further polish this section, though the content is already very useful.🧰 Tools
🪛 LanguageTool
[uncategorized] ~203-~203: Possible missing comma found.
Context: ... ``` The dry run will output the build directory where you can inspect the built tasks a...(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~207-~207: The word ‘deploy’ is a verb. Did you mean the noun “deployment” (= release, placement)?
Context: ...gging. ### Debug logs You can run the deploy command with--log-level debugat the...(PREPOSITION_VERB)
[grammar] ~207-~207: The word ‘deploy’ is a verb. Did you mean the noun “deployment” (= release, placement)?
Context: ...rint out a lot of information about the deploy. If you can't figure out the problem fr...(PREPOSITION_VERB)
[typographical] ~207-~207: It seems that a comma is missing.
Context: ...t the problem from the information below please join [our Discord](https://trigger.dev/...(IF_PLEASE_COMMA)
[uncategorized] ~213-~213: Possible missing comma found.
Context: ... what's going wrong. Do NOT share these publicly as the verbose logs might reveal privat...(AI_HYDRA_LEO_MISSING_COMMA)
[typographical] ~216-~216: Consider adding a comma after ‘Usually’ for more clarity.
Context: ...####Deployment encountered an errorUsually there will be some useful guidance belo...(RB_LY_COMMA)
[typographical] ~217-~217: Consider adding a comma.
Context: ... you can't figure out what's going wrong then join [our Discord](https://trigger.dev/...(IF_THEN_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
docs/deployment/api-key.pngis excluded by!**/*.pngdocs/deployment/auto-assign-production-domains.pngis excluded by!**/*.pngdocs/deployment/my-first-deployment.pngis excluded by!**/*.pngdocs/deployment/promote-button.pngis excluded by!**/*.pngdocs/deployment/skip-promotion.pngis excluded by!**/*.pngdocs/deployment/staging-deploy.pngis excluded by!**/*.png
📒 Files selected for processing (8)
docs/cli-deploy-commands.mdx(1 hunks)docs/cli-promote-commands.mdx(1 hunks)docs/deployment/atomic-deployment.mdx(1 hunks)docs/deployment/overview.mdx(1 hunks)docs/docs.json(8 hunks)docs/github-actions.mdx(2 hunks)docs/snippets/cli-commands-deploy.mdx(3 hunks)docs/snippets/cli-commands-promote.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- docs/cli-promote-commands.mdx
- docs/github-actions.mdx
- docs/docs.json
🧰 Additional context used
🪛 LanguageTool
docs/deployment/overview.mdx
[style] ~7-~7: For conciseness, consider replacing this expression with an adverb.
Context: ...loy your tasks. The only way to do this at the moment is through the [deploy CLI command](/cl...
(AT_THE_MOMENT)
[style] ~70-~70: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...loyed your tasks, you can trigger tasks exactly the same way you did locally, but with the "PROD...
(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)
[style] ~92-~92: This phrase is redundant. Consider writing “point” or “time”.
Context: ...s a snapshot of your tasks at a certain point in time. This ensures that tasks are not affect...
(MOMENT_IN_TIME)
[style] ~117-~117: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...{ version: "20250228.1" }); ``` If you want to set a global version to run all tasks a...
(REP_WANT_TO_VB)
[uncategorized] ~125-~125: Possible missing comma found.
Context: ... parent task is expecting. If you don't wait then version locking doesn't apply. | ...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~136-~136: Possible missing preposition found.
Context: ...e new version is automatically promoted be the current version. If you want to ski...
(AI_HYDRA_LEO_MISSING_TO)
[uncategorized] ~142-~142: Possible missing comma found.
Context: ...his will create a new deployment version but not promote it to the current version: ...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~146-~146: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...thout affecting new task runs. When you want to promote the version, you can do so from...
(REP_WANT_TO_VB)
[uncategorized] ~203-~203: Possible missing comma found.
Context: ... ``` The dry run will output the build directory where you can inspect the built tasks a...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~207-~207: The word ‘deploy’ is a verb. Did you mean the noun “deployment” (= release, placement)?
Context: ...gging. ### Debug logs You can run the deploy command with --log-level debug at the...
(PREPOSITION_VERB)
[grammar] ~207-~207: The word ‘deploy’ is a verb. Did you mean the noun “deployment” (= release, placement)?
Context: ...rint out a lot of information about the deploy. If you can't figure out the problem fr...
(PREPOSITION_VERB)
[typographical] ~207-~207: It seems that a comma is missing.
Context: ...t the problem from the information below please join [our Discord](https://trigger.dev/...
(IF_PLEASE_COMMA)
[uncategorized] ~213-~213: Possible missing comma found.
Context: ... what's going wrong. Do NOT share these publicly as the verbose logs might reveal privat...
(AI_HYDRA_LEO_MISSING_COMMA)
[typographical] ~216-~216: Consider adding a comma after ‘Usually’ for more clarity.
Context: ...#### Deployment encountered an error Usually there will be some useful guidance belo...
(RB_LY_COMMA)
[typographical] ~217-~217: Consider adding a comma.
Context: ... you can't figure out what's going wrong then join [our Discord](https://trigger.dev/...
(IF_THEN_COMMA)
docs/deployment/atomic-deployment.mdx
[uncategorized] ~77-~77: Loose punctuation mark.
Context: ...ub repository: - TRIGGER_ACCESS_TOKEN: Your Trigger.dev personal access token....
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~78-~78: Loose punctuation mark.
Context: ...actions) to learn more. - VERCEL_TOKEN: Your Vercel personal access token. You ...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~82-~82: Possible wrong verb form detected. Did you mean “been” or “being”?
Context: ... w/Vercel Github integration If you're are using Vercel, chances are you are using...
(BE_WITH_WRONG_VERB_FORM)
[uncategorized] ~159-~159: Loose punctuation mark.
Context: ...ub repository: - TRIGGER_ACCESS_TOKEN: Your Trigger.dev personal access token....
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~160-~160: Loose punctuation mark.
Context: ...actions) to learn more. - VERCEL_TOKEN: Your Vercel personal access token. You ...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~161-~161: Loose punctuation mark.
Context: ... account settings. - VERCEL_PROJECT_ID: Your Vercel project ID. You can find th...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~162-~162: Loose punctuation mark.
Context: ... project settings. - VERCEL_SCOPE_NAME: Your Vercel team slug. Checkout our [e...
(UNLIKELY_OPENING_PUNCTUATION)
[grammar] ~163-~163: This sentence should probably be started with a verb instead of the noun ‘Checkout’. If not, consider inserting a comma for better clarity.
Context: ...EL_SCOPE_NAME`: Your Vercel team slug. Checkout our [example repo](https://github.com/e...
(SENT_START_NN_DT)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (38)
docs/snippets/cli-commands-promote.mdx (5)
1-2: Import & File Setup: Consistent and Clear
The import ofCommonOptionsfrom the snippets folder is clear and follows our absolute path style.
3-4: Command Introduction Is Clear
The introductory text “Run the command like this:” provides a clear call-to-action for the reader.
5-20: CodeBlock & Example Commands: Well Structured
The use of a<CodeGroup>to present examples for npm, pnpm, and yarn is well executed. The command snippet syntax (e.g.npx trigger.dev@latest promote [version]) is clear and consistent across examples.
21-29: Arguments Section: Informative and Consistent
The “## Arguments” section clearly reinforces the command usage by repeating the command and further documents the[version]argument via the<ParamField>component.
31-35: Common Options Import: Good Reuse
Rendering the<CommonOptions />component further standardizes documentation across CLI commands.docs/cli-deploy-commands.mdx (2)
2-4: Frontmatter Update: Improved Clarity
The updated title “CLI deploy command” and the revised description make the file’s purpose very clear. Great job focusing the language on a specific command rather than abstract options.
7-9: Component Import and Usage: Correct and Consistent
The import ofCliDeployCommandsand its insertion into the document are concise and consistent with our MDX practices.docs/snippets/cli-commands-deploy.mdx (9)
1-6: Imports & Initial Setup: Clean and Consistent
The series of import statements at the top of the file are clear and use a consistent absolute path style. No issues detected.
8-24: Deploy Command Examples: Excellent Usage and Layout
The examples for running the deploy command with npm, pnpm, and yarn are well presented inside a<CodeGroup>. This makes it accessible for users regardless of their preferred package manager.
26-29: Warning Block: Helpful Guidance
The warning message effectively alerts users about potential CI failures due to version mismatches. The reference to the dev command is useful.
31-38: Step-by-Step Deployment Explanation: Clear and Sequential
Listing the deploy steps (“Optionally updates packages…”, “Compiles and bundles the code…”, etc.) helps set clear expectations.🧰 Tools
🪛 LanguageTool
[grammar] ~38-~38: The word “setup” is a noun. The verb is spelled with a space.
Context: ...onment (prod by default). You can also setup GitHub Actions to de...(NOUN_VERB_CONFUSION)
40-46: Arguments Example: Reinforcement Through Repetition
Repeating the deploy command in the “## Arguments” section further reinforces the expected usage. The integration of<ProjectPathArg />is also appropriate.
48-64: Options Section (Part 1): Comprehensive Parameter Documentation
The sequential presentation of configuration options (ConfigFile, ProjectRef, EnvFile, SkipUpdateCheck) is clear and maintains consistency with our documentation style.
66-68: New "Skip promotion" Parameter: Essential Update
The added<ParamField>for “Skip promotion” (with type--skip-promotion) directly addresses the updated deployment flow. This change accurately reflects the migration away from the old “build platform” parameter.
70-79: Options Section (Part 2): Clear and Informative
The rest of the options, including “Skip syncing env vars” and the common options for self-hosting, are well documented. The structure is logical and user-friendly.
80-129: Examples Section: Detailed and Actionable
The example provided for pushing to Docker Hub in a self-hosted setup is detailed and offers real-world context. The command formatting and option usage are clear.docs/deployment/atomic-deployment.mdx (5)
1-5: Frontmatter Definition: Clear and Descriptive
The frontmatter (title, sidebarTitle, description) is well defined and sets the reader’s expectations for atomic deploys.
7-12: Introduction and "How it works" Section: Informative Overview
The opening paragraphs provide a concise explanation of the concept of atomic deploys, detailing the synchronization of task versions with application deployments.
13-16: Step-by-Step Process: Clear Instruction Flow
The bullet-pointed steps effectively break down the atomic deployment process. This clarity improves user understanding of the process.
64-72: Workflow Explanation: Context Enhancer
The bullet points that follow the workflow effectively explain the steps taken in the CI process. This breakdown aids in understanding complex deployment integrations.
73-172: Vercel & GitHub Actions Second Workflow Example: Comprehensive and Informative
The second GitHub Actions workflow example, which includes a verification step withericallam/vercel-wait, adds depth to the documentation. It shows a real-world scenario where atomic deploys are integrated with Vercel promotion.🧰 Tools
🪛 LanguageTool
[uncategorized] ~77-~77: Loose punctuation mark.
Context: ...ub repository: -TRIGGER_ACCESS_TOKEN: Your Trigger.dev personal access token....(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~78-~78: Loose punctuation mark.
Context: ...actions) to learn more. -VERCEL_TOKEN: Your Vercel personal access token. You ...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~82-~82: Possible wrong verb form detected. Did you mean “been” or “being”?
Context: ... w/Vercel Github integration If you're are using Vercel, chances are you are using...(BE_WITH_WRONG_VERB_FORM)
[uncategorized] ~159-~159: Loose punctuation mark.
Context: ...ub repository: -TRIGGER_ACCESS_TOKEN: Your Trigger.dev personal access token....(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~160-~160: Loose punctuation mark.
Context: ...actions) to learn more. -VERCEL_TOKEN: Your Vercel personal access token. You ...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~161-~161: Loose punctuation mark.
Context: ... account settings. -VERCEL_PROJECT_ID: Your Vercel project ID. You can find th...(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~162-~162: Loose punctuation mark.
Context: ... project settings. -VERCEL_SCOPE_NAME: Your Vercel team slug. Checkout our [e...(UNLIKELY_OPENING_PUNCTUATION)
[grammar] ~163-~163: This sentence should probably be started with a verb instead of the noun ‘Checkout’. If not, consider inserting a comma for better clarity.
Context: ...EL_SCOPE_NAME`: Your Vercel team slug. Checkout our [example repo](https://github.com/e...(SENT_START_NN_DT)
docs/deployment/overview.mdx (17)
1-5: Frontmatter & Metadata: Sets the Stage
The frontmatter clearly conveys the purpose of this overview document. The title, sidebarTitle, and description are concise and informative.
7-9: Introduction Paragraph: Context and Purpose
The opening paragraph immediately establishes the importance of deploying tasks for production workloads, providing good context for newcomers.🧰 Tools
🪛 LanguageTool
[style] ~7-~7: For conciseness, consider replacing this expression with an adverb.
Context: ...loy your tasks. The only way to do this at the moment is through the [deploy CLI command](/cl...(AT_THE_MOMENT)
9-23: CLI Command Examples: Clear and Accessible
The code blocks demonstrating how to deploy using npm, pnpm, and yarn are straightforward and provide immediate value to the reader.
25-29: Deploying 101 Section: Step-by-Step Instruction
The “Deploying 101” section outlines the deployment process in a logical and sequential manner. This clarity helps bridge the gap for users transitioning from local to production deployments.
30-36: Login Instructions: Essential Preparation
Providing the login command and explanation ensures users understand the prerequisite of authentication. This section is succinct and clear.
37-41: Deployment Execution: Straightforward and Actionable
The command to deploy tasks is clearly presented. The expected output (success message) is a useful inclusion for validating the deployment.
43-57: Success Message Example: Clear Feedback for Users
The success message snippet (including version information and a summary of deployed tasks) gives users confidence that the deploy process was successful.
59-66: Dashboard & Note on Process Timing: Helpful & Realistic
The note explaining that deployments can take a few seconds to minutes is practical; pairing it with a dashboard image reference reinforces the documentation’s usability.
68-76: Triggering Deployed Tasks: Easy-to-Follow Instructions
The section on triggering tasks post-deployment, including setting environment variables and referencing the “PROD” API key, is practical and well laid out.🧰 Tools
🪛 LanguageTool
[style] ~70-~70: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...loyed your tasks, you can trigger tasks exactly the same way you did locally, but with the "PROD...(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)
76-86: Environment Variables & Task Triggering Code: Clear Example
Both the.envsnippet and the TypeScript example for triggering a task demonstrate proper usage and help reduce potential integration errors.
90-100: Versions Explanation: Detailed and Reassuring
The explanation of versioning—why a snapshot is taken at each deploy and how version locking works—is thorough and informative.🧰 Tools
🪛 LanguageTool
[style] ~92-~92: This phrase is redundant. Consider writing “point” or “time”.
Context: ...s a snapshot of your tasks at a certain point in time. This ensures that tasks are not affect...(MOMENT_IN_TIME)
101-107: Version Locking & Global Version Setting: Critical Details
The guidance on using theversionparameter and theTRIGGER_VERSIONenvironment variable is clear. This information is crucial for advanced use cases.
109-133: Child Tasks and Auto-Version Locking: Technical Clarity
The inclusion of the table that clarifies behavior for child task versions is very helpful. It succinctly illustrates a potentially confusing topic.🧰 Tools
🪛 LanguageTool
[style] ~117-~117: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...{ version: "20250228.1" }); ``` If you want to set a global version to run all tasks a...(REP_WANT_TO_VB)
[uncategorized] ~125-~125: Possible missing comma found.
Context: ... parent task is expecting. If you don't wait then version locking doesn't apply. | ...(AI_HYDRA_LEO_MISSING_COMMA)
142-146: Code Example for Skipping Promotion: Clear and Concise
The command snippet usingnpx trigger.dev deploy --skip-promotionaccurately reflects the updated process.🧰 Tools
🪛 LanguageTool
[uncategorized] ~142-~142: Possible missing comma found.
Context: ...his will create a new deployment version but not promote it to the current version: ...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~146-~146: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...thout affecting new task runs. When you want to promote the version, you can do so from...(REP_WANT_TO_VB)
146-156: Additional Guidance & Linking: Effective Cross-Referencing
Linking to the atomic deployment guide (“Atomic deployment”) encourages further reading and improves navigability between related documents.🧰 Tools
🪛 LanguageTool
[style] ~146-~146: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...thout affecting new task runs. When you want to promote the version, you can do so from...(REP_WANT_TO_VB)
158-174: Staging Deploys: Environment-Specific Instructions Well Articulated
The section on staging deployments, including the use of the--envflag and setting appropriate API keys, is precise. The accompanying image reference adds clarity.
183-189: Environment Variables Section: Helpful Resource Links Provided
Details on managing environment variables, combined with references to additional guides, ensure that users have the resources needed if issues arise.
Summary by CodeRabbit