Add service-level destroy endpoint

src/app/api/v2/builds/[uuid]/destroy/route.ts

@@ -25,8 +25,9 @@ import BuildService from 'server/services/build';
  *   put:
  *     summary: Tear down a build environment
  *     description: |
- *       Changes the status of all Deploys, Builds and Deployables associated with the specified
- *       UUID to torn_down. This effectively marks the environment as deleted.
+ *       Queues teardown for the build environment. The worker deletes Kubernetes resources, runs configured
+ *       CLI/Codefresh destroy steps, uninstalls Helm releases, removes the namespace, queues ingress and
+ *       GitHub deployment cleanup, then marks the associated Build and Deploy records as torn_down.
  *     tags:
  *       - Builds
  *     parameters:
@@ -38,7 +39,7 @@ import BuildService from 'server/services/build';
  *         description: The UUID of the environment
  *     responses:
  *       200:
- *         description: Build has been successfully torn down
+ *         description: Build teardown has been successfully queued
  *         content:
  *           application/json:
  *             schema:
@@ -67,7 +68,7 @@ const PutHandler = async (req: NextRequest, { params }: { params: { uuid: string
 
   const buildService = new BuildService();
 
-  const response = await buildService.tearDownBuild(buildUuid);
+  const response = await buildService.destroyBuildEnvironment(buildUuid);
 
   if (response.status === 'success') {
     return successResponse(response, { status: 200 }, req);

src/app/api/v2/builds/[uuid]/services/[name]/destroy/route.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright 2026 GoodRx, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { NextRequest } from 'next/server';
+import { createApiHandler } from 'server/lib/createApiHandler';
+import { errorResponse, successResponse } from 'server/lib/response';
+import DeployCleanupService from 'server/services/deployCleanup';
+
+/**
+ * @openapi
+ * /api/v2/builds/{uuid}/services/{name}/destroy:
+ *   put:
+ *     summary: Destroy a service deployment within an environment
+ *     description: |
+ *       Deletes deploy-scoped infrastructure for a service in a build environment, including Kubernetes
+ *       resources, secrets, Helm releases, and configured CLI/Codefresh destroy steps for the service type.
+ *       Static environments are allowed. When cleanup succeeds, the Deploy record is marked torn_down.
+ *     tags:
+ *       - Services
+ *     parameters:
+ *       - in: path
+ *         name: uuid
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: The UUID of the environment
+ *       - in: path
+ *         name: name
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: The name of the service deployment to destroy
+ *     responses:
+ *       200:
+ *         description: Service deployment has been successfully destroyed
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/DestroyServiceDeploymentSuccessResponse'
+ *       404:
+ *         description: Build or service not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ApiErrorResponse'
+ *       400:
+ *         description: Cleanup failed
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ApiErrorResponse'
+ *       500:
+ *         description: Server error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ApiErrorResponse'
+ */
+const PutHandler = async (req: NextRequest, { params }: { params: { uuid: string; name: string } }) => {
+  const { uuid: buildUuid, name: serviceName } = params;
+
+  const deployCleanupService = new DeployCleanupService();
+
+  const response = await deployCleanupService.destroyServiceDeployment(buildUuid, serviceName);
+
+  if (response.status === 'success') {
+    return successResponse(response, { status: 200 }, req);
+  } else if (response.status === 'not_found') {
+    return errorResponse(response.message, { status: 404 }, req);
+  } else {
+    return errorResponse(response.message, { status: 400 }, req);
+  }
+};
+
+export const PUT = createApiHandler(PutHandler);

src/server/services/__tests__/build.test.ts

@@ -168,7 +168,7 @@ describe('BuildService build response queries', () => {
   function createQueueManager() {
     return {
       registerQueue: jest.fn(() => ({
-        add: jest.fn(),
+        add: mockQueueAdd,
         process: jest.fn(),
         on: jest.fn(),
       })),
@@ -373,6 +373,132 @@ describe('BuildService status updates', () => {
   });
 });
 
+describe('BuildService destroyBuildEnvironment', () => {
+  function createQueueManager() {
+    return {
+      registerQueue: jest.fn(() => ({
+        add: mockQueueAdd,
+        process: jest.fn(),
+        on: jest.fn(),
+      })),
+    };
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('queues build cleanup for worker processing', async () => {
+    const build = {
+      id: 42,
+      uuid: 'sample-build',
+      isStatic: false,
+      status: BuildStatus.DEPLOYED,
+    };
+    const buildQuery = {
+      findOne: jest.fn().mockResolvedValue(build),
+    };
+    const buildService = new BuildService(
+      {
+        models: {
+          Build: {
+            query: jest.fn(() => buildQuery),
+          },
+        },
+      } as any,
+      {} as any,
+      {} as any,
+      createQueueManager() as any
+    );
+    const deleteBuild = jest.spyOn(buildService, 'deleteBuild').mockResolvedValue(undefined);
+
+    const result = await buildService.destroyBuildEnvironment('sample-build');
+
+    expect(buildQuery.findOne).toHaveBeenCalledWith({ uuid: 'sample-build' });
+    expect(deleteBuild).not.toHaveBeenCalled();
+    expect(mockQueueAdd).toHaveBeenCalledWith('delete', {
+      buildId: 42,
+      buildUuid: 'sample-build',
+    });
+    expect(result).toEqual({
+      status: 'success',
+      message: 'Build sample-build teardown has been queued',
+    });
+  });
+
+  test('does not clean up missing builds', async () => {
+    const buildQuery = {
+      findOne: jest.fn().mockResolvedValue(null),
+    };
+    const deployQuery = {
+      where: jest.fn(),
+    };
+    const buildService = new BuildService(
+      {
+        models: {
+          Build: {
+            query: jest.fn(() => buildQuery),
+          },
+          Deploy: {
+            query: jest.fn(() => deployQuery),
+          },
+        },
+      } as any,
+      {} as any,
+      {} as any,
+      createQueueManager() as any
+    );
+    const deleteBuild = jest.spyOn(buildService, 'deleteBuild').mockResolvedValue(undefined);
+
+    await expect(buildService.destroyBuildEnvironment('missing-build')).resolves.toEqual({
+      status: 'not_found',
+      message: 'Build not found for missing-build or is static environment.',
+    });
+
+    expect(deleteBuild).not.toHaveBeenCalled();
+    expect(deployQuery.where).not.toHaveBeenCalled();
+  });
+
+  test('does not clean up static environments', async () => {
+    const build = {
+      id: 42,
+      uuid: 'static-build',
+      isStatic: true,
+      status: BuildStatus.DEPLOYED,
+    };
+    const buildQuery = {
+      findOne: jest.fn().mockResolvedValue(build),
+    };
+    const deployQuery = {
+      where: jest.fn(),
+    };
+    const buildService = new BuildService(
+      {
+        models: {
+          Build: {
+            query: jest.fn(() => buildQuery),
+          },
+          Deploy: {
+            query: jest.fn(() => deployQuery),
+          },
+        },
+      } as any,
+      {} as any,
+      {} as any,
+      createQueueManager() as any
+    );
+    const deleteBuild = jest.spyOn(buildService, 'deleteBuild').mockResolvedValue(undefined);
+
+    await expect(buildService.destroyBuildEnvironment('static-build')).resolves.toEqual({
+      status: 'not_found',
+      message: 'Build not found for static-build or is static environment.',
+    });
+
+    expect(deleteBuild).not.toHaveBeenCalled();
+    expect(deployQuery.where).not.toHaveBeenCalled();
+  });
+});
+
 describe('BuildService stale deploy reconciliation', () => {
   let buildService: BuildService;
   let deployableQuery: any;