feat(cli): server-selected deploy build path (#4803)

The CLI now asks the server which build path to use before it builds or
uploads anything, so native builds can be rolled out per organization
and per environment type without a CLI release.

```
trigger.dev deploy
  │
  ├─ explicit flag? (--native-build / --local-build / --depot-build)
  │     └─ yes → use it, never ask the server
  │
  └─ GET /api/v1/projects/:ref/:env/deploy-settings   (env API key, 5s timeout, one attempt)
        │
        │  server resolves: native unavailable → org[env type] → org → global[env type] → global → depot
        │
        ├─ { "build_path": "native" | "native_local_bundle" } → that path
        ├─ { "build_path": "depot" }                          → Depot
        └─ error / timeout / 404                              → Depot (fail open)
```

The path comes from four enum feature flags, editable in the global and
per-org admin flag UIs: `deployBuildPath` and `deployBuildPathPreview` /
`Staging` / `Production`. Unset everywhere keeps current behaviour
unchanged; CLIs older than this release never call the endpoint and keep
their current behaviour.

Author: myftija

.changeset/deploy-build-path-settings.md

@@ -0,0 +1,6 @@
+---
+"trigger.dev": patch
+"@trigger.dev/core": patch
+---
+
+`trigger.dev deploy` now asks the server whether to build with Depot or the native build server unless `--native-build`, `--depot-build`, or `--local-build` is passed, so the native build server can be rolled out per organization without a CLI change. `--local-bundle` and `--detach` now require `--native-build`.

apps/webapp/app/routes/api.v1.projects.$projectRef.$env.deploy-settings.ts

@@ -0,0 +1,70 @@
+import { json, type LoaderFunctionArgs } from "@remix-run/server-runtime";
+import { type GetDeploySettingsResponseBody } from "@trigger.dev/core/v3";
+import { z } from "zod";
+import { authenticateApiKeyWithScope } from "~/services/apiAuth.server";
+import { logger } from "~/services/logger.server";
+import { DeploymentService } from "~/v3/services/deployment.server";
+
+const ParamsSchema = z.object({
+  projectRef: z.string(),
+  env: z.enum(["dev", "staging", "prod", "preview"]),
+});
+
+export async function loader({ request, params }: LoaderFunctionArgs) {
+  const parsedParams = ParamsSchema.safeParse(params);
+
+  if (!parsedParams.success) {
+    return json({ error: "Invalid params" }, { status: 400 });
+  }
+
+  try {
+    const authResult = await authenticateApiKeyWithScope(request, {
+      action: "read",
+      resource: { type: "deployments" },
+    });
+
+    if (!authResult.ok) {
+      logger.info("Invalid or missing api key", { url: request.url });
+      return json({ error: authResult.error }, { status: authResult.status });
+    }
+
+    const { environment: authenticatedEnv } = authResult.authentication;
+    const { projectRef, env } = parsedParams.data;
+
+    const deploymentService = new DeploymentService();
+
+    return await deploymentService
+      .getDeploySettings(authenticatedEnv, { projectRef, envSlug: env })
+      .match(
+        ({ buildPath, buildPathSource }) => {
+          logger.info("Resolved deploy build path", {
+            environmentId: authenticatedEnv.id,
+            projectRef,
+            env,
+            buildPath,
+            buildPathSource,
+          });
+
+          return json({ build_path: buildPath } satisfies GetDeploySettingsResponseBody);
+        },
+        (error) => {
+          switch (error.type) {
+            case "environment_mismatch":
+              return json(
+                { error: "API key does not belong to this project environment" },
+                { status: 403 }
+              );
+            case "failed_to_load_global_flags":
+            default:
+              error.type satisfies "failed_to_load_global_flags";
+              logger.error("Failed to load the global feature flags", { error: error.cause });
+              return json({ error: "Internal Server Error" }, { status: 500 });
+          }
+        }
+      );
+  } catch (error) {
+    if (error instanceof Response) throw error;
+    logger.error("Failed to resolve deploy settings", { error });
+    return json({ error: "Internal Server Error" }, { status: 500 });
+  }
+}

apps/webapp/app/services/deploymentApiPaths.server.ts

@@ -4,6 +4,7 @@ export const deploymentApiPaths: (RegExp | string)[] = [
   // /current is runtime SDK surface, kept out of the deploy budget
   /^\/api\/v\d+\/deployments(?!\/current$)(\/|$)/,
   /^\/api\/v1\/projects\/[^/]+\/(dev|staging|prod|preview)$/,
+  /^\/api\/v1\/projects\/[^/]+\/(dev|staging|prod|preview)\/deploy-settings$/,
   /^\/api\/v1\/projects\/[^/]+\/envvars$/,
   /^\/api\/v1\/projects\/[^/]+\/envvars\/[^/]+\/import$/,
   /^\/api\/v1\/projects\/[^/]+\/branches$/,

apps/webapp/app/v3/featureFlags.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { DeployBuildPath } from "@trigger.dev/core/v3";
 
 export const FEATURE_FLAG = {
   defaultWorkerInstanceGroupId: "defaultWorkerInstanceGroupId",
@@ -37,6 +38,11 @@ export const FEATURE_FLAG = {
   // Fleet-wide pin for the complete cutover. Beats every per-org and per-env pin.
   runOpsMintShardOverride: "runOpsMintShardOverride",
   queueMetricsUiEnabled: "queueMetricsUiEnabled",
+  // Build path for CLI deploys, resolved by DeploymentService.getDeploySettings.
+  deployBuildPath: "deployBuildPath",
+  deployBuildPathPreview: "deployBuildPathPreview",
+  deployBuildPathStaging: "deployBuildPathStaging",
+  deployBuildPathProduction: "deployBuildPathProduction",
   // Per-organization rollout for creating additional environment API keys.
   additionalApiKeysEnabled: "additionalApiKeysEnabled",
   // System-wide kill switch for issuing additional environment API keys.
@@ -148,6 +154,10 @@ export const FeatureFlagCatalog = {
   // Per-org access to the Queue Metrics dashboard UI (view only; emission is global and
   // separate). Off unless enabled for the org.
   [FEATURE_FLAG.queueMetricsUiEnabled]: z.coerce.boolean(),
+  [FEATURE_FLAG.deployBuildPath]: DeployBuildPath,
+  [FEATURE_FLAG.deployBuildPathPreview]: DeployBuildPath,
+  [FEATURE_FLAG.deployBuildPathStaging]: DeployBuildPath,
+  [FEATURE_FLAG.deployBuildPathProduction]: DeployBuildPath,
   // Strict booleans prevent a stringified "false" from silently enabling API-key
   // creation or lookup. Cold/absent values resolve to the safe `false`.
   [FEATURE_FLAG.additionalApiKeysEnabled]: z.boolean(),

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

@@ -4,16 +4,25 @@ import { errAsync, fromPromise, okAsync, type ResultAsync } from "neverthrow";
 import { Prisma, type WorkerDeployment, type Project, boundedIn } from "@trigger.dev/database";
 import {
   BuildServerMetadata,
+  DeployBuildPath,
   logger,
   type GitMeta,
   type DeploymentEvent,
+  type RuntimeEnvironmentType,
 } from "@trigger.dev/core/v3";
 import { TimeoutDeploymentService } from "./timeoutDeployment.server";
 import { recordDeploymentFinished } from "./recordDeploymentFinished.server";
 import { env } from "~/env.server";
 import { createRemoteImageBuild } from "../remoteImageBuilder.server";
 import { FINAL_DEPLOYMENT_STATUSES } from "./failDeployment.server";
-import { enqueueBuild, generateRegistryCredentials } from "~/services/platform.v3.server";
+import {
+  enqueueBuild,
+  generateRegistryCredentials,
+  isBillingConfigured,
+} from "~/services/platform.v3.server";
+import { FEATURE_FLAG, type FeatureFlagKey } from "../featureFlags";
+import { flags } from "../featureFlags.server";
+import { globalFlagsRegistry } from "../globalFlagsRegistry.server";
 import { AppendInput, AppendRecord, S2 } from "@s2-dev/streamstore";
 import { createRedisClient } from "~/redis.server";
 
@@ -28,6 +37,31 @@ const s2TokenRedis = createRedisClient("s2-token-cache", {
 });
 const s2 = env.S2_ENABLED === "1" ? new S2({ accessToken: env.S2_ACCESS_TOKEN }) : undefined;
 
+const DEPLOY_BUILD_PATH_ENV_FLAG: Partial<Record<RuntimeEnvironmentType, FeatureFlagKey>> = {
+  PREVIEW: FEATURE_FLAG.deployBuildPathPreview,
+  STAGING: FEATURE_FLAG.deployBuildPathStaging,
+  PRODUCTION: FEATURE_FLAG.deployBuildPathProduction,
+};
+
+const DEPLOY_ENV_SLUG_FOR_TYPE: Record<RuntimeEnvironmentType, DeployEnvSlug> = {
+  DEVELOPMENT: "dev",
+  STAGING: "staging",
+  PRODUCTION: "prod",
+  PREVIEW: "preview",
+};
+
+type DeployEnvSlug = "dev" | "staging" | "prod" | "preview";
+
+type DeployBuildPathSource =
+  | "unavailable"
+  | "organization_environment"
+  | "organization"
+  | "global_environment"
+  | "global"
+  | "default";
+
+type DeploySettings = { buildPath: DeployBuildPath; buildPathSource: DeployBuildPathSource };
+
 export class DeploymentService extends BaseService {
   /**
    * Progresses a deployment from PENDING to INSTALLING and then to BUILDING.
@@ -282,6 +316,67 @@ export class DeploymentService extends BaseService {
       .map(() => undefined);
   }
 
+  public getDeploySettings(
+    authenticatedEnv: Pick<AuthenticatedEnvironment, "type" | "organization" | "project">,
+    target: { projectRef: string; envSlug: DeployEnvSlug }
+  ) {
+    const validateTarget = (): ResultAsync<undefined, { type: "environment_mismatch" }> => {
+      if (
+        authenticatedEnv.project.externalRef !== target.projectRef ||
+        DEPLOY_ENV_SLUG_FOR_TYPE[authenticatedEnv.type] !== target.envSlug
+      ) {
+        return errAsync({ type: "environment_mismatch" as const });
+      }
+      return okAsync(undefined);
+    };
+
+    const loadGlobalFlags = () =>
+      fromPromise(Promise.resolve(globalFlagsRegistry.current() ?? flags()), (error) => ({
+        type: "failed_to_load_global_flags" as const,
+        cause: error,
+      }));
+
+    const pickBuildPath = (globalFlagSet: Record<string, unknown>): DeploySettings => {
+      const envKey = DEPLOY_BUILD_PATH_ENV_FLAG[authenticatedEnv.type];
+      const orgFlags = authenticatedEnv.organization.featureFlags;
+      const orgFlagSet: Record<string, unknown> =
+        orgFlags && typeof orgFlags === "object" && !Array.isArray(orgFlags)
+          ? (orgFlags as Record<string, unknown>)
+          : {};
+
+      const candidates: Array<
+        [Record<string, unknown>, FeatureFlagKey | undefined, DeployBuildPathSource]
+      > = [
+        [orgFlagSet, envKey, "organization_environment"],
+        [orgFlagSet, FEATURE_FLAG.deployBuildPath, "organization"],
+        [globalFlagSet, envKey, "global_environment"],
+        [globalFlagSet, FEATURE_FLAG.deployBuildPath, "global"],
+      ];
+
+      for (const [flagSet, key, buildPathSource] of candidates) {
+        if (!key) continue;
+        const parsed = DeployBuildPath.safeParse(flagSet[key]);
+        if (parsed.success) {
+          return { buildPath: parsed.data, buildPathSource };
+        }
+      }
+
+      return { buildPath: "depot", buildPathSource: "default" };
+    };
+
+    const resolveBuildPath = (): ResultAsync<
+      DeploySettings,
+      { type: "failed_to_load_global_flags"; cause: unknown }
+    > => {
+      if (!isBillingConfigured()) {
+        return okAsync({ buildPath: "depot" as const, buildPathSource: "unavailable" as const });
+      }
+      return loadGlobalFlags().map(pickBuildPath);
+    };
+
+    return validateTarget().andThen(resolveBuildPath);
+  }
+
   /**
    * Generates registry credentials for a deployment. Returns an error if the deployment is in a final state.
    *

apps/webapp/test/deploySettingsRoute.test.ts

@@ -0,0 +1,121 @@
+import { errAsync, okAsync } from "neverthrow";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  authenticateApiKeyWithScope: vi.fn<(...args: any[]) => Promise<any>>(),
+  getDeploySettings: vi.fn<(...args: any[]) => any>(),
+}));
+
+vi.mock("~/services/apiAuth.server", () => ({
+  authenticateApiKeyWithScope: mocks.authenticateApiKeyWithScope,
+}));
+vi.mock("~/v3/services/deployment.server", () => ({
+  DeploymentService: class {
+    getDeploySettings = mocks.getDeploySettings;
+  },
+}));
+vi.mock("~/services/logger.server", () => ({
+  logger: { info: vi.fn(), debug: vi.fn(), error: vi.fn() },
+}));
+
+import { loader } from "~/routes/api.v1.projects.$projectRef.$env.deploy-settings";
+
+function environment(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "env_1",
+    type: "PRODUCTION",
+    project: { id: "proj_1", externalRef: "proj_ref" },
+    organization: { featureFlags: {} },
+    ...overrides,
+  };
+}
+
+function load(env = "prod", projectRef = "proj_ref") {
+  return loader({
+    request: new Request(
+      `https://app.example.com/api/v1/projects/${projectRef}/${env}/deploy-settings`
+    ),
+    params: { projectRef, env },
+    context: {},
+  });
+}
+
+describe("deploy settings route", () => {
+  beforeEach(() => {
+    mocks.authenticateApiKeyWithScope.mockReset();
+    mocks.getDeploySettings.mockReset();
+    mocks.authenticateApiKeyWithScope.mockResolvedValue({
+      ok: true,
+      authentication: { environment: environment() },
+    });
+    mocks.getDeploySettings.mockReturnValue(
+      okAsync({ buildPath: "depot", buildPathSource: "default" })
+    );
+  });
+
+  it("rejects an unknown env slug before authenticating", async () => {
+    const response = await load("nope");
+    expect(response.status).toBe(400);
+    expect(mocks.authenticateApiKeyWithScope).not.toHaveBeenCalled();
+  });
+
+  it("passes the auth failure through", async () => {
+    mocks.authenticateApiKeyWithScope.mockResolvedValue({
+      ok: false,
+      status: 401,
+      error: "Invalid API key",
+    });
+    const response = await load();
+    expect(response.status).toBe(401);
+    expect(await response.json()).toEqual({ error: "Invalid API key" });
+    expect(mocks.getDeploySettings).not.toHaveBeenCalled();
+  });
+
+  it("maps an environment mismatch to 403", async () => {
+    mocks.getDeploySettings.mockReturnValue(errAsync({ type: "environment_mismatch" }));
+    const response = await load("prod", "proj_other");
+    expect(response.status).toBe(403);
+    expect(mocks.getDeploySettings).toHaveBeenCalledWith(environment(), {
+      projectRef: "proj_other",
+      envSlug: "prod",
+    });
+  });
+
+  it("returns only the build path, resolved for the authenticated environment", async () => {
+    const env = environment({ type: "PREVIEW" });
+    mocks.authenticateApiKeyWithScope.mockResolvedValue({
+      ok: true,
+      authentication: { environment: env },
+    });
+    mocks.getDeploySettings.mockReturnValue(
+      okAsync({ buildPath: "native", buildPathSource: "organization_environment" })
+    );
+
+    const response = await load("preview");
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({ build_path: "native" });
+    expect(mocks.getDeploySettings).toHaveBeenCalledWith(env, {
+      projectRef: "proj_ref",
+      envSlug: "preview",
+    });
+    expect(mocks.authenticateApiKeyWithScope).toHaveBeenCalledWith(expect.any(Request), {
+      action: "read",
+      resource: { type: "deployments" },
+    });
+  });
+
+  it("returns 500 when the global flags cannot be loaded", async () => {
+    mocks.getDeploySettings.mockReturnValue(
+      errAsync({ type: "failed_to_load_global_flags", cause: new Error("db down") })
+    );
+    const response = await load();
+    expect(response.status).toBe(500);
+    expect(await response.json()).toEqual({ error: "Internal Server Error" });
+  });
+
+  it("rethrows a Response thrown by authentication", async () => {
+    const thrown = new Response(null, { status: 429 });
+    mocks.authenticateApiKeyWithScope.mockRejectedValue(thrown);
+    await expect(load()).rejects.toBe(thrown);
+  });
+});