docs: fix self-hosting section in deploy docs

[nicktrn]

Fixes #2835

There were still some flags in here we removed, deploying is a lot simpler now for self-hosters.

Also updates the github actions guide.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0fe9dc0

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]

Walkthrough

This PR updates self-hosting documentation across two files. docs/github-actions.mdx simplifies the self-hosting setup instructions by removing references to v4 flags, eliminating multi-step Docker comments, and shortening the deploy command from npx trigger.dev@latest deploy --self-hosted --push to npx trigger.dev@latest deploy. docs/snippets/cli-commands-deploy.mdx adds a new --local-build parameter, removes multiple self-hosting-specific parameters, and consolidates the self-hosting guidance to indicate that local builds are the default behavior when self-hosting. Both files are updated to require setting TRIGGER_ACCESS_TOKEN and TRIGGER_API_URL environment variables for CI/CD environments.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Pre-merge checks

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description identifies the linked issue and explains the purpose (removing deprecated flags and simplifying self-hosted deployment), but lacks detailed testing information required by the template.	Add a Testing section describing the steps taken to verify the documentation changes, and provide a more detailed Changelog entry following the template structure.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely describes the main change: updating the self-hosting section in deploy documentation with simplified guidance.
Linked Issues check	✅ Passed	The PR addresses the core requirement from issue #2835 by removing deprecated CLI flags and simplifying self-hosted deployment documentation with current guidance.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation updates for self-hosting deploy instructions and GitHub Actions guide, directly addressing the linked issue requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between edf5b14 and 0fe9dc0.

📒 Files selected for processing (2)

• docs/github-actions.mdx
• docs/snippets/cli-commands-deploy.mdx

🧰 Additional context used

🧠 Learnings (8)

📓 Common learnings

Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 2155
File: hosting/docker/registry/auth.htpasswd:1-1
Timestamp: 2025-06-06T18:49:18.144Z
Learning: Example credentials in self-hosting documentation files are acceptable when they serve as templates or examples for users to understand the setup process, particularly in hosting/docker configuration files.

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Use build extensions in trigger.config.ts (additionalFiles, additionalPackages, aptGet, prismaExtension, etc.) to customize the build

Applied to files:

• docs/snippets/cli-commands-deploy.mdx
• docs/github-actions.mdx

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Configure build process in trigger.config.ts using `build` object with external packages, extensions, and JSX settings

Applied to files:

• docs/snippets/cli-commands-deploy.mdx

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Specify machine resources using the `machine` property with preset options like 'large-1x'

Applied to files:

• docs/snippets/cli-commands-deploy.mdx

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Run `npx trigger.devlatest dev` to start the Trigger.dev development server

Applied to files:

• docs/snippets/cli-commands-deploy.mdx
• docs/github-actions.mdx

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Run `npx trigger.devlatest init` to initialize a Trigger.dev project

Applied to files:

• docs/github-actions.mdx

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use the `task()` function from `trigger.dev/sdk/v3` to define tasks with id and run properties

Applied to files:

• docs/github-actions.mdx

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `trigger.dev/sdk/v3` for all imports in Trigger.dev tasks

Applied to files:

• docs/github-actions.mdx

🪛 LanguageTool

docs/github-actions.mdx

[grammar] ~141-~141: Ensure spelling is correct
Context: ...environment variable pointing to your webapp domain, for example:https://trigger.e...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (4)

docs/github-actions.mdx (2)

184-184: Simplified deploy command consistent with updated CLI behavior.

The deploy command has been simplified from the previous version that required multiple flags. This change is consistent with the updated CLI documentation in docs/snippets/cli-commands-deploy.mdx and reflects that self-hosted deployments now detect the environment automatically.

---

137-141: Docker Buildx is listed as a requirement but is actually optional for self-hosted deployments.

The documentation states "Set up Docker Buildx in your CI environment for building images locally" as a requirement, but Trigger.dev's self-hosted guide indicates Docker Buildx is optional. Docker Buildx is shown in the GitHub Actions example and useful for multi-platform builds and advanced caching, but standard single-platform local Docker builds work without it. The actual hard requirements are Docker and registry credentials.

Recommend clarifying that Docker Buildx is recommended for the example GitHub Actions workflow but not a strict requirement for all self-hosted CI deployments.

Likely an incorrect or invalid review comment.

docs/snippets/cli-commands-deploy.mdx (2)

80-82: Documentation is accurate and well-integrated.

The --local-build parameter documentation correctly states that local builds are automatic when self-hosting. The implementation confirms this: local builds automatically occur when externalBuildData is unavailable, which is the case for self-hosted deployments that lack remote build infrastructure. The --local-build flag allows users to explicitly force local builds even when remote build providers are available, making the documentation complete and clear.

---

92-98: Simplified and clearer self-hosting instructions.

The updated self-hosting section effectively simplifies the deployment process and appropriately cross-references the GitHub Actions guide for CI/CD setup. The guidance about required environment variables is accurate—TRIGGER_ACCESS_TOKEN and TRIGGER_API_URL are used during authentication and build initialization, and the simplified deploy command works without additional flags for self-hosted instances.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[vibe-kanban-cloud]

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

[nicktrn]

@claude review this please, don't make any edits

[claude]

Claude finished @nicktrn's task in 1m 2s —— View job

---

Review Complete

• Read changed files and understand the changes
• Review documentation accuracy and completeness
• Provide feedback

---

Summary

This PR simplifies the self-hosting deployment documentation, removing deprecated CLI flags and streamlining the instructions. The changes are well-structured and improve clarity.

Changes Reviewed

docs/github-actions.mdx

• Simplifies the self-hosting requirements list to focus on the essentials (Docker Buildx, registry credentials, TRIGGER_API_URL)
• Removes outdated --self-hosted and --push flags from the deploy command
• Cleans up redundant comments in the workflow YAML (e.g., "docker setup - part 1")
• Deploy command simplified to just npx trigger.dev@latest deploy

docs/snippets/cli-commands-deploy.mdx

• Adds new --local-build parameter documentation (for forcing local Docker builds)
• Removes several deprecated self-hosting options (--self-hosted, --skip-deploy, --load-image, --registry, --push, --namespace, --network)
• Replaces the verbose Docker Hub example with a simple self-hosting note
• Updates the self-hosting link from /open-source-self-hosting to /self-hosting/overview

Review Notes

Looks good overall. The documentation is now simpler and easier to follow for self-hosters. A few observations:

1. Internal links are correct - The link to /self-hosting/overview and the anchor /github-actions#self-hosting both reference valid documentation paths.

2. Consistent messaging - Both files now convey the same message: self-hosted builds are performed locally by default, and users just need to set the appropriate environment variables.

3. Minor suggestion - In github-actions.mdx line 139, "Set up Docker Buildx" is listed as a requirement. CodeRabbit noted this is technically optional for single-platform builds. Consider clarifying this is "recommended" or "required for the example workflow" rather than a strict requirement. However, since the example workflow uses it, leaving it as-is is also reasonable.

Verdict

Approve - The changes correctly simplify the self-hosting documentation and remove deprecated CLI flags. The documentation is accurate and the cross-references are valid.

---

|