Skip to content

chore(docs): improve version pinning advise to use installed trigger.dev CLI #2466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 2, 2025
Merged

chore(docs): improve version pinning advise to use installed trigger.dev CLI #2466

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions docs/github-actions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,13 +102,16 @@ If you already have a GitHub action file, you can just add the final step "🚀
## CLI Version pinning

The CLI and `@trigger.dev/*` package versions need to be in sync with the `trigger.dev` CLI, otherwise there will be errors and unpredictable behavior. Hence, the `deploy` command will automatically fail during CI on any version mismatches.
Tip: add the deploy command to your `package.json` file to keep versions managed in the same place. For example:
Tip: add the `trigger.dev` CLI to your `devDependencies` and the deploy command to your `package.json` file to keep versions managed in the same place. For example:

```json
{
"scripts": {
"deploy:trigger-prod": "npx trigger.dev@3.0.0 deploy",
"deploy:trigger": "npx trigger.dev@3.0.0 deploy --env staging"
"deploy:trigger-prod": "trigger deploy",
"deploy:trigger": "trigger deploy --env staging"
},
"devDependencies": {
"trigger.dev": "4.0.2"
}
Comment on lines +110 to 115
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Also pin your @trigger.dev/* packages to the same version as the CLI.

The deploy step will fail if app packages and CLI differ. Expand the example to make this explicit.

 {
   "scripts": {
     "deploy:trigger-prod": "trigger deploy",
     "deploy:trigger": "trigger deploy --env staging"
   },
-  "devDependencies": {
-    "trigger.dev": "4.0.2"
-  }
+  "devDependencies": {
+    "trigger.dev": "4.0.2"
+  },
+  "dependencies": {
+    "@trigger.dev/sdk": "4.0.2"
+  }
 }

Optionally add install commands right below the snippet:

npm i -D trigger.dev@4.0.2 && npm i @trigger.dev/sdk@4.0.2
🤖 Prompt for AI Agents 
In docs/github-actions.mdx around lines 110 to 115, the example shows only the
trigger.dev CLI pinned but doesn’t instruct to pin @trigger.dev/* packages to
the same version; update the example and accompanying text to explicitly state
that all @trigger.dev packages must match the CLI version to avoid deploy
failures, expand the shown package.json snippet to include a pinned @trigger.dev
SDK version matching trigger.dev@4.0.2, and add the optional install command
line shown in the comment directly below the snippet (e.g., an npm i -D
trigger.dev@4.0.2 && npm i @trigger.dev/sdk@4.0.2) so users can easily apply the
pins.

}
```
Expand All @@ -134,9 +137,7 @@ When self-hosting, you will have to take a few additional steps:
- Add your registry credentials to the GitHub secrets.
- Use the `--self-hosted` and `--push` flags when deploying.

<Tip>
If you're self-hosting v4, the `--self-hosted` and `--push` flags are **NOT** needed.
</Tip>
<Tip>If you're self-hosting v4, the `--self-hosted` and `--push` flags are **NOT** needed.</Tip>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Contradiction: Tip says flags NOT needed on v4, but example still uses them.

Self-hosted v4 should not pass --self-hosted/--push per the Tip. Align the example and also use the local CLI via script.

       - name: 🚀 Deploy Trigger.dev
         env:
           TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
           # required when self-hosting
           TRIGGER_API_URL: ${{ secrets.TRIGGER_API_URL }}
-        # deploy with additional flags
-        run: |
-          npx trigger.dev@latest deploy --self-hosted --push
+        # deploy using the pinned local CLI (no extra flags on v4)
+        run: |
+          npm run deploy:trigger

Also applies to: 182-190

🤖 Prompt for AI Agents 
docs/github-actions.mdx lines 140 and 182-190: The Tip states that for
self-hosted v4 the --self-hosted and --push flags are NOT needed, but the
example still uses them and doesn't demonstrate using the local CLI via script;
update the example(s) to remove --self-hosted and --push when documenting
self-hosted v4 and replace the direct CLI invocation with a call to the local
CLI script (e.g., use the repository's ./scripts/cli or npm script) so the
example aligns with the Tip and shows the recommended local CLI usage.


Other than that, your GitHub action file will look very similar to the one above:

Expand Down