feat(webapp): add DEPLOY_IMAGE_OVERRIDE env var for custom image references

When set, bypasses auto-generation of image tags and uses the provided
image reference directly for all deployments.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

apps/webapp/app/env.server.ts

@@ -345,6 +345,10 @@ const EnvironmentSchema = z
 
     DEPLOY_IMAGE_PLATFORM: z.string().default("linux/amd64"),
     DEPLOY_VERSION_SUFFIX: z.string().optional(),
+    // Full image reference override - bypasses auto-generation of image tags
+    // When set, all deployments will use this exact image reference
+    // Example: "myregistry.com/myorg/myapp:1.0.5"
+    DEPLOY_IMAGE_OVERRIDE: z.string().optional(),
     DEPLOY_TIMEOUT_MS: z.coerce
       .number()
       .int()

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

@@ -146,29 +146,46 @@ export class InitializeDeploymentService extends BaseService {
 
       const deploymentShortCode = nanoid(8);
 
-      const [imageRefError, imageRefResult] = await tryCatch(
-        getDeploymentImageRef({
-          registry: registryConfig,
-          projectRef: environment.project.externalRef,
-          nextVersion,
-          environmentType: environment.type,
-          deploymentShortCode,
-        })
-      );
-
-      if (imageRefError) {
-        logger.error("Failed to get deployment image ref", {
+      // If DEPLOY_IMAGE_OVERRIDE is set, use it instead of generating an image reference
+      let imageRef: string;
+      let isEcr = false;
+      let repoCreated = false;
+
+      if (env.DEPLOY_IMAGE_OVERRIDE) {
+        imageRef = env.DEPLOY_IMAGE_OVERRIDE;
+        logger.info("Using image override", {
+          imageRef,
           environmentId: environment.id,
           projectId: environment.projectId,
           version: nextVersion,
-          triggeredById: triggeredBy?.id,
-          type: payload.type,
-          cause: imageRefError.message,
         });
-        throw new ServiceValidationError("Failed to get deployment image ref");
-      }
+      } else {
+        const [imageRefError, imageRefResult] = await tryCatch(
+          getDeploymentImageRef({
+            registry: registryConfig,
+            projectRef: environment.project.externalRef,
+            nextVersion,
+            environmentType: environment.type,
+            deploymentShortCode,
+          })
+        );
 
-      const { imageRef, isEcr, repoCreated } = imageRefResult;
+        if (imageRefError) {
+          logger.error("Failed to get deployment image ref", {
+            environmentId: environment.id,
+            projectId: environment.projectId,
+            version: nextVersion,
+            triggeredById: triggeredBy?.id,
+            type: payload.type,
+            cause: imageRefError.message,
+          });
+          throw new ServiceValidationError("Failed to get deployment image ref");
+        }
+
+        imageRef = imageRefResult.imageRef;
+        isEcr = imageRefResult.isEcr;
+        repoCreated = imageRefResult.repoCreated;
+      }
 
       // We keep using `BUILDING` as the initial status if not explicitly set
       // to avoid changing the behavior for deployments not created in the build server.