feat(app): add --no-promote for promotionless deploys

Add a `--no-promote` flag to `prisma-cli app deploy` that builds a new
deployment without flipping the live pointer. The previous deployment
keeps serving live; the new one is reachable only at its own candidate
URL until a later `app promote <deployment-id>` makes it live.

This is the CI build-then-verify path: build the candidate, health-check
its URL, then promote. Because a promotionless deploy never replaces the
live deployment, it bypasses the production-confirmation gate — so
`app deploy --no-promote` on the production branch works without `--prod`.

Wiring:
- ComputeClient.deploy already supports `skipPromote`; the provider now
  forwards it and maps the not-promoted return (candidate URL, live
  pointer stays on the previous deployment, `promoted: false`).
- Controller threads `noPromote`, skips the gate when set, surfaces
  `promoted` + `deployment.live`, and leads nextSteps with `app promote`.
- Human output renders a built-not-live headline with a promote hint;
  `--json` carries `promoted` and the candidate `deployment.{url,live}`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: kristof-siket

docs/product/command-spec.md

@@ -1012,7 +1012,7 @@ prisma-cli app run --build-type bun --entry server.ts --port 3000
 prisma-cli app run api
 ```
 
-## `prisma-cli app deploy [app] --project <id-or-name> --create-project <name> --app <name> --branch <name> --framework <nextjs|nuxt|astro|hono|nestjs|tanstack-start|custom|bun> --entry <path> --http-port <port> --region <region> --env <name=value|file> --db --no-db --prod`
+## `prisma-cli app deploy [app] --project <id-or-name> --create-project <name> --app <name> --branch <name> --framework <nextjs|nuxt|astro|hono|nestjs|tanstack-start|custom|bun> --entry <path> --http-port <port> --region <region> --env <name=value|file> --db --no-db --prod --no-promote`
 
 Purpose:
 
@@ -1053,7 +1053,7 @@ same reasons they are excluded today.
 - the `[app]` argument selects an `apps` target by key:
   - without an `[app]` argument, a command run from inside a target's `root` selects that target, so `cd apps/api && prisma-cli app deploy` deploys `api`; the deepest matching root wins and an ambiguous tie selects nothing
   - with multiple `apps` entries, no `[app]` argument, and no target inferred from the invocation directory, deploy deploys every target sequentially in declaration order — the config declares the system, and a bare `prisma-cli app deploy` ships it
-  - deploying all targets rejects per-app inputs (`--app`, `--framework`, `--entry`, `--http-port`, `--region`, `--env`, `PRISMA_APP_ID`) with a usage error; project- and branch-level flags (`--project`, `--create-project`, `--branch`, `--db`, `--no-db`, `--prod`, `--yes`) apply to the whole run, with `--create-project` creating and binding the Project once before the first target
+  - deploying all targets rejects per-app inputs (`--app`, `--framework`, `--entry`, `--http-port`, `--region`, `--env`, `PRISMA_APP_ID`) with a usage error; project- and branch-level flags (`--project`, `--create-project`, `--branch`, `--db`, `--no-db`, `--prod`, `--no-promote`, `--yes`) apply to the whole run, with `--create-project` creating and binding the Project once before the first target
   - a deploy-all run stops at the first failure and reports the targets already live; `--json` output aggregates one full deploy result per target
   - `app build` and `app run` still require a target in multi-app configs and fail with `COMPUTE_CONFIG_TARGET_REQUIRED` (a dev server cannot run N apps at once; build keeps the same shape)
   - an `[app]` argument that matches no target fails with `COMPUTE_CONFIG_TARGET_UNKNOWN`
@@ -1120,6 +1120,8 @@ Behavior:
 - resolves or creates app context inside the resolved branch from `--app`, `PRISMA_APP_ID`, `package.json#name`, or current directory name
 - auto-promotes the first production deploy for an App without `--prod`
 - requires `--prod` for subsequent deploys to a production Branch; `--yes` only skips the confirmation prompt when `--prod` is also present
+- supports `--no-promote` to build a new deployment without promoting it to live: the previous deployment keeps serving, and the new deployment is reachable only at its own candidate URL until a later `app promote <deployment-id>` makes it live
+- `--no-promote` never replaces the live deployment, so it bypasses the production gate: `app deploy --no-promote` on a production Branch builds a candidate without `--prod` and without confirmation. It is the CI build-then-verify path — build the candidate, health-check its URL, then `app promote`
 - does not prompt when there is no real choice; zero matching apps creates the inferred app
 - writes `.prisma/local.json` after Project binding succeeds and before build/deploy starts, so retries after a failed deploy do not repeat setup
 - before asking `Customize build settings? (y/N)`, previews the detected framework and runtime so the user can see the defaults they are accepting or changing
@@ -1135,6 +1137,7 @@ Behavior:
 - after setup, deploy prints `Deploying to <Project> / <Branch> / <App>`; later deploys print a compact target header such as `Deploying ./j1 to j1 / main / j1`
 - deploy progress uses short stage copy (`Building locally...`, `Built <size>`, `Uploading...`, `Uploaded`, `Deploying...`, `Deployed`) and never prints `Status: running` or `Deployment is running at ...`
 - success human output prints `Live in <duration>`, the URL on its own line, and `Logs   prisma-cli app logs`
+- with `--no-promote`, success human output instead prints `Built <deployment-id> in <duration> (not promoted)`, the candidate URL on its own line, a note that the live deployment is unchanged, and a `Promote   prisma-cli app promote <deployment-id>` next step
 - accepts repeated `--env NAME=VALUE` flags and dotenv file paths such as `--env .env`
 - supports `--db` to create a new empty Prisma Postgres database and write `DATABASE_URL` and `DIRECT_URL` through the existing `project env` storage; the CLI never runs schema or migration commands — applying the schema stays with the user's own tooling
 - `--db` is the opinionated single-database path: it creates **one** branch database and exposes `DATABASE_URL`/`DIRECT_URL` as branch-scoped env vars, so every app on the branch shares it. In a multi-app deploy-all run the database is created once (on the first target) and reused by the rest; the run never creates a database per app. Per-app or per-service database topologies are explicit-configuration territory — set each app's database env vars yourself rather than relying on `--db` to infer app-to-database ownership
@@ -1176,6 +1179,7 @@ prisma-cli app deploy --no-db
 prisma-cli app deploy --framework nextjs --http-port 3000
 prisma-cli app deploy --branch feat-login --framework hono --http-port 3000
 prisma-cli app deploy --prod --yes
+prisma-cli app deploy --no-promote
 prisma-cli app deploy --framework bun --entry src/server.ts --http-port 3000
 prisma-cli app deploy --entry src/server.ts --http-port 3000
 prisma-cli app deploy web

packages/cli/src/commands/app/index.ts

@@ -247,7 +247,13 @@ function createDeployCommand(runtime: CliRuntime): Command {
       ),
     )
     .addOption(new Option("--no-db", "Skip database setup"))
-    .addOption(new Option("--prod", "Confirm intent to deploy to production"));
+    .addOption(new Option("--prod", "Confirm intent to deploy to production"))
+    .addOption(
+      new Option(
+        "--no-promote",
+        "Build the new deployment without promoting it to live (promote later with app promote <id>)",
+      ),
+    );
   addGlobalFlags(command);
 
   command.action(async (configTarget: string | undefined, options) => {
@@ -262,6 +268,7 @@ function createDeployCommand(runtime: CliRuntime): Command {
     const createProjectName = (options as { createProject?: string })
       .createProject;
     const prod = (options as { prod?: boolean }).prod;
+    const noPromote = (options as { promote?: boolean }).promote === false;
     const db = (options as { db?: boolean }).db;
     const hasDbConflict =
       hasFlag(runtime.argv, "--db") && hasFlag(runtime.argv, "--no-db");
@@ -291,6 +298,7 @@ function createDeployCommand(runtime: CliRuntime): Command {
           region,
           envAssignments,
           prod: prod === true,
+          noPromote,
           db,
           configTarget,
         });

packages/cli/src/controllers/app.ts

@@ -387,6 +387,7 @@ interface AppDeployOptions {
   region?: string;
   envAssignments?: string[];
   prod?: boolean;
+  noPromote?: boolean;
   db?: boolean;
   configTarget?: string;
 }
@@ -739,16 +740,18 @@ async function runSingleAppDeploy(
   framework = customized.framework;
   runtime = customized.runtime;
 
-  const productionDeployGate = await enforceProductionDeployGate(
-    context,
-    provider,
-    {
-      appId: selectedApp.appId,
-      appName: selectedApp.displayName,
-      branchKind: target.branch.kind,
-      prod: options?.prod === true,
-    },
-  );
+  const noPromote = options?.noPromote === true;
+  // A promotionless deploy never replaces the live deployment, so the
+  // production-confirmation gate does not apply: --no-promote on the production
+  // branch builds a candidate without --prod.
+  const productionDeployGate = noPromote
+    ? { firstProductionDeploy: false }
+    : await enforceProductionDeployGate(context, provider, {
+        appId: selectedApp.appId,
+        appName: selectedApp.displayName,
+        branchKind: target.branch.kind,
+        prod: options?.prod === true,
+      });
 
   // Customization can switch from a Bun-compatible framework to one that
   // derives its entrypoint from build output, so validate --entry again after it.
@@ -801,6 +804,7 @@ async function runSingleAppDeploy(
       buildSettings: buildSettingsResolution.settings,
       portMapping,
       envVars,
+      skipPromote: noPromote,
       interaction: undefined,
       signal: context.runtime.signal,
       progress: createDeployProgress(
@@ -838,6 +842,7 @@ async function runSingleAppDeploy(
         name: deployResult.app.name,
       },
       deployment: deployResult.deployment,
+      promoted: deployResult.promoted,
       deploySettings: {
         config: {
           path: buildSettingsResolution.relativeConfigPath,
@@ -871,10 +876,15 @@ async function runSingleAppDeploy(
       ...legacyWarnings,
       ...branchDatabaseSetup.warnings,
     ],
-    nextSteps: [
-      "prisma-cli app list-deploys",
-      `prisma-cli app show-deploy ${deployResult.deployment.id}`,
-    ],
+    nextSteps: deployResult.promoted
+      ? [
+          "prisma-cli app list-deploys",
+          `prisma-cli app show-deploy ${deployResult.deployment.id}`,
+        ]
+      : [
+          `prisma-cli app promote ${deployResult.deployment.id}`,
+          `prisma-cli app show-deploy ${deployResult.deployment.id}`,
+        ],
   };
 }
 

packages/cli/src/lib/app/app-provider.ts

@@ -65,7 +65,9 @@ export interface DeployRecord {
     id: string;
     status: string;
     url: string | null;
+    live: boolean;
   };
+  promoted: boolean;
 }
 
 export interface EnvRecord {
@@ -229,6 +231,7 @@ export interface AppProvider {
     buildSettings?: AppBuildSettings;
     portMapping?: PortMapping;
     envVars?: Record<string, string>;
+    skipPromote?: boolean;
     interaction?: unknown;
     signal?: AbortSignal;
     progress?: unknown;
@@ -511,6 +514,7 @@ export function createAppProvider(
         region: resolvedApp.region,
         portMapping: options.portMapping,
         envVars: options.envVars,
+        skipPromote: options.skipPromote,
         timeoutSeconds: 120,
         pollIntervalMs: 2000,
         interaction: options.interaction as never,
@@ -524,13 +528,18 @@ export function createAppProvider(
 
       const deployed = deployResult.value;
 
+      // On a promotionless deploy the SDK leaves appEndpointDomain null and the
+      // previous deployment serving live, so the live pointer stays on the old
+      // deployment and both URL expressions resolve to the candidate endpoint.
       return {
         projectId: deployed.projectId,
         app: {
           id: deployed.appId,
           name: deployed.appName,
           region: deployed.region ?? null,
-          liveDeploymentId: deployed.deploymentId,
+          liveDeploymentId: deployed.promoted
+            ? deployed.deploymentId
+            : deployed.previousDeploymentId,
           liveUrl: toAbsoluteUrl(deployed.appEndpointDomain ?? null),
         },
         deployment: {
@@ -541,7 +550,9 @@ export function createAppProvider(
               deployed.deploymentEndpointDomain ??
               null,
           ),
+          live: deployed.promoted,
         },
+        promoted: deployed.promoted,
       };
     },
 

packages/cli/src/presenters/app.ts

@@ -68,12 +68,33 @@ export function renderAppDeploy(
   const logsCommand = options?.logsTarget
     ? `prisma-cli app logs ${options.logsTarget}`
     : "prisma-cli app logs";
+  const headline = result.promoted
+    ? [
+        `Live in ${formatDuration(result.durationMs)}`,
+        ...(result.deployment.url
+          ? [context.ui.link(result.deployment.url)]
+          : []),
+      ]
+    : [
+        `Built ${result.deployment.id} in ${formatDuration(result.durationMs)} (not promoted)`,
+        ...(result.deployment.url
+          ? [context.ui.link(result.deployment.url)]
+          : []),
+        context.ui.dim("The live deployment is unchanged."),
+      ];
   const lines = [
-    `Live in ${formatDuration(result.durationMs)}`,
-    ...(result.deployment.url ? [context.ui.link(result.deployment.url)] : []),
+    ...headline,
     ...renderBranchDatabaseDeploySummary(context, result),
     "",
     ...renderDeployOutputRows(context.ui, [
+      ...(result.promoted
+        ? []
+        : [
+            {
+              label: "Promote",
+              value: `prisma-cli app promote ${result.deployment.id}`,
+            },
+          ]),
       { label: "Logs", value: logsCommand },
     ]),
     ...renderDeployResolvedContextBlock(context, result),

packages/cli/src/types/app.ts

@@ -75,7 +75,10 @@ export interface AppDeployResult {
     id: string;
     status: string;
     url: string | null;
+    live: boolean;
   };
+  /** Whether the new deployment was promoted to live. False for --no-promote. */
+  promoted: boolean;
   deploySettings: AppDeploySettings;
   durationMs: number;
   localPin?: {