core: move sanitizeBranchName + isValidGitBranchName to @trigger.dev/core/v3/utils/gitBranch

Both helpers were originally in apps/webapp/app/v3/gitBranch.ts.
internal-packages/rbac needed sanitizeBranchName for the PREVIEW-env
branch resolution added in 8246234, and copy-pasting the function into
the fallback was a smell. Moves the canonical home into core (no
internal-package can import webapp code), and updates the four webapp
call sites + the rbac fallback to import from
@trigger.dev/core/v3/utils/gitBranch.

`sanitizeBranchName`'s input type is widened slightly to
`string | null | undefined` so callers passing `Headers.get(...)` (which
returns `string | null`) don't need a `?? undefined` workaround. The
existing webapp callers all pass `string | undefined`; the new union is
backwards-compatible.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: matt-aitken

.changeset/git-branch-utils.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Add `sanitizeBranchName` and `isValidGitBranchName` exports under `@trigger.dev/core/v3/utils/gitBranch`. These were previously webapp-internal but are now shared with the RBAC fallback's branch-aware authentication path.

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

@@ -3,7 +3,7 @@ import type { Prisma, PrismaClientOrTransaction, RuntimeEnvironment } from "@tri
 import { $replica, prisma } from "~/db.server";
 import { logger } from "~/services/logger.server";
 import { getUsername } from "~/utils/username";
-import { sanitizeBranchName } from "~/v3/gitBranch";
+import { sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
 
 export type { RuntimeEnvironment };
 

apps/webapp/app/services/apiAuth.server.ts

@@ -23,7 +23,7 @@ import {
   isOrganizationAccessToken,
 } from "./organizationAccessToken.server";
 import { isPublicJWT, validatePublicJwtKey } from "./realtime/jwtAuth.server";
-import { sanitizeBranchName } from "~/v3/gitBranch";
+import { sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
 
 const ClaimsSchema = z.object({
   scopes: z.array(z.string()).optional(),

apps/webapp/app/services/upsertBranch.server.ts

@@ -3,7 +3,7 @@ import slug from "slug";
 import { prisma } from "~/db.server";
 import { createApiKeyForEnv, createPkApiKeyForEnv } from "~/models/api-key.server";
 import { type CreateBranchOptions } from "~/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.branches/route";
-import { isValidGitBranchName, sanitizeBranchName } from "~/v3/gitBranch";
+import { isValidGitBranchName, sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
 import { logger } from "./logger.server";
 import { getCurrentPlan, getLimit } from "./platform.v3.server";
 

apps/webapp/test/validateGitBranchName.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { isValidGitBranchName, sanitizeBranchName } from "~/v3/gitBranch";
+import { isValidGitBranchName, sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
 
 describe("isValidGitBranchName", () => {
   it("returns true for a valid branch name", async () => {

internal-packages/rbac/src/fallback.ts

@@ -15,6 +15,7 @@ import type {
 import { createHash } from "node:crypto";
 import type { PrismaClient } from "@trigger.dev/database";
 import { validateJWT } from "@trigger.dev/core/v3/jwt";
+import { sanitizeBranchName } from "@trigger.dev/core/v3/utils/gitBranch";
 import { buildFallbackAbility, buildJwtAbility, permissiveAbility } from "./ability.js";
 
 export class RoleBaseAccessFallback {
@@ -311,22 +312,6 @@ class RoleBaseAccessFallbackController implements RoleBaseAccessController {
   }
 }
 
-// Mirror of `apps/webapp/app/v3/gitBranch.ts#sanitizeBranchName`.
-// Inlined here because internal-packages can't import webapp code; the
-// two should stay in sync. Strips common refs/* prefixes and rejects
-// unknown ref formats (returns undefined → no branch override).
-function sanitizeBranchName(ref: string | null): string | undefined {
-  if (!ref) return undefined;
-  if (ref.startsWith("refs/heads/")) return ref.substring("refs/heads/".length);
-  if (ref.startsWith("refs/remotes/")) return ref.substring("refs/remotes/".length);
-  if (ref.startsWith("refs/tags/")) return ref.substring("refs/tags/".length);
-  if (ref.startsWith("refs/pull/")) return ref.substring("refs/pull/".length);
-  if (ref.startsWith("refs/merge/")) return ref.substring("refs/merge/".length);
-  if (ref.startsWith("refs/release/")) return ref.substring("refs/release/".length);
-  if (ref.startsWith("refs/")) return undefined;
-  return ref;
-}
-
 function isPublicJWT(token: string): boolean {
   const parts = token.split(".");
   if (parts.length !== 3) return false;

packages/core/package.json

@@ -37,6 +37,7 @@
       "./v3/semanticInternalAttributes": "./src/v3/semanticInternalAttributes.ts",
       "./v3/utils/durations": "./src/v3/utils/durations.ts",
       "./v3/utils/flattenAttributes": "./src/v3/utils/flattenAttributes.ts",
+      "./v3/utils/gitBranch": "./src/v3/utils/gitBranch.ts",
       "./v3/utils/ioSerialization": "./src/v3/utils/ioSerialization.ts",
       "./v3/utils/omit": "./src/v3/utils/omit.ts",
       "./v3/utils/retries": "./src/v3/utils/retries.ts",
@@ -402,6 +403,17 @@
         "default": "./dist/commonjs/v3/utils/flattenAttributes.js"
       }
     },
+    "./v3/utils/gitBranch": {
+      "import": {
+        "@triggerdotdev/source": "./src/v3/utils/gitBranch.ts",
+        "types": "./dist/esm/v3/utils/gitBranch.d.ts",
+        "default": "./dist/esm/v3/utils/gitBranch.js"
+      },
+      "require": {
+        "types": "./dist/commonjs/v3/utils/gitBranch.d.ts",
+        "default": "./dist/commonjs/v3/utils/gitBranch.js"
+      }
+    },
     "./v3/utils/ioSerialization": {
       "import": {
         "@triggerdotdev/source": "./src/v3/utils/ioSerialization.ts",

apps/webapp/app/v3/gitBranch.ts packages/core/src/v3/utils/gitBranch.tsapps/webapp/app/v3/gitBranch.ts renamed to packages/core/src/v3/utils/gitBranch.ts

@@ -1,43 +1,30 @@
 export function isValidGitBranchName(branch: string): boolean {
-  // Must not be empty
   if (!branch) return false;
 
-  // Disallowed characters: space, ~, ^, :, ?, *, [, \
   if (/[ \~\^:\?\*\[\\]/.test(branch)) return false;
 
-  // Disallow ASCII control characters (0-31) and DEL (127)
   for (let i = 0; i < branch.length; i++) {
     const code = branch.charCodeAt(i);
     if ((code >= 0 && code <= 31) || code === 127) return false;
   }
 
-  // Cannot start or end with a slash
   if (branch.startsWith("/") || branch.endsWith("/")) return false;
-
-  // Cannot have consecutive slashes
   if (branch.includes("//")) return false;
-
-  // Cannot contain '..'
   if (branch.includes("..")) return false;
-
-  // Cannot contain '@{'
   if (branch.includes("@{")) return false;
-
-  // Cannot end with '.lock'
   if (branch.endsWith(".lock")) return false;
 
   return true;
 }
 
-export function sanitizeBranchName(ref: string | undefined): string | null {
+export function sanitizeBranchName(ref: string | null | undefined): string | null {
   if (!ref) return null;
   if (ref.startsWith("refs/heads/")) return ref.substring("refs/heads/".length);
   if (ref.startsWith("refs/remotes/")) return ref.substring("refs/remotes/".length);
   if (ref.startsWith("refs/tags/")) return ref.substring("refs/tags/".length);
   if (ref.startsWith("refs/pull/")) return ref.substring("refs/pull/".length);
   if (ref.startsWith("refs/merge/")) return ref.substring("refs/merge/".length);
   if (ref.startsWith("refs/release/")) return ref.substring("refs/release/".length);
-  //unknown ref format, so reject
   if (ref.startsWith("refs/")) return null;
 
   return ref;