feat(webapp): allow version downgrades via promote API

[chengzp]

✅ Checklist

• I have followed every step in the contributing guide
• The PR title follows the convention.
• I ran and tested the code works

---

Testing

Deployed twice with pnpm exec trigger deploy

# Without allowRollbacks: returns 400
curl -X POST http://localhost:3030/api/v1/deployments/20260314.1/promote -H "Authorization: Bearer ${TRIGGER_API_KEY}"
{"error":"Cannot promote a deployment that is older than the current deployment."}

# With allowRollbacks: succeeds
curl -X POST "http://localhost:3030/api/v1/deployments/20260314.1/promote?allowRollbacks=true" -H "Authorization: Bearer ${TRIGGER_API_KEY}"
{"id":"deployment_k2usviwk6bgq63ctkqqqo","version":"20260314.1","shortCode":"pzaalcga"}

---

Changelog

Adds an allowRollbacks query param to the promote deployment API endpoint (POST /api/v1/deployments/:version/promote?allowRollbacks=true). When set to true, the version ordering check in ChangeCurrentDeploymentService is skipped, allowing older deployments to be promoted.

---

Screenshots

N/A

[changeset-bot]

⚠️ No Changeset found

Latest commit: b3fc567

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 pull request introduces a feature to allow bypassing version validation when promoting or rolling back worker deployments. It adds a new allowRollbacks query parameter to the promote deployment API endpoint, which is parsed and passed through to the deployment service. The service method signature is updated to accept an optional parameter that gates the existing version validation logic, allowing callers to skip deployment version checks when this parameter is enabled.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding version downgrade capability to the promote API via a new query parameter.
Description check	✅ Passed	The description fully addresses all required template sections with substantive content: checklist items checked, testing steps with curl commands and results, detailed changelog, and proper formatting.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

📝 Coding Plan

• Generate coding plan for human review comments

---

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

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@apps/webapp/app/routes/api.v1.deployments`.$deploymentVersion.promote.ts:
- Around line 35-37: The code reads allowRollbacks from the URL without schema
validation; create a Zod QuerySchema (e.g., const QuerySchema = z.object({
allowRollbacks: z.optional(z.union([z.literal("true"), z.literal("false")])) }))
and parse url.searchParams via QuerySchema.parse or safeParse, then derive
allowRollbacks as parsed.allowRollbacks === "true"; on parse failure return a
400 response (consistent with other routes) and include the validation error
message. Update the usage of request/url and the allowRollbacks variable to use
the validated parsed result.

In `@apps/webapp/app/v3/services/changeCurrentDeployment.server.ts`:
- Around line 10-14: The current call method accepts disableVersionCheck and
uses it to skip ordering/version safety for both "promote" and "rollback";
change the logic so disableVersionCheck is only honored when direction ===
"promote" (i.e., only allow bypassing the version-order check for promotions),
and ensure rollback paths always perform the ordering/version checks regardless
of the disableVersionCheck flag; update any conditional(s) in the call method
that reference disableVersionCheck and the direction to explicitly require
direction === "promote" before skipping checks (use the deployment, direction,
and disableVersionCheck parameters to locate the code).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 54146e47-65d5-4b37-8575-2cf689514197

📥 Commits

Reviewing files that changed from the base of the PR and between 440c16c and b3fc567.

📒 Files selected for processing (3)

• .server-changes/allow-rollbacks-promote-api.md
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts
• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

📜 Review details

🧰 Additional context used

📓 Path-based instructions (15)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.{ts,tsx}: Use types over interfaces for TypeScript
Avoid using enums; prefer string unions or const objects instead

**/*.{ts,tsx}: Use task export syntax: export const myTask = task({ id: 'my-task', run: async (payload) => { ... } })
Use Run Engine 2.0 (@internal/run-engine) and redis-worker for all new work - avoid DEPRECATED zodworker (Graphile-worker wrapper)
Prisma 6.14.0 client and schema use PostgreSQL in internal-packages/database - import only from Prisma client

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

{packages/core,apps/webapp}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use zod for validation in packages/core and apps/webapp

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use function declarations instead of default exports

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

apps/webapp/app/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

Access all environment variables through the env export of env.server.ts instead of directly accessing process.env in the Trigger.dev webapp

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

apps/webapp/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

apps/webapp/**/*.{ts,tsx}: When importing from @trigger.dev/core in the webapp, use subpath exports from the package.json instead of importing from the root path
Follow the Remix 2.1.0 and Express server conventions when updating the main trigger.dev webapp

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

apps/webapp/app/v3/services/**/*.server.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

Organize services in the webapp following the pattern app/v3/services/*/*.server.ts

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/otel-metrics.mdc)

**/*.ts: When creating or editing OTEL metrics (counters, histograms, gauges), ensure metric attributes have low cardinality by using only enums, booleans, bounded error codes, or bounded shard IDs
Do not use high-cardinality attributes in OTEL metrics such as UUIDs/IDs (envId, userId, runId, projectId, organizationId), unbounded integers (itemCount, batchSize, retryCount), timestamps (createdAt, startTime), or free-form strings (errorMessage, taskName, queueName)
When exporting OTEL metrics via OTLP to Prometheus, be aware that the exporter automatically adds unit suffixes to metric names (e.g., 'my_duration_ms' becomes 'my_duration_ms_milliseconds', 'my_counter' becomes 'my_counter_total'). Account for these transformations when writing Grafana dashboards or Prometheus queries

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

**/*.{js,ts,jsx,tsx,json,md,yaml,yml}

📄 CodeRabbit inference engine (AGENTS.md)

Format code using Prettier before committing

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

apps/webapp/**/*.server.ts

📄 CodeRabbit inference engine (apps/webapp/CLAUDE.md)

Access environment variables via the env export from app/env.server.ts, never use process.env directly

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

apps/webapp/app/v3/services/**/*.server.ts

📄 CodeRabbit inference engine (apps/webapp/CLAUDE.md)

When editing services that branch on RunEngineVersion to support both V1 and V2 (e.g., cancelTaskRun.server.ts, batchTriggerV3.server.ts), only modify V2 code paths

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

apps/{webapp,supervisor}/**/*

📄 CodeRabbit inference engine (CLAUDE.md)

When modifying only server components (apps/webapp/, apps/supervisor/) with no package changes, add a .server-changes/ file instead of a changeset

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

**/*.{ts,tsx,js}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,js}: Always import from @trigger.dev/sdk for Trigger.dev tasks - never use @trigger.dev/sdk/v3 or deprecated client.defineJob
Import subpaths only from @trigger.dev/core, never import from root
Add crumbs as you write code using // @crumbs comments or // #region @crumbs blocks for agentcrumbs debug tracing

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

apps/webapp/app/v3/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

When modifying V3 code paths in apps/webapp/app/v3/, only modify V2 code - consult apps/webapp/CLAUDE.md for V1-only legacy code to avoid

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

apps/webapp/**/*.{ts,tsx,jsx,js}

📄 CodeRabbit inference engine (CLAUDE.md)

Remix 2.1.0 is used in apps/webapp for the main API, dashboard, and orchestration with Express server

Files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

apps/webapp/app/routes/**/*.ts

📄 CodeRabbit inference engine (apps/webapp/CLAUDE.md)

Use Remix flat-file route convention with dot-separated segments (e.g., api.v1.tasks.$taskId.trigger.ts for /api/v1/tasks/:taskId/trigger)

Files:

• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

🧠 Learnings (7)

📓 Common learnings

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: packages/cli-v3/CLAUDE.md:0-0
Timestamp: 2026-03-02T12:43:34.140Z
Learning: Applies to packages/cli-v3/src/commands/promote.ts : Implement `promote.ts` command in `src/commands/` for deployment promotion

📚 Learning: 2026-03-02T12:43:34.140Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: packages/cli-v3/CLAUDE.md:0-0
Timestamp: 2026-03-02T12:43:34.140Z
Learning: Applies to packages/cli-v3/src/commands/promote.ts : Implement `promote.ts` command in `src/commands/` for deployment promotion

Applied to files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

📚 Learning: 2026-03-02T12:42:56.114Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: apps/webapp/CLAUDE.md:0-0
Timestamp: 2026-03-02T12:42:56.114Z
Learning: Applies to apps/webapp/app/v3/services/**/*.server.ts : When editing services that branch on `RunEngineVersion` to support both V1 and V2 (e.g., `cancelTaskRun.server.ts`, `batchTriggerV3.server.ts`), only modify V2 code paths

Applied to files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

📚 Learning: 2026-03-13T13:37:49.544Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-13T13:37:49.544Z
Learning: Applies to apps/webapp/app/v3/**/*.{ts,tsx} : When modifying V3 code paths in apps/webapp/app/v3/, only modify V2 code - consult apps/webapp/CLAUDE.md for V1-only legacy code to avoid

Applied to files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

📚 Learning: 2026-03-02T12:43:34.140Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: packages/cli-v3/CLAUDE.md:0-0
Timestamp: 2026-03-02T12:43:34.140Z
Learning: Applies to packages/cli-v3/src/commands/deploy.ts : Implement `deploy.ts` command in `src/commands/` for production deployment

Applied to files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts
• apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts

📚 Learning: 2026-03-13T13:37:49.544Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-13T13:37:49.544Z
Learning: Applies to {packages,integrations}/**/*.{ts,tsx,js,json} : When modifying public packages (packages/* or integrations/*), add a changeset using pnpm run changeset:add with default patch level for bug fixes and minor changes

Applied to files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

📚 Learning: 2026-03-10T17:56:20.938Z

Learnt from: samejr
Repo: triggerdotdev/trigger.dev PR: 3201
File: apps/webapp/app/v3/services/setSeatsAddOn.server.ts:25-29
Timestamp: 2026-03-10T17:56:20.938Z
Learning: Do not implement local userId-to-organizationId authorization checks inside org-scoped service classes (e.g., SetSeatsAddOnService, SetBranchesAddOnService) in the web app. Rely on route-layer authentication (requireUserId(request)) and org membership enforcement via the _app.orgs.$organizationSlug layout route. Any userId/organizationId that reaches these services from org-scoped routes has already been validated. Apply this pattern across all org-scoped services to avoid redundant auth checks and maintain consistency.

Applied to files:

• apps/webapp/app/v3/services/changeCurrentDeployment.server.ts

🔇 Additional comments (2)

.server-changes/allow-rollbacks-promote-api.md (1)

1-6: Changelog entry is clear and correctly scoped.

This documents the API behavior change accurately and is ready to ship.

apps/webapp/app/routes/api.v1.deployments.$deploymentVersion.promote.ts (1)

53-53: Service wiring for rollback flag propagation looks good.

Passing the parsed allowRollbacks flag through to the service keeps the route behavior aligned with the new API capability.