feat: hosting app deploy supports preview deployment flag (#1205)

* feat: hosting app deploy supports preview deployment flag

* write preview url to github actions output

* bump

* promote instead of preview

* working nicely

* fmt

Author: viktormarinho

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deco-cli",
-  "version": "0.19.3",
+  "version": "0.20.0",
   "description": "CLI for managing decocms.com apps & projects",
   "license": "MIT",
   "author": "Deco team",

packages/cli/src/cli.ts

@@ -183,6 +183,7 @@ const hostingDeploy = new Command("deploy")
     "--dry-run",
     "Write deploy manifest to local filesystem instead of deploying",
   )
+  .option("--no-promote", "Do not promote the deployment to production routes")
   .argument("[cwd]", "Working directory")
   .action(async (cwd, options) => {
     try {
@@ -206,6 +207,7 @@ const hostingDeploy = new Command("deploy")
         assetsDirectory,
         force: options.force,
         dryRun: options.dryRun,
+        promote: options.promote ?? true,
       });
     } catch (error) {
       console.error(

packages/cli/src/commands/hosting/deploy.ts

@@ -35,6 +35,7 @@ interface Options {
   unlisted?: boolean;
   assetsDirectory?: string;
   force?: boolean;
+  promote?: boolean;
   dryRun?: boolean;
 }
 
@@ -48,6 +49,7 @@ export const deploy = async ({
   assetsDirectory,
   skipConfirmation,
   force,
+  promote = true,
   unlisted = true,
   dryRun = false,
 }: Options) => {
@@ -163,13 +165,17 @@ export const deploy = async ({
     bundle: hasTsFile,
     unlisted,
     force,
+    promote,
   };
 
   console.log("🚚 Deployment summary:");
   console.log(`  App: ${appSlug}`);
   console.log(`  Files: ${files.length}`);
   console.log(`  ${envVarsStatus}`);
   console.log(`  ${wranglerConfigStatus}`);
+  if (promote) {
+    console.log(`  Promote mode: true (deployment will replace production)`);
+  }
 
   if (dryRun) {
     const manifestPath = join(cwd, "deploy-manifest.json");
@@ -240,4 +246,12 @@ export const deploy = async ({
   console.log(`\n🎉 Deployed! Available at:`);
   hosts.forEach((host) => console.log(`  ${host}`));
   console.log();
+
+  const previewUrl = promote ? null : hosts[0];
+  if (process.env.GITHUB_OUTPUT && previewUrl) {
+    await fs.appendFile(
+      process.env.GITHUB_OUTPUT,
+      `preview_url=${previewUrl}\n`,
+    );
+  }
 };

packages/create-deco/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-deco",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Create a new deco app",
   "main": "index.js",
   "bin": {
@@ -20,7 +20,7 @@
   "author": "Deco team",
   "license": "MIT",
   "dependencies": {
-    "deco-cli": "^0.17.6"
+    "deco-cli": "^0.20.0"
   },
   "engines": {
     "node": ">=22.0.0"

packages/sdk/src/mcp/hosting/api.ts

@@ -147,6 +147,7 @@ interface UpdateDatabaseArgs {
   result: DeployResult;
   wranglerConfig: WranglerConfig;
   force?: boolean;
+  promote?: boolean;
   files?: Record<string, string>;
 }
 
@@ -158,6 +159,7 @@ async function updateDatabase({
   result,
   wranglerConfig,
   force,
+  promote = true,
 }: UpdateDatabaseArgs) {
   // First, ensure the app exists (without deployment-specific data)
   let { data: app, error: updateError } = await c.db
@@ -275,32 +277,34 @@ async function updateDatabase({
     const regularRoutes = toInsert.filter((r) => !r.custom_domain);
 
     // For custom domains, use the promote functionality (update existing routes only)
-
-    await Promise.all(
-      customDomainRoutes.map(async (route) => {
-        try {
-          await promoteDeployment(c, {
-            deploymentId: deployment.id,
-            routePattern: route.route_pattern,
-            force,
-          });
-        } catch (error) {
-          // If route doesn't exist, create it (only during initial deployment)
-          if (error instanceof NotFoundError) {
-            const { error: insertError } = await c.db
-              .from(DECO_CHAT_HOSTING_ROUTES_TABLE)
-              .insert({
-                deployment_id: deployment.id,
-                route_pattern: route.route_pattern,
-                custom_domain: true,
-              });
-            if (insertError) throw insertError;
-          } else {
-            throw error;
+    // Skip promotion if this is a preview deployment
+    if (promote) {
+      await Promise.all(
+        customDomainRoutes.map(async (route) => {
+          try {
+            await promoteDeployment(c, {
+              deploymentId: deployment.id,
+              routePattern: route.route_pattern,
+              force,
+            });
+          } catch (error) {
+            // If route doesn't exist, create it (only during initial deployment)
+            if (error instanceof NotFoundError) {
+              const { error: insertError } = await c.db
+                .from(DECO_CHAT_HOSTING_ROUTES_TABLE)
+                .insert({
+                  deployment_id: deployment.id,
+                  route_pattern: route.route_pattern,
+                  custom_domain: true,
+                });
+              if (insertError) throw insertError;
+            } else {
+              throw error;
+            }
           }
-        }
-      }),
-    );
+        }),
+      );
+    }
     // For regular routes (non-custom domains), just insert them in batch
     if (regularRoutes.length > 0) {
       const { error: insertError } = await c.db
@@ -446,6 +450,8 @@ export const deployFiles = createTool({
   name: "HOSTING_APP_DEPLOY",
   description: `Deploy multiple TypeScript files that use Wrangler for bundling and deployment to Cloudflare Workers. You must provide a package.json file with the necessary dependencies and a wrangler.toml file matching the Workers for Platforms format. Use 'main_module' instead of 'main', and define bindings using the [[bindings]] array, where each binding is a table specifying its type and properties. To add custom Deco bindings, set type = "MCP" in a binding entry (these will be filtered and handled automatically).
 
+Set 'preview: true' to create a preview deployment that won't replace the production version. Preview deployments get their own unique URL but are not promoted to production routes.
+
 Common patterns:
 1. Use a package.json file to manage dependencies:
    // package.json
@@ -649,6 +655,13 @@ Important Notes:
         "If true, force the deployment even if there are breaking changes",
       )
       .optional(),
+    promote: z
+      .boolean()
+      .describe(
+        "If true, promotes the deployment to production routes. The deployment will be available at a unique URL but won't replace the production version.",
+      )
+      .optional()
+      .default(true),
     appSlug: z
       .string()
       .optional()
@@ -694,6 +707,7 @@ Important Notes:
   handler: async (
     {
       force,
+      promote = true,
       appSlug: _appSlug,
       files,
       envVars,
@@ -726,6 +740,7 @@ Important Notes:
         : ({ name: _appSlug } as WranglerConfig);
 
       addDefaultCustomDomain(wranglerConfig);
+
       // check if the entrypoint is in the files
       const entrypoints = [
         ...ENTRYPOINTS,
@@ -851,6 +866,7 @@ Important Notes:
       const data = await updateDatabase({
         c,
         force,
+        promote,
         workspace,
         scriptSlug,
         result,
@@ -877,12 +893,20 @@ Important Notes:
             throw err;
           }
         });
+
+      const hosts = [];
+
+      if (promote) {
+        hosts.push(data.entrypoint);
+      }
+
+      if (deploymentId) {
+        hosts.push(Entrypoint.build(data.slug!, deploymentId));
+      }
+
       return {
         entrypoint: data.entrypoint,
-        hosts: [
-          data.entrypoint,
-          ...(deploymentId ? [Entrypoint.build(data.slug!, deploymentId)] : []),
-        ],
+        hosts,
         id: data.id,
         workspace: data.workspace,
         deploymentId,