feat: Add DEPLOY_IMAGE_OVERRIDE env var for custom image references

Allow users to specify a custom image reference via DEPLOY_IMAGE_OVERRIDE
environment variable instead of using the auto-generated format. When set,
all deployments use this exact image reference, enabling workflows with
externally-built images or custom naming schemes.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: ConProgramming

apps/webapp/app/env.server.ts

@@ -240,6 +240,10 @@ const EnvironmentSchema = z.object({
   DEPLOY_REGISTRY_ECR_ASSUME_ROLE_EXTERNAL_ID: z.string().optional(),
   DEPLOY_IMAGE_PLATFORM: z.string().default("linux/amd64"),
   DEPLOY_VERSION_SUFFIX: z.string().optional(), // Optional suffix for deployment versions, e.g., "hardened"
+  // 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

@@ -69,34 +69,51 @@ export class InitializeDeploymentService extends BaseService {
           })
         : undefined;
 
-      const [imageRefError, imageRefResult] = await tryCatch(
-        getDeploymentImageRef({
-          host: env.DEPLOY_REGISTRY_HOST,
-          namespace: env.DEPLOY_REGISTRY_NAMESPACE,
-          projectRef: environment.project.externalRef,
-          nextVersion,
-          environmentSlug: environment.slug,
-          registryTags: env.DEPLOY_REGISTRY_ECR_TAGS,
-          assumeRole: {
-            roleArn: env.DEPLOY_REGISTRY_ECR_ASSUME_ROLE_ARN,
-            externalId: env.DEPLOY_REGISTRY_ECR_ASSUME_ROLE_EXTERNAL_ID,
-          },
-        })
-      );
+      // If DEPLOY_IMAGE_OVERRIDE is set, use it instead of generating an image reference
+      let imageRef: string;
+      let isEcr = false;
+      let repoCreated = false;
 
-      if (imageRefError) {
-        logger.error("Failed to get deployment image ref", {
+      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({
+            host: env.DEPLOY_REGISTRY_HOST,
+            namespace: env.DEPLOY_REGISTRY_NAMESPACE,
+            projectRef: environment.project.externalRef,
+            nextVersion,
+            environmentSlug: environment.slug,
+            registryTags: env.DEPLOY_REGISTRY_ECR_TAGS,
+            assumeRole: {
+              roleArn: env.DEPLOY_REGISTRY_ECR_ASSUME_ROLE_ARN,
+              externalId: env.DEPLOY_REGISTRY_ECR_ASSUME_ROLE_EXTERNAL_ID,
+            },
+          })
+        );
 
-      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;
+      }
 
       logger.debug("Creating deployment", {
         environmentId: environment.id,