feat(webapp): make development environments branchable (API + auth)

Extend branch support to DEVELOPMENT environments alongside PREVIEW.

- UpsertBranchRequestBody / branches API accept env "development" as well
  as "preview"; the upsert service resolves the parent env by slug
  ("preview" or "dev") and scopes dev branches per org member.
- checkBranchLimit applies a separate "branchesDev" limit and filters dev
  branches by the owning org member.
- API-key and JWT auth resolve branch child environments for both PREVIEW
  and DEVELOPMENT parents; findEnvironmentByApiKey returns the dev branch
  child when a non-default branch is requested.
- archiveBranch refuses to archive the default dev branch and reports the
  branch type so callers can route appropriately.
- Presenters and presence are env/branch aware.

Backwards compatible with the existing CLI: requests that send
env "preview" (or no dev branch) behave exactly as before.

TRI-8726

Author: carderne

.changeset/dev-branch-default-sentinel.md

@@ -0,0 +1,6 @@
+---
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Centralize the `"default"` dev-branch sentinel behind a shared `DEFAULT_DEV_BRANCH` constant and `isDefaultDevBranch()` helper in `@trigger.dev/core/v3/utils/gitBranch`, replacing the hardcoded string literals duplicated across the CLI and server. No behavior change — `trigger dev` still targets the root development environment when no branch is specified.

apps/webapp/app/models/member.server.ts

@@ -215,7 +215,7 @@ export async function acceptInvite({
         organization: invite.organization,
         project,
         type: "DEVELOPMENT",
-        isBranchableEnvironment: false,
+        isBranchableEnvironment: true,
         member,
         prismaClient: tx,
       });

apps/webapp/app/models/project.server.ts

@@ -126,7 +126,7 @@ export async function createProject(
       organization,
       project,
       type: "DEVELOPMENT",
-      isBranchableEnvironment: false,
+      isBranchableEnvironment: true,
       member,
     });
   }

apps/webapp/app/models/runtimeEnvironment.server.ts

@@ -4,7 +4,7 @@ import { $replica, prisma } from "~/db.server";
 import { runStore } from "~/v3/runStore.server";
 import { logger } from "~/services/logger.server";
 import { getUsername } from "~/utils/username";
-import { sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
+import { isDefaultDevBranch, sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
 
 export type { RuntimeEnvironment };
 
@@ -100,11 +100,11 @@ export async function findEnvironmentByApiKey(
     ...authIncludeBase,
     childEnvironments: branchName
       ? {
-          where: {
-            branchName: sanitizeBranchName(branchName),
-            archivedAt: null,
-          },
-        }
+        where: {
+          branchName: sanitizeBranchName(branchName),
+          archivedAt: null,
+        },
+      }
       : undefined,
   } satisfies Prisma.RuntimeEnvironmentInclude;
 
@@ -163,6 +163,25 @@ export async function findEnvironmentByApiKey(
     return null;
   }
 
+  // If there is a named DEV branch (other than default), return it
+  if (environment.type === "DEVELOPMENT" && branchName !== undefined && !isDefaultDevBranch(branchName)) {
+    const childEnvironment = environment.childEnvironments.at(0);
+
+    if (childEnvironment) {
+      return toAuthenticated({
+        ...childEnvironment,
+        apiKey: environment.apiKey,
+        orgMember: environment.orgMember,
+        organization: environment.organization,
+        project: environment.project,
+      });
+    }
+
+    //A branch was specified but no child environment was found
+    return null;
+
+  }
+
   return toAuthenticated(environment);
 }
 

apps/webapp/app/presenters/OrganizationsPresenter.server.ts

@@ -13,6 +13,8 @@ import { defaultAvatar, parseAvatar } from "~/components/primitives/Avatar";
 import { env } from "~/env.server";
 import { flags } from "~/v3/featureFlags.server";
 import { validatePartialFeatureFlags } from "~/v3/featureFlags";
+import { devPresence } from "./v3/DevPresence.server";
+import { hydrateEnvsWithActivity } from "./v3/BranchesPresenter.server";
 
 export class OrganizationsPresenter {
   #prismaClient: PrismaClient;
@@ -102,6 +104,13 @@ export class OrganizationsPresenter {
       throw redirect(newProjectPath(organization));
     }
 
+    const recentDevBranchIds = await devPresence.getRecentBranchIds(user.id, fullProject.id);
+
+    const environments = fullProject.
+      environments.filter((env) => env.type !== "DEVELOPMENT" || env.orgMember?.userId === user.id);
+
+    const environmentsWithActivity = await hydrateEnvsWithActivity(user.id, fullProject.id, environments);
+
     const environment = this.#getEnvironment({
       user,
       projectId: fullProject.id,
@@ -115,13 +124,7 @@ export class OrganizationsPresenter {
       project: {
         ...fullProject,
         createdAt: fullProject.createdAt,
-        environments: sortEnvironments(
-          fullProject.environments.filter((env) => {
-            if (env.type !== "DEVELOPMENT") return true;
-            if (env.orgMember?.userId === user.id) return true;
-            return false;
-          })
-        ),
+        environments: sortEnvironments(environmentsWithActivity),
       },
       environment,
     };
@@ -244,7 +247,10 @@ export class OrganizationsPresenter {
 
     //otherwise show their dev environment
     const yourDevEnvironment = environments.find(
-      (env) => env.type === "DEVELOPMENT" && env.orgMember?.userId === user.id
+      (env) =>
+        env.type === "DEVELOPMENT" &&
+        env.parentEnvironmentId === null &&
+        env.orgMember?.userId === user.id
     );
     if (yourDevEnvironment) {
       return yourDevEnvironment;

apps/webapp/app/presenters/SelectBestEnvironmentPresenter.server.ts

@@ -1,7 +1,7 @@
 import {
   type RuntimeEnvironment,
   type PrismaClient,
-  RuntimeEnvironmentType,
+  type RuntimeEnvironmentType,
 } from "@trigger.dev/database";
 import { prisma } from "~/db.server";
 import { logger } from "~/services/logger.server";
@@ -140,7 +140,7 @@ export class SelectBestEnvironmentPresenter {
   }
 
   async selectBestEnvironment<
-    T extends { id: string; type: RuntimeEnvironmentType; orgMember: { userId: string } | null }
+    T extends { id: string; type: RuntimeEnvironmentType; slug: string; orgMember: { userId: string } | null }
   >(projectId: string, user: UserFromSession, environments: T[]): Promise<T> {
     //try get current environment from prefs
     const currentEnvironmentId: string | undefined =
@@ -153,7 +153,8 @@ export class SelectBestEnvironmentPresenter {
 
     //otherwise show their dev environment
     const yourDevEnvironment = environments.find(
-      (env) => env.type === "DEVELOPMENT" && env.orgMember?.userId === user.id
+      // Return the default dev environment, not a branch
+      (env) => env.type === "DEVELOPMENT" && env.slug === "dev" && env.orgMember?.userId === user.id
     );
     if (yourDevEnvironment) {
       return yourDevEnvironment;

apps/webapp/app/presenters/v3/BranchesPresenter.server.ts

@@ -1,11 +1,15 @@
-import { GitMeta } from "@trigger.dev/core/v3";
+import { GitMeta, } from "@trigger.dev/core/v3";
+import { DEFAULT_DEV_BRANCH } from "@trigger.dev/core/v3/utils/gitBranch";
+import { type RuntimeEnvironmentType } from "@trigger.dev/database";
 import { type z } from "zod";
 import { type Prisma, type PrismaClient, prisma } from "~/db.server";
 import { type Project } from "~/models/project.server";
 import { type User } from "~/models/user.server";
 import { type BranchesOptions } from "~/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.branches/route";
 import { getCurrentPlan, getPlans } from "~/services/platform.v3.server";
 import { checkBranchLimit } from "~/services/upsertBranch.server";
+import { devPresence } from "./DevPresence.server";
+import { sortEnvironments } from "~/utils/environmentSort";
 
 type Result = Awaited<ReturnType<BranchesPresenter["call"]>>;
 export type Branch = Result["branches"][number];
@@ -58,12 +62,14 @@ export class BranchesPresenter {
   public async call({
     userId,
     projectSlug,
+    env,
     showArchived = false,
     search,
     page = 1,
   }: {
     userId: User["id"];
     projectSlug: Project["slug"];
+    env: "preview" | "development";
   } & Options) {
     const project = await this.#prismaClient.project.findFirst({
       select: {
@@ -86,12 +92,16 @@ export class BranchesPresenter {
       throw new Error("Project not found");
     }
 
+    // TODO audit mishmash of preview/developement preview/dev stg/dev PREVIEW/DEVELOPMENT
+    const envType = env === "preview" ? "PREVIEW" : "DEVELOPMENT";
+
     const branchableEnvironment = await this.#prismaClient.runtimeEnvironment.findFirst({
       select: {
         id: true,
       },
       where: {
         projectId: project.id,
+        type: envType,
         isBranchableEnvironment: true,
       },
     });
@@ -119,23 +129,30 @@ export class BranchesPresenter {
       };
     }
 
+    // The default DEV branch has no branchName (it's the root dev env, stored
+    // with branchName: null), so searching for it by name wouldn't display it.
+    // Hacky way around that: always include the null-branchName root env.
+    const branchNameWhere = envType === "DEVELOPMENT" ?
+      search
+        ? { OR: [{ contains: search, mode: "insensitive" as const }, { is: null }] }
+        : {} :
+      search
+        ? { contains: search, mode: "insensitive" as const }
+        : { not: null };
+    const orgMemberWhere = envType === "DEVELOPMENT" ? { orgMember: { userId } } : {};
+
+
     const visibleCount = await this.#prismaClient.runtimeEnvironment.count({
       where: {
         projectId: project.id,
-        branchName: search
-          ? {
-              contains: search,
-              mode: "insensitive",
-            }
-          : {
-              not: null,
-            },
+        type: envType,
+        branchName: branchNameWhere,
+        ...orgMemberWhere,
         ...(showArchived ? {} : { archivedAt: null }),
       },
     });
 
-    // Limits
-    const limits = await checkBranchLimit(this.#prismaClient, project.organizationId, project.id);
+    const limits = await checkBranchLimit({ prisma: this.#prismaClient, organizationId: project.organizationId, projectId: project.id, userId, env });
 
     const [currentPlan, plans] = await Promise.all([
       getCurrentPlan(project.organizationId),
@@ -161,14 +178,9 @@ export class BranchesPresenter {
       },
       where: {
         projectId: project.id,
-        branchName: search
-          ? {
-              contains: search,
-              mode: "insensitive",
-            }
-          : {
-              not: null,
-            },
+        type: envType,
+        branchName: branchNameWhere,
+        ...orgMemberWhere,
         ...(showArchived ? {} : { archivedAt: null }),
       },
       orderBy: {
@@ -178,35 +190,34 @@ export class BranchesPresenter {
       take: BRANCHES_PER_PAGE,
     });
 
+    const totalBranchesWhere = envType === "DEVELOPMENT" ? {} : { not: null };
     const totalBranches = await this.#prismaClient.runtimeEnvironment.count({
       where: {
         projectId: project.id,
-        branchName: {
-          not: null,
-        },
+        type: envType,
+        branchName: totalBranchesWhere,
+        ...orgMemberWhere,
       },
     });
 
+
+    const branchesFiltered = branches
+      .filter((branch) => envType === "DEVELOPMENT" || branch.branchName !== null)
+      .map((branch) => ({
+        ...branch,
+        git: processGitMetadata(branch.git),
+        branchName: branch.branchName ?? DEFAULT_DEV_BRANCH,
+      }));
+
+    const branchesWithActivity = await hydrateEnvsWithActivity(userId, project.id, branchesFiltered);
+    const branchesSorted = sortEnvironments(branchesWithActivity);
+
     return {
       branchableEnvironment,
       currentPage: page,
       totalPages: Math.ceil(visibleCount / BRANCHES_PER_PAGE),
       hasBranches: totalBranches > 0,
-      branches: branches.flatMap((branch) => {
-        if (branch.branchName === null) {
-          return [];
-        }
-
-        const git = processGitMetadata(branch.git);
-
-        return [
-          {
-            ...branch,
-            branchName: branch.branchName,
-            git,
-          } as const,
-        ];
-      }),
+      branches: branchesSorted,
       hasFilters,
       limits,
       canPurchaseBranches,
@@ -218,6 +229,23 @@ export class BranchesPresenter {
   }
 }
 
+export async function hydrateEnvsWithActivity<T extends { type: RuntimeEnvironmentType; id: string }>
+  (userId: string, projectId: string, environments: T[]): Promise<Array<T & { lastActivity: Date | undefined; isConnected: boolean | undefined }>> {
+  const recentDevBranchIds = await devPresence.getRecentBranchIds(userId, projectId);
+
+  return Promise.all(environments.map(async (env) => {
+    if (env.type !== "DEVELOPMENT") {
+      return { ...env, lastActivity: undefined, isConnected: undefined };
+    }
+
+    const devHit = recentDevBranchIds.get(env.id);
+    const lastActivity = devHit === undefined ? undefined : devHit;
+    // TODO change dev-presence to a different data structure to avoid N calls?
+    const isConnected = devHit === undefined ? undefined : await devPresence.isConnected(env.id);
+    return { ...env, lastActivity, isConnected };
+  }));
+}
+
 export function processGitMetadata(data: Prisma.JsonValue): GitMetaLinks | null {
   if (!data) return null;