feat(core,webapp): return externalId from the deployments API

The column has always existed and the dashboard reads it, but no public endpoint
returned it, so callers had no way to tell which deployment a version skew
protection pin resolves to. It is now on deployments.list(),
deployments.retrieveCurrent() and the single-deployment retrieve.

The list route already loads the whole row, so only the projection changed. The
current-deployment route needed the column added to its select as well.

Also stops that same projection throwing on a deployment with no git metadata:
the response schema rejects null, so one API-created deployment hid every other
row on the page.

GetDeploymentResponseBody uses optional rather than nullish so it stays
assignable to the CLI's narrower InitializeDeploymentResponseBody, which it is
spread into when a deploy attaches to an existing deployment.

Author: 0ski

.changeset/deployments-external-id.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+`deployments.list()` and `deployments.retrieveCurrent()` now return `externalId`, the `--external-id` a deployment was deployed under, so you can tell which deployment a version skew protection pin resolves to. Null for deployments deployed without one.

apps/webapp/app/routes/api.v1.deployments.$deploymentId.ts

@@ -62,6 +62,7 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
       imageReference: deployment.imageReference,
       imagePlatform: deployment.imagePlatform,
       commitSHA: deployment.commitSHA,
+      externalId: deployment.externalId ?? undefined,
       externalBuildData:
         deployment.externalBuildData as GetDeploymentResponseBody["externalBuildData"],
       errorData: deployment.errorData as GetDeploymentResponseBody["errorData"],

apps/webapp/app/routes/api.v1.deployments.current.ts

@@ -29,6 +29,7 @@ export const loader = createLoaderApiRoute(
               deployedAt: true,
               git: true,
               errorData: true,
+              externalId: true,
             },
           },
         },
@@ -49,6 +50,7 @@ export const loader = createLoaderApiRoute(
       deployedAt: deployment.deployedAt ?? undefined,
       git: deployment.git ?? undefined,
       error: deployment.errorData ?? undefined,
+      externalId: deployment.externalId ?? undefined,
     });
   }
 );

apps/webapp/app/routes/api.v1.deployments.ts

@@ -135,8 +135,9 @@ export const loader = createLoaderApiRoute(
         runtimeVersion: deployment.runtimeVersion,
         status: deployment.status,
         deployedAt: deployment.deployedAt,
-        git: deployment.git,
+        git: deployment.git ?? undefined,
         error: deployment.errorData ?? undefined,
+        externalId: deployment.externalId ?? undefined,
       })),
       pagination: {
         next: nextCursor,

docs/v3-openapi.yaml

@@ -895,6 +895,12 @@ paths:
                           type: object
                           nullable: true
                           description: Error data if the deployment failed
+                        externalId:
+                          type: string
+                          nullable: true
+                          description: >-
+                            The external deployment id this deployment was deployed under
+                            (`--external-id`), used by version skew protection to pin runs
                   pagination:
                     type: object
                     properties:

packages/core/src/v3/schemas/api.ts

@@ -921,6 +921,15 @@ export const GetDeploymentResponseBody = z.object({
   imageReference: z.string().nullish(),
   imagePlatform: z.string(),
   commitSHA: z.string().nullish(),
+  /**
+   * The `--external-id` this deployment was deployed under, used by version skew
+   * protection to pin runs. Distinct from `commitSHA`, which is git metadata.
+   *
+   * `optional`, not `nullish`, to stay assignable to the CLI's narrower
+   * `InitializeDeploymentResponseBody` shape, which this is spread into on the
+   * attach-to-existing-deployment path (`cli-v3/src/commands/deploy.ts:1156`).
+   */
+  externalId: z.string().optional(),
   externalBuildData: ExternalBuildData.optional().nullable(),
   errorData: DeploymentErrorData.nullish(),
   canceledReason: z.string().nullish(),
@@ -2201,6 +2210,12 @@ export const ApiDeploymentListResponseItem = z.object({
   deployedAt: z.coerce.date().optional(),
   git: z.record(z.any()).optional(),
   error: DeploymentErrorData.optional(),
+  /**
+   * The `--external-id` this deployment was deployed under, used by version skew
+   * protection to pin runs. Nullish on deployments created without one, and on
+   * servers older than this field.
+   */
+  externalId: z.string().nullish(),
 });
 
 export type ApiDeploymentListResponseItem = z.infer<typeof ApiDeploymentListResponseItem>;