@@ -0,0 +1,23 @@
+---
+"trigger.dev": patch
+---
+
+`trigger.dev deploy` can now carry an id of your own choosing, such as a commit SHA, a CI run id or a release tag:
+
+```bash
+trigger.dev deploy --external-id $GITHUB_SHA
+```
+
+Give the same value to your running app (see `TRIGGER_EXTERNAL_DEPLOYMENT_ID`) and every task it triggers runs on that deployment, so a request served by an old release never triggers tasks from a new one.
+
+**Deploying an id that has already been deployed doesn't build an image**: the command reports the existing version, sets the same GitHub Actions outputs a normal deploy would, and exits successfully without pushing anything. A pipeline that re-runs for a commit it already deployed gets that version back instead of a second identical deployment.
+
+**If a build for that id is still running**, the deploy is rejected and tells you which version is already in flight, so two builds never race to define one id.
+
+**Ids that only ever failed, timed out or were cancelled always build again**, so retrying a broken build just works. Note that a failed build leaves the id undeployed: runs triggered with it wait, and expire after an hour if you never land a successful build for it.
+
+The id is at most 128 characters, which fits a SHA-256 commit hash with room to spare.
+
+Pass `--force` alongside `--external-id` to build again even when that id is already deployed. Deployments that already succeeded are left alone and both are kept — new runs triggered with that id go to the highest version, so the rebuild takes over once it lands. A build that is still in flight is cancelled instead, so one id never has two live builds racing to define it. `--force` on its own is rejected, since there is nothing for it to act on.
+
+Deploys that pass no `--external-id` are unaffected.
@@ -65,6 +65,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
       externalBuildData:
         deployment.externalBuildData as GetDeploymentResponseBody["externalBuildData"],
       errorData: deployment.errorData as GetDeploymentResponseBody["errorData"],
+      canceledReason: deployment.canceledReason,
       worker: deployment.worker
         ? {
             id: deployment.worker.friendlyId,
 
@@ -42,24 +42,32 @@ export async function action({ request, params }: ActionFunctionArgs) {
   const service = new InitializeDeploymentService();
 
   try {
-    const { deployment, imageRef, eventStream } = await service.call(authenticatedEnv, body.data);
+    const result = await service.call(authenticatedEnv, body.data);
+    const { deployment, imageRef } = result;
 
     const responseBody: InitializeDeploymentResponseBody = {
       id: deployment.friendlyId,
       contentHash: deployment.contentHash,
       shortCode: deployment.shortCode,
       version: deployment.version,
-      externalBuildData:
-        deployment.externalBuildData as InitializeDeploymentResponseBody["externalBuildData"],
       imageTag: imageRef,
       imagePlatform: deployment.imagePlatform,
-      eventStream,
+      externalId: deployment.externalId ?? undefined,
+      outcome: result.outcome,
+      ...(result.outcome === "created"
+        ? {
+            externalBuildData: result.deployment
+              .externalBuildData as InitializeDeploymentResponseBody["externalBuildData"],
+            eventStream: result.eventStream,
+            canceledDeployments: result.canceledDeployments,
+          }
+        : {}),
     };
 
     return json(responseBody, { status: 200 });
   } catch (error) {
     if (error instanceof ServiceValidationError) {
-      return json({ error: error.message }, { status: 400 });
+      return json({ error: error.message }, { status: error.status ?? 400 });
     }
 
     logger.error("Error initializing deployment", { error });
 
@@ -16,16 +16,52 @@ import { tryCatch } from "@trigger.dev/core";
 import { getRegistryConfig } from "../registryConfig.server";
 import { DeploymentService } from "./deployment.server";
 import { createDeploymentWithNextVersion } from "./initializeDeployment/createDeploymentWithNextVersion.server";
+import {
+  cancelSupersededDeployments,
+  type SupersededDeployment,
+} from "./initializeDeployment/cancelSupersededDeployments.server";
+import {
+  resolveExternalIdReuse,
+  type ExternalIdReuseDeployment,
+} from "./initializeDeployment/resolveExternalIdReuse.server";
+import { type WorkerDeployment } from "@trigger.dev/database";
 import { errAsync } from "neverthrow";
 
 const nanoid = customAlphabet("1234567890abcdefghijklmnopqrstuvwxyz", 8);
 
+type DeploymentEventStream = {
+  s2: {
+    basin: string;
+    stream: string;
+    accessToken: string;
+  };
+};
+
+export type InitializeDeploymentResult =
+  | {
+      outcome: "created";
+      deployment: WorkerDeployment;
+      imageRef: string;
+      eventStream?: DeploymentEventStream;
+      canceledDeployments?: SupersededDeployment[];
+    }
+  | {
+      outcome: "existing";
+      deployment: ExternalIdReuseDeployment;
+      imageRef: string;
+    };
+
 export class InitializeDeploymentService extends BaseService {
   public async call(
     environment: AuthenticatedEnvironment,
     payload: InitializeDeploymentRequestBody
-  ) {
-    return this.traceWithEnv("call", environment, async () => {
+  ): Promise<InitializeDeploymentResult> {
+    return this.traceWithEnv("call", environment, async (span) => {
+      if (payload.externalId) {
+        span.setAttribute("externalId", payload.externalId);
+      }
+      span.setAttribute("force", payload.force ?? false);
+
       if (payload.gitMeta?.commitSha?.startsWith("deployment_")) {
         // When we introduced automatic deployments via the build server, we slightly changed the deployment flow
         // mainly in the initialization and starting step: now deployments are first initialized in the `PENDING` status
@@ -39,6 +75,13 @@ export class InitializeDeploymentService extends BaseService {
         // build server experience for users with older CLI versions. We'll eventually be able to remove this workaround
         // once we stop supporting 3.x CLI versions.
 
+        if (payload.externalId || payload.force) {
+          throw new ServiceValidationError(
+            "externalId and force are not supported when attaching to an existing deployment",
+            400
+          );
+        }
+
         const existingDeploymentId = payload.gitMeta.commitSha;
         const existingDeployment = await this._prisma.workerDeployment.findFirst({
           where: {
@@ -53,7 +96,10 @@ export class InitializeDeploymentService extends BaseService {
           );
         }
 
+        span.setAttribute("outcome", "created");
+
         return {
+          outcome: "created",
           deployment: existingDeployment,
           imageRef: existingDeployment.imageReference ?? "",
         };
@@ -103,6 +149,55 @@ export class InitializeDeploymentService extends BaseService {
         );
       }
 
+      const deploymentService = new DeploymentService();
+
+      const reuse = await resolveExternalIdReuse({
+        prisma: this._prisma,
+        environmentId: environment.id,
+        externalId: payload.externalId,
+        force: payload.force,
+      });
+
+      if (reuse.action === "reject") {
+        span.setAttribute("outcome", "rejected");
+
+        throw new ServiceValidationError(
+          `A deployment for external id "${payload.externalId}" is already in progress (version ${reuse.deployment.version}). Wait for it to finish, or deploy again with --force to cancel it and start a new one.`,
+          409
+        );
+      }
+
+      if (reuse.action === "short-circuit") {
+        span.setAttribute("outcome", "existing");
+
+        logger.debug("Reusing deployed external id, skipping build", {
+          environmentId: environment.id,
+          projectId: environment.projectId,
+          externalId: payload.externalId,
+          version: reuse.deployment.version,
+        });
+
+        return {
+          outcome: "existing",
+          deployment: reuse.deployment,
+          imageRef: reuse.deployment.imageReference ?? "",
+        };
+      }
+
+      span.setAttribute("outcome", "created");
+
+      const canceledDeployments =
+        reuse.action === "cancel-then-build"
+          ? await cancelSupersededDeployments({
+              deploymentService,
+              environmentId: environment.id,
+              externalId: reuse.externalId,
+              deployments: reuse.deployments,
+            })
+          : [];
+
+      span.setAttribute("canceledDeploymentCount", canceledDeployments.length);
+
       // For the `PENDING` initial status, defer the creation of the Depot build until the deployment is started to avoid token expiration issues.
       // For local and native builds we don't need to generate the Depot tokens. We still need to create an empty object sadly due to a bug in older CLI versions.
       const generateExternalBuildToken =
@@ -140,7 +235,6 @@ export class InitializeDeploymentService extends BaseService {
       const initialStatus =
         payload.initialStatus ?? (payload.isNativeBuild ? "PENDING" : "BUILDING");
 
-      const deploymentService = new DeploymentService();
       const s2StreamOrFail = await deploymentService
         .createEventStream(environment.project, { shortCode: deploymentShortCode })
         .andThen(({ basin, stream }) =>
@@ -253,6 +347,7 @@ export class InitializeDeploymentService extends BaseService {
             imagePlatform: env.DEPLOY_IMAGE_PLATFORM,
             git: payload.gitMeta ?? undefined,
             commitSHA: payload.gitMeta?.commitSha ?? undefined,
+            externalId: payload.externalId,
             runtime: payload.runtime ?? environment.project.defaultRuntime ?? undefined,
             triggeredVia: payload.triggeredVia ?? undefined,
             startedAt: initialStatus === "BUILDING" ? new Date() : undefined,
@@ -307,9 +402,11 @@ export class InitializeDeploymentService extends BaseService {
       }
 
       return {
+        outcome: "created",
         deployment,
         imageRef: deployment.imageReference ?? "",
         eventStream,
+        canceledDeployments,
       };
     });
   }
 
@@ -0,0 +1,70 @@
+import { logger } from "~/services/logger.server";
+import { ServiceValidationError } from "~/v3/services/baseService.server";
+import type { DeploymentService } from "../deployment.server";
+import type { ExternalIdReuseDeployment } from "./resolveExternalIdReuse.server";
+
+export type SupersededDeployment = Pick<ExternalIdReuseDeployment, "version" | "shortCode">;
+
+export function supersededByForceReason(externalId: string): string {
+  return `Superseded by a new deploy with --force for external id "${externalId}"`;
+}
+
+type CancelSupersededDeploymentsOptions = {
+  deploymentService: DeploymentService;
+  environmentId: string;
+  externalId: string;
+  deployments: ExternalIdReuseDeployment[];
+};
+
+export async function cancelSupersededDeployments({
+  deploymentService,
+  environmentId,
+  externalId,
+  deployments,
+}: CancelSupersededDeploymentsOptions): Promise<SupersededDeployment[]> {
+  const canceled: SupersededDeployment[] = [];
+
+  for (const deployment of deployments) {
+    const result = await deploymentService.cancelDeployment(
+      { id: environmentId },
+      deployment.friendlyId,
+      {
+        canceledReason: supersededByForceReason(externalId),
+      }
+    );
+
+    if (result.isOk()) {
+      canceled.push({ version: deployment.version, shortCode: deployment.shortCode });
+      continue;
+    }
+
+    if (
+      result.error.type === "deployment_cannot_be_cancelled" ||
+      result.error.type === "deployment_not_found"
+    ) {
+      logger.debug("Superseded deployment was already final", {
+        externalId,
+        version: deployment.version,
+        reason: result.error.type,
+      });
+      continue;
+    }
+
+    if (result.error.type === "failed_to_delete_deployment_timeout") {
+      logger.warn("Failed to dequeue the timeout job for a superseded deployment", {
+        externalId,
+        version: deployment.version,
+        error: result.error.cause,
+      });
+      canceled.push({ version: deployment.version, shortCode: deployment.shortCode });
+      continue;
+    }
+
+    throw new ServiceValidationError(
+      `Failed to cancel the in-progress deployment ${deployment.version} holding external id "${externalId}". Nothing was built — try again.`,
+      500
+    );
+  }
+
+  return canceled;
+}
@@ -0,0 +1,91 @@
+import { type PrismaClientOrTransaction, type WorkerDeployment } from "@trigger.dev/database";
+import { compareDeploymentVersions } from "../../utils/deploymentVersions";
+import { FINAL_DEPLOYMENT_STATUSES } from "../failDeployment.server";
+
+const MAX_CANDIDATES = 20;
+
+export type ExternalIdReuseDeployment = Pick<
+  WorkerDeployment,
+  | "id"
+  | "friendlyId"
+  | "shortCode"
+  | "version"
+  | "status"
+  | "contentHash"
+  | "imageReference"
+  | "imagePlatform"
+  | "externalId"
+>;
+
+export type ResolveExternalIdReuseResult =
+  | { action: "build" }
+  | { action: "short-circuit"; deployment: ExternalIdReuseDeployment }
+  | { action: "reject"; deployment: ExternalIdReuseDeployment }
+  | {
+      action: "cancel-then-build";
+      externalId: string;
+      deployments: ExternalIdReuseDeployment[];
+    };
+
+export type ResolveExternalIdReuseOptions = {
+  prisma: PrismaClientOrTransaction;
+  environmentId: string;
+  externalId?: string;
+  force?: boolean;
+};
+
+export async function resolveExternalIdReuse({
+  prisma,
+  environmentId,
+  externalId,
+  force,
+}: ResolveExternalIdReuseOptions): Promise<ResolveExternalIdReuseResult> {
+  if (!externalId) {
+    return { action: "build" };
+  }
+
+  const candidates = await prisma.workerDeployment.findMany({
+    where: { environmentId, externalId },
+    select: {
+      id: true,
+      friendlyId: true,
+      shortCode: true,
+      version: true,
+      status: true,
+      contentHash: true,
+      imageReference: true,
+      imagePlatform: true,
+      externalId: true,
+    },
+    orderBy: { id: "desc" },
+    take: MAX_CANDIDATES,
+  });
+
+  const inFlight = byVersionDesc(
+    candidates.filter((deployment) => !FINAL_DEPLOYMENT_STATUSES.includes(deployment.status))
+  );
+
+  if (force) {
+    return inFlight.length
+      ? { action: "cancel-then-build", externalId, deployments: inFlight }
+      : { action: "build" };
+  }
+
+  if (inFlight.length) {
+    return { action: "reject", deployment: inFlight[0]! };
+  }
+
+  const deployed = byVersionDesc(
+    candidates.filter((deployment) => deployment.status === "DEPLOYED")
+  );
+
+  if (deployed.length) {
+    return { action: "short-circuit", deployment: deployed[0]! };
+  }
+
+  return { action: "build" };
+}
+
+function byVersionDesc(deployments: ExternalIdReuseDeployment[]): ExternalIdReuseDeployment[] {
+  return [...deployments].sort((a, b) => compareDeploymentVersions(b.version, a.version));
+}