[release] Add prebuilt deploy mode for functions and sites

Opt-in mode that bypasses Appwrite's server-side build container entirely:
runs the build locally, ships node_modules / dist inside the tarball, and
tells Appwrite to skip its build step (empty commands sent to
createDeployment). Removes the need for a GitHub installation / token on
Appwrite when functions or sites pull private GitHub-hosted dependencies.

Default behavior is unchanged. Enable per-resource by setting
`prebuilt: true` in .fnconfig.yaml / config.yaml, or per single-function
CLI deploy with --prebuilt. The deploy-functions GitHub Action gains a
`prebuilt` input, and the MCP `deploy_functions` tool gains an optional
`prebuilt` flag that forces the whole batch.

When prebuilt:
  - functions: `commands` runs locally in the deploy dir before tarring.
  - sites:     `installCommand` then `buildCommand` run locally.
  - ignore list shrinks to .git/.vscode/.DS_Store so built artifacts ship
    (user's explicit `ignore` still wins).
  - createDeployment receives empty commands so Appwrite does nothing
    server-side.

Schema fields added to AppwriteFunctionSchema and AppwriteSiteSchema; the
field is optional and undefined falls back to the existing
build-on-Appwrite path.

Author: ZachHandley

actions/_shared/run.ts

@@ -92,6 +92,8 @@ function buildArgv(): string[] {
       if (enabled !== undefined) argv.push(`--functionEnabled=${enabled}`);
       const logging = env("AWU_FN_LOGGING");
       if (logging !== undefined) argv.push(`--functionLogging=${logging}`);
+      const prebuilt = env("AWU_PREBUILT");
+      if (prebuilt !== undefined) argv.push(`--prebuilt=${prebuilt}`);
       break;
     }
     case "push": {

actions/deploy-functions/action.yml

@@ -84,6 +84,10 @@ inputs:
     description: "Override whether function logging is enabled (true/false)."
     required: false
     default: ""
+  prebuilt:
+    description: "Single-function override: run the function's build commands LOCALLY before tarring, ship node_modules/dist inside the tarball, and tell Appwrite to skip its build step. Bypasses Appwrite's build container entirely so private GitHub deps don't need an installation/GitHub token on Appwrite. (true/false)"
+    required: false
+    default: ""
 
 runs:
   using: "composite"
@@ -116,3 +120,4 @@ runs:
         AWU_FN_EXECUTE: ${{ inputs.execute }}
         AWU_FN_ENABLED: ${{ inputs.enabled }}
         AWU_FN_LOGGING: ${{ inputs.logging }}
+        AWU_PREBUILT: ${{ inputs.prebuilt }}

packages/appwrite-utils-cli/src/cli/commands/deployFunctionsFlow.ts

@@ -40,6 +40,12 @@ export interface DeployFunctionFieldOverrides {
   ignore?: string;
   /** Comma-separated domains for --functionDomains. Reconciled after deploy. */
   domains?: string;
+  /**
+   * When true (from --prebuilt), run the function's `commands` locally and
+   * ship the resulting build artifacts inside the tarball; Appwrite is told
+   * to skip its build step. Single-function only.
+   */
+  prebuilt?: boolean;
 }
 
 export interface DeployFunctionsFlowOptions {
@@ -208,6 +214,7 @@ function applyOverrides(
   if (overrides.deployDir !== undefined) next.deployDir = overrides.deployDir;
   if (overrides.ignore !== undefined) next.ignore = splitCsv(overrides.ignore);
   if (overrides.domains !== undefined) next.domains = splitCsv(overrides.domains);
+  if (overrides.prebuilt !== undefined) next.prebuilt = overrides.prebuilt;
   return next;
 }
 

packages/appwrite-utils-cli/src/functions/deployments.ts

@@ -30,6 +30,11 @@ const DEFAULT_IGNORED = [
   ".venv",
 ];
 
+// Slimmer ignore list for `prebuilt: true` deploys: built artifacts
+// (node_modules, .venv, __pycache__) MUST ship so Appwrite can skip its
+// build step entirely. Only strip VCS/editor noise.
+const PREBUILT_IGNORED = [".git", ".vscode", ".DS_Store"];
+
 /**
  * Upload-only phase of a deployment: tars + uploads the function source and
  * creates the deployment record. Does NOT wait for the build to finish and
@@ -225,8 +230,13 @@ export interface PreparedFunctionDeployment {
   functionName: string;
   deployPath: string;
   entrypoint: string;
+  /**
+   * Commands string sent to Appwrite's createDeployment. Empty when the
+   * function is prebuilt — Appwrite skips the build step entirely.
+   */
   commands: string;
   ignored: string[];
+  prebuilt: boolean;
 }
 
 /**
@@ -264,9 +274,10 @@ export const prepareFunctionDeployment = async (
     throw new Error(`Function directory is invalid or missing required files: ${resolvedPath}`);
   }
 
+  const isWindows = platform() === "win32";
+
   if (functionConfig.predeployCommands?.length) {
     MessageFormatter.processing("Executing predeploy commands...", { prefix: "Deployment" });
-    const isWindows = platform() === "win32";
 
     for (const command of functionConfig.predeployCommands) {
       try {
@@ -299,13 +310,46 @@ export const prepareFunctionDeployment = async (
     ? join(resolvedPath, functionConfig.deployDir)
     : resolvedPath;
 
+  // Prebuilt mode: run the function's build commands locally now (in deployPath
+  // so the built artifacts land alongside the source we're about to tar), then
+  // tell Appwrite to skip its build step by passing empty commands.
+  const prebuilt = functionConfig.prebuilt === true;
+  if (prebuilt && functionConfig.commands && functionConfig.commands.trim().length > 0) {
+    MessageFormatter.processing(
+      `[prebuilt] Running build locally: ${functionConfig.commands}`,
+      { prefix: "Deployment" }
+    );
+    try {
+      execSync(functionConfig.commands, {
+        cwd: deployPath,
+        stdio: "inherit",
+        shell: isWindows ? "cmd.exe" : "/bin/sh",
+        windowsHide: true,
+      });
+    } catch (error) {
+      MessageFormatter.error(
+        `[prebuilt] Local build failed: ${functionConfig.commands}`,
+        error instanceof Error ? error : undefined,
+        { prefix: "Deployment" }
+      );
+      throw error;
+    }
+  }
+
+  // Pick the ignore list. User-supplied `ignore` always wins. Otherwise:
+  //   - prebuilt: slim list (ship node_modules, .venv, __pycache__)
+  //   - normal:   classic DEFAULT_IGNORED (strip those)
+  const ignored =
+    functionConfig.ignore ?? (prebuilt ? PREBUILT_IGNORED : DEFAULT_IGNORED);
+
   return {
     functionId: functionConfig.$id,
     functionName,
     deployPath,
     entrypoint: functionConfig.entrypoint ?? "main.js",
-    commands: functionConfig.commands ?? "npm install",
-    ignored: functionConfig.ignore ?? DEFAULT_IGNORED,
+    commands: prebuilt ? "" : (functionConfig.commands ?? "npm install"),
+    ignored,
+    prebuilt,
   };
 };
 

packages/appwrite-utils-cli/src/main.ts

@@ -93,6 +93,7 @@ interface CliOptions {
   functionDeployDir?: string;
   functionIgnore?: string;
   functionDomains?: string;
+  prebuilt?: boolean;
   pruneDomains?: boolean;
   listRules?: string;
   createRule?: boolean;
@@ -740,6 +741,11 @@ const argv = yargs(hideBin(process.argv))
     type: "string",
     description: "Comma-separated custom domains to attach as Appwrite Proxy Rules during --deployFunctions. For single-function deploys, overrides the config's domains[]. For multi-function deploys, each function's declared domains[] is reconciled.",
   })
+  .option("prebuilt", {
+    alias: ["function-prebuilt", "functionPrebuilt"],
+    type: "boolean",
+    description: "Single-function --deployFunctions override: run the function's `commands` (build step) LOCALLY before tarring, ship the resulting node_modules/dist inside the tarball, and tell Appwrite to skip its build step (empty commands sent to createDeployment). Bypasses Appwrite's build container entirely so private GitHub deps don't need an installation/GitHub token on Appwrite. For multi-function deploys, set `prebuilt: true` per-function in .fnconfig.yaml / config.yaml instead.",
+  })
   .option("pruneDomains", {
     alias: ["prune-domains"],
     type: "boolean",
@@ -1195,6 +1201,7 @@ async function main() {
           deployDir: argv.functionDeployDir,
           ignore: argv.functionIgnore,
           domains: argv.functionDomains,
+          prebuilt: argv.prebuilt,
         },
         pruneDomains: argv.pruneDomains,
       });

packages/appwrite-utils-cli/src/sites/deployments.ts

@@ -18,6 +18,18 @@ import {
 import { MessageFormatter } from "appwrite-utils-helpers";
 import { resolveFunctionDirectory, validateFunctionDirectory } from "appwrite-utils-helpers";
 
+const DEFAULT_SITE_IGNORED = [
+  "node_modules",
+  ".git",
+  ".vscode",
+  ".DS_Store",
+  "__pycache__",
+  ".venv",
+];
+
+// Slim ignore for prebuilt site deploys: ship built artifacts.
+const PREBUILT_SITE_IGNORED = [".git", ".vscode", ".DS_Store"];
+
 export const deploySite = async (
   client: Client,
   siteId: string,
@@ -26,14 +38,7 @@ export const deploySite = async (
   installCommand?: string,
   buildCommand?: string,
   outputDirectory?: string,
-  ignored: string[] = [
-    "node_modules",
-    ".git",
-    ".vscode",
-    ".DS_Store",
-    "__pycache__",
-    ".venv",
-  ]
+  ignored: string[] = DEFAULT_SITE_IGNORED
 ) => {
   const sites = new Sites(client);
   MessageFormatter.processing("Preparing site deployment...", { prefix: "Deployment" });
@@ -196,9 +201,10 @@ export const deployLocalSite = async (
     throw new Error(`Site directory is invalid or missing required files: ${resolvedPath}`);
   }
 
+  const isWindows = platform() === "win32";
+
   if (siteConfig.predeployCommands?.length) {
     MessageFormatter.processing("Executing predeploy commands...", { prefix: "Deployment" });
-    const isWindows = platform() === "win32";
 
     for (const command of siteConfig.predeployCommands) {
       try {
@@ -232,14 +238,47 @@ export const deployLocalSite = async (
     ? join(resolvedPath, siteConfig.deployDir)
     : resolvedPath;
 
+  // Prebuilt mode: run installCommand then buildCommand locally in deployPath
+  // so the build output (dist/, .output/, etc.) lands inside the tarball.
+  // Appwrite is then told to skip its build step (empty install+build commands).
+  const prebuilt = siteConfig.prebuilt === true;
+  if (prebuilt) {
+    const localSteps: Array<{ label: string; command?: string }> = [
+      { label: "install", command: siteConfig.installCommand },
+      { label: "build", command: siteConfig.buildCommand },
+    ];
+    for (const step of localSteps) {
+      if (!step.command || step.command.trim().length === 0) continue;
+      MessageFormatter.processing(
+        `[prebuilt] Running ${step.label} locally: ${step.command}`,
+        { prefix: "Deployment" }
+      );
+      try {
+        execSync(step.command, {
+          cwd: deployPath,
+          stdio: "inherit",
+          shell: isWindows ? "cmd.exe" : "/bin/sh",
+          windowsHide: true,
+        });
+      } catch (error) {
+        MessageFormatter.error(
+          `[prebuilt] Local ${step.label} failed: ${step.command}`,
+          error instanceof Error ? error : undefined,
+          { prefix: "Deployment" }
+        );
+        throw error;
+      }
+    }
+  }
+
   return deploySite(
     client,
     siteConfig.$id,
     deployPath,
     true,
-    siteConfig.installCommand,
-    siteConfig.buildCommand,
+    prebuilt ? "" : siteConfig.installCommand,
+    prebuilt ? "" : siteConfig.buildCommand,
     siteConfig.outputDirectory,
-    siteConfig.ignore
+    siteConfig.ignore ?? (prebuilt ? PREBUILT_SITE_IGNORED : DEFAULT_SITE_IGNORED)
   );
 };

packages/appwrite-utils-helpers/src/functions/functionManager.ts

@@ -72,6 +72,15 @@ export interface FunctionDeploymentOptions {
   commands?: string;
   ignored?: string[];
   verbose?: boolean;
+  /**
+   * When true (or when `functionConfig.prebuilt === true`), run the function's
+   * `commands` LOCALLY before tarring, ship the resulting build artifacts
+   * inside the tarball (slim ignore list), and tell Appwrite to skip its
+   * build step (empty commands sent to createDeployment). Bypasses Appwrite's
+   * build container entirely so private GitHub deps don't need an
+   * installation/GitHub token on Appwrite.
+   */
+  prebuilt?: boolean;
   /**
    * @deprecated The function config is now always pushed when the function
    * exists; this flag is retained for back-compat and is a no-op.
@@ -315,18 +324,31 @@ export class FunctionManager {
     functionPath: string,
     options: FunctionDeploymentOptions = {}
   ): Promise<Models.Deployment> {
+    const prebuilt =
+      options.prebuilt === true || functionConfig.prebuilt === true;
     const {
       activate = true,
       entrypoint = functionConfig.entrypoint || "main.js",
-      commands = functionConfig.commands || "npm install",
-      ignored = ["node_modules", ".git", ".vscode", ".DS_Store", "__pycache__", ".venv"],
       verbose = false,
     } = options;
+    // commands/ignored have prebuilt-aware defaults: empty commands so Appwrite
+    // skips its build, slim ignore so built artifacts ship.
+    const commands =
+      options.commands ??
+      (prebuilt ? "" : functionConfig.commands || "npm install");
+    const ignored =
+      options.ignored ??
+      (prebuilt
+        ? [".git", ".vscode", ".DS_Store"]
+        : ["node_modules", ".git", ".vscode", ".DS_Store", "__pycache__", ".venv"]);
 
     if (verbose) {
       MessageFormatter.processing(`Uploading function: ${functionConfig.name}`, { prefix: "Functions" });
       MessageFormatter.debug(`Path: ${functionPath}`, undefined, { prefix: "Functions" });
       MessageFormatter.debug(`Entrypoint: ${entrypoint}`, undefined, { prefix: "Functions" });
+      if (prebuilt) {
+        MessageFormatter.debug(`Mode: prebuilt (local build; Appwrite skips build step)`, undefined, { prefix: "Functions" });
+      }
     }
 
     if (!await this.isValidFunctionDirectory(functionPath)) {
@@ -353,6 +375,18 @@ export class FunctionManager {
       await this.executePredeployCommands(functionConfig.predeployCommands, functionPath, { verbose });
     }
 
+    // Prebuilt: run the build LOCALLY in functionPath so artifacts land
+    // alongside source before tarring.
+    if (prebuilt && functionConfig.commands && functionConfig.commands.trim().length > 0) {
+      if (verbose) {
+        MessageFormatter.processing(
+          `[prebuilt] Running build locally: ${functionConfig.commands}`,
+          { prefix: "Functions" }
+        );
+      }
+      await this.executePredeployCommands([functionConfig.commands], functionPath, { verbose });
+    }
+
     return await this.createDeployment(
       functionConfig.$id,
       functionPath,

packages/appwrite-utils-helpers/src/sites/siteManager.ts

@@ -24,6 +24,13 @@ export interface SiteDeploymentOptions {
   outputDirectory?: string;
   ignored?: string[];
   verbose?: boolean;
+  /**
+   * When true (or `siteConfig.prebuilt === true`), run installCommand then
+   * buildCommand LOCALLY in the site directory before tarring, ship the
+   * build output (dist/, .output/, node_modules) inside the tarball, and
+   * tell Appwrite to skip its build step (empty install+build commands).
+   */
+  prebuilt?: boolean;
   /**
    * @deprecated The site config is now always pushed when the site exists;
    * this flag is retained for back-compat and is a no-op.
@@ -244,15 +251,26 @@ export class SiteManager {
     sitePath: string,
     options: SiteDeploymentOptions = {}
   ): Promise<Models.Deployment> {
+    const prebuilt =
+      options.prebuilt === true || siteConfig.prebuilt === true;
     const {
       activate = true,
-      installCommand = siteConfig.installCommand,
-      buildCommand = siteConfig.buildCommand,
       outputDirectory = siteConfig.outputDirectory,
-      ignored = ["node_modules", ".git", ".vscode", ".DS_Store", "__pycache__", ".venv"],
       verbose = false,
       pollOptions,
     } = options;
+    // installCommand/buildCommand/ignored have prebuilt-aware defaults:
+    // empty install+build so Appwrite skips its build; slim ignore so built
+    // artifacts ship.
+    const installCommand =
+      options.installCommand ?? (prebuilt ? "" : siteConfig.installCommand);
+    const buildCommand =
+      options.buildCommand ?? (prebuilt ? "" : siteConfig.buildCommand);
+    const ignored =
+      options.ignored ??
+      (prebuilt
+        ? [".git", ".vscode", ".DS_Store"]
+        : ["node_modules", ".git", ".vscode", ".DS_Store", "__pycache__", ".venv"]);
 
     return await siteLimit(async () => {
       if (verbose) {
@@ -290,6 +308,25 @@ export class SiteManager {
         await this.executePredeployCommands(siteConfig.predeployCommands, sitePath, { verbose });
       }
 
+      // Prebuilt: run installCommand then buildCommand LOCALLY in sitePath so
+      // the build output lands inside the tarball.
+      if (prebuilt) {
+        const localSteps: Array<{ label: string; command?: string }> = [
+          { label: "install", command: siteConfig.installCommand },
+          { label: "build", command: siteConfig.buildCommand },
+        ];
+        for (const step of localSteps) {
+          if (!step.command || step.command.trim().length === 0) continue;
+          if (verbose) {
+            MessageFormatter.processing(
+              `[prebuilt] Running ${step.label} locally: ${step.command}`,
+              { prefix: "Sites" }
+            );
+          }
+          await this.executePredeployCommands([step.command], sitePath, { verbose });
+        }
+      }
+
       // Deploy the site
       const deployment = await this.createDeployment(siteConfig.$id, sitePath, {
         activate,