feat: add branch selection to Git Stack modal with branches API endpoint (#1343)

* feat: add branch selection to Git Stack modal with branches API endpoint

- Add branch dropdown in create mode (fetches branches from new API endpoint)
- Add branch field in edit mode for existing Git stacks
- Remove redundant branch badge next to repository URL in edit mode
- Add POST /api/git/branches endpoint to list available branches
- Export buildGitEnv, buildRepoUrl, execGit from git.ts for reuse

* cla: recheck with correct author email

* fix: harden git branches endpoint and fix credential resolution

* feat(git-stacks): per-stack branch override

Add a per-stack 'branch' column to git_stacks so each stack can deploy
from a branch different from its repository's default.

- Migration 0012 (drizzle + drizzle-pg): add nullable 'branch' column
- resolveStackBranch() in git.ts: effective branch = per-stack override,
  else repository default; wired into sync/deploy/test paths
- db.ts: persist/read branch; GitStackData.branch is string | null
- API routes (preview-env, stacks create/update): honor explicit branch
  override with partial-update semantics (null/empty clears the override)
- UI: GitStackModal shows a 'Repository default' sentinel + per-stack
  selector; GitSourceBadge displays effective branch with a '(per-stack)'
  marker; stacks page passes through the per-stack branch
- tests/git-stack-branch.test.ts: unit coverage for resolveStackBranch
  and effective-branch display semantics

* feat(git-branches): security hardening per PR #1343 maintainer review

Adopts the three security recommendations from the maintainer review on
the git-branch-stack feature:

1. SSRF guard (assertSafeBranchTarget)
   New src/lib/server/git-branch-lookup.ts rejects repository URLs that
   point at private/loopback/link-local addresses before any git
   subprocess is spawned. Covers IPv4 (127/8, 169.254/16, 10/8,
   172.16/12, 192.168/16, 100.64/10, 0/8), IPv6 (::1, fe80::/10,
   fc00::/7, ::), IPv4-mapped IPv6 (::ffff:a.b.c.d), and a 25-entry
   hostname denylist (localhost, metadata.google.internal,
   host.docker.internal, etc.). Raw-URL parse only — no DNS resolution,
   avoiding TOCTOU/rebinding. Runs on BOTH the url and repositoryId
   paths (a stored repo's URL could also point internal).

2. Credential-exfiltration guard (assertCredentialUrlPair)
   A raw url paired with a stored credentialId is only allowed when the
   credential is plausibly for that host. SSH and none credentials are
   always allowed (no secret to leak). Password credentials: allowed
   when the username equals the URL host, or when the credential name
   (or its hyphen/underscore-separated segments) equals the host or its
   first label (e.g. "github-pat" → github.com). Inference-based — no
   new DB column. The repositoryId path is not subject to this guard
   (the pairing is the user's own stored config).

3. Timeout on git subprocesses
   execGit now accepts a timeoutMs parameter (default GIT_TIMEOUT_MS =
   20s, env-overridable). On timeout the process is killed with SIGKILL
   and the caller receives { timedOut: true, code: 124 }. Applied to all
   execGit call sites (clone, pull, fetch, ls-remote, etc.) so a dead
   or black-holed remote cannot stall a request indefinitely.

OpenAPI: @openapi JSDoc block added to the branches endpoint; spec
regenerated via the upstream generator (359/359 coverage, all 6 gates
pass). /api/git/branches POST entry added to openapi.generated.json.

Svelte5: fix-svelte-optional-params.sh applied to 7 .svelte files
(x?: T → x: T = undefined) to work around esbuild's rejection of
TS-only optional-parameter syntax in lang="ts" script tags.

Tests: 59 tests in tests/git-branches.test.ts covering SSRF (blocked
IPs, boundary cases), credential affinity (allowed/rejected cases),
endpoint pipeline ordering, and parseRepoHost edge cases.

Rebased onto upstream/main (a485c85) — zero conflicts; GitStackModal.svelte
had not drifted since the branch was created.

* fix(git): close SSRF/RCE/exfil gaps across all git URL+credential endpoints (PR #1343 re-review)

1. SSRF: replace hand-rolled assertSafeBranchTarget with shared URL()-based
   isSafeNotificationUrl — blocks decimal/octal/hex/short-form IPv4 and
   v4-mapped IPv6 encodings (all six maintainer bypass payloads now blocked).
   ALL schemes (http/https/ssh/git/scp-like) now judge the CANONICALIZED
   host through that single check: non-http(s) schemes can't be passed to
   URL() as-is, so the parsed host (port-stripped, IPv6 bracketed only
   when it contains a colon) is run through isSafeNotificationUrl under
   an https:// scheme. Closes the ssh/git encoded-IP bypass (decimal
   2130706433, hex 0x7f000001, short-form 127.1 over ssh://, git:// and
   scp-like all resolve to 127.0.0.1 and are now blocked).
2. Credential affinity: drop the dead second rule — with rule (i) being
   username === host, the single-label variant was identical and unreachable.
3. listRemoteBranches + testRepositoryConfig call assertSafeRepoUrl explicitly
   so the ext::/file:: transport denylist holds on every path into a git
   subprocess, not only via buildRepoUrl.
4. preview-env: assertSafeRepoTarget (SSRF+RCE) + repoFilePath containment for
   composePath/envFilePath (path traversal) + assertCredentialHostMatch
   (exfil).
5. repositories/test: assertSafeRepoTarget + assertCredentialHostMatch.

Tests: 134 across 3 files (git-branches, preview-env-security,
repositories-test-security) — lock the six http(s) encoding bypasses, the
four ssh/git encoded-IP payloads at unit and endpoint level, the subdomain
attack, single-label username, path traversal, and the endpoint pipelines.

Verified safe (no change): backup/destinations/test, registries/test,
environments/test, git/repositories CRUD, git/stacks, git/repositories/[id]/test.

* fix(git): address branch stack review feedback

- scope remote branch lookup timeout to ls-remote only
- require git:edit permission for preview-env
- clarify SSRF policy while preserving private LAN Git hosts
- support free-text branch selection for new repositories
- share production branch resolution logic with tests and UI
- add testable preview-env request pipeline

src/lib/git-stack-branch.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure branch-selection helpers for git stacks.
+ *
+ * These functions are dependency-free and safe to import from the browser and
+ * from unit tests without pulling in native/server initialisation
+ * (better-sqlite3 / argon2, etc). Both the production code (sync/deploy in
+ * src/lib/server/git.ts, the stacks routes) and the stacks UI import them, so
+ * a single implementation is the source of truth for "which branch does this
+ * stack deploy from" — the tests in tests/git-stack-branch.test.ts exercise
+ * these exact functions rather than a mirrored copy.
+ */
+
+/**
+ * The effective branch a git stack deploys from.
+ *
+ * A per-stack branch override (git_stacks.branch) wins; when it is unset,
+ * null, empty, or whitespace-only, the repository's default branch is used.
+ */
+export function resolveStackBranch(
+	gitStack: { branch: string | null } | null | undefined,
+	repository: { branch: string }
+): string {
+	const override = gitStack?.branch?.trim();
+	return override || repository.branch;
+}
+
+/**
+ * Effective branch for display in the stacks UI (list badge / stack modal
+ * header). Follows the same rule as resolveStackBranch, but tolerates a
+ * missing repository and reports whether the shown branch is a per-stack
+ * override:
+ *
+ *   - branch: the per-stack override when set (non-blank), else the
+ *     repository default (or undefined when neither is available).
+ *   - perStack: true when the shown branch is a per-stack override (a
+ *     non-blank stored value), else null (shown branch is the repository
+ *     default / nothing set).
+ *
+ * Consistency: a blank (empty / whitespace-only) override is NOT treated as a
+ * per-stack branch — it falls back to the repository default, exactly as
+ * resolveStackBranch does for deploy/sync. Only a non-blank stored override is
+ * shown as a per-stack branch.
+ */
+export function effectiveStackBranch(
+	gitStack: { branch?: string | null } | null | undefined,
+	repository: { branch?: string } | null | undefined
+): { branch: string | undefined; perStack: boolean | null } {
+	const raw = gitStack?.branch ?? null;
+	const perStackBranch = typeof raw === 'string' && raw.trim() ? raw.trim() : null;
+	return {
+		branch: perStackBranch || (repository?.branch || undefined),
+		perStack: perStackBranch ? true : null
+	};
+}
+
+/**
+ * Normalise the `branch` field of the PUT /api/git/stacks/:id partial update
+ * into a next stored value.
+ *
+ * Semantics (the API contract the stacks route implements):
+ *   - key ABSENT in the body  -> leave the current override untouched
+ *     ({ next: current, changed: false });
+ *   - explicit `null`         -> clear the override so the stack inherits the
+ *     repository default ({ next: null, changed: true });
+ *   - non-blank string        -> set the per-stack override, stored
+ *     whitespace-trimmed ({ next: <trimmed>, changed: true });
+ *   - blank / whitespace-only -> clear the override, normalised to null so a
+ *     blank save is treated as "inherit repository default" consistently
+ *     ({ next: null, changed: true }).
+ */
+export function normalizeStackBranchUpdate(
+	current: string | null,
+	body: Record<string, unknown>
+): { next: string | null; changed: boolean } {
+	if (!('branch' in body)) return { next: current, changed: false };
+	const value = body.branch;
+	if (value === null) return { next: null, changed: true };
+	const trimmed = typeof value === 'string' ? value.trim() : '';
+	return { next: trimmed || null, changed: true };
+}

src/lib/openapi.generated.json

@@ -12188,6 +12188,92 @@
         ]
       }
     },
+    "/api/git/branches": {
+      "post": {
+        "operationId": "post_api_git_branches",
+        "tags": [
+          "git"
+        ],
+        "summary": "List remote branches for a git repository via `git ls-remote`",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "branches": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  "required": [
+                    "branches"
+                  ]
+                },
+                "example": {
+                  "branches": [
+                    "main",
+                    "develop",
+                    "feature/test"
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The URL points at a loopback/link-local/metadata/reserved target, the credential does not match the URL host, or neither repositoryId nor url was supplied"
+          },
+          "403": {
+            "description": "Permission denied (requires git:edit)"
+          },
+          "404": {
+            "description": "The referenced repository does not exist"
+          },
+          "500": {
+            "description": "Failed to fetch branches (ls-remote error or timeout)"
+          }
+        },
+        "security": [
+          {
+            "cookieAuth": []
+          },
+          {
+            "bearerAuth": []
+          }
+        ],
+        "description": "Accepts either repositoryId (an existing repository, using its stored URL and credential) or url + credentialId (a new repository). SECURITY: the repository target is checked against the shared SSRF policy — loopback, link-local/cloud-metadata and other reserved dangerous targets are rejected, while ordinary private-LAN addresses are intentionally allowed so self-hosted Git servers remain supported. A raw url may only be paired with a stored credentialId whose username plausibly matches that host (SSH credentials are always allowed). The ls-remote is bounded by a hard timeout.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "repositoryId": {
+                    "type": "integer"
+                  },
+                  "url": {
+                    "type": "string"
+                  },
+                  "credentialId": {
+                    "type": "integer"
+                  }
+                }
+              },
+              "example": {
+                "url": "https://github.com/example/repo.git",
+                "credentialId": 2
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/git/credentials": {
       "get": {
         "operationId": "get_api_git_credentials",
@@ -12713,10 +12799,10 @@
             }
           },
           "400": {
-            "description": "composePath missing, neither repositoryId nor url supplied, or the repo/env-file preview reported an error"
+            "description": "composePath missing, neither repositoryId nor url supplied, the URL points at a loopback/link-local/metadata/reserved target, the URL is an unsupported transport (ext::/file::), the credential does not match the URL host, the compose/env path escapes the repository, or the repo/env-file preview reported an error"
           },
-          "401": {
-            "description": "Authentication required"
+          "403": {
+            "description": "Permission denied (requires the git:edit permission — same model as /api/git/branches; an unauthenticated or read-only user is denied here rather than via a separate 401)"
           },
           "404": {
             "description": "The referenced repository does not exist"
@@ -12733,7 +12819,7 @@
             "bearerAuth": []
           }
         ],
-        "description": "repositoryId from GET /api/git/repositories. credentialId from GET /api/git/credentials.",
+        "description": "repositoryId from GET /api/git/repositories. credentialId from GET /api/git/credentials. SECURITY: requires the git:edit permission when authentication is enabled (403 otherwise). The repository target is checked against the shared SSRF policy — loopback, link-local/cloud-metadata and other reserved dangerous targets are rejected, while ordinary private-LAN addresses are intentionally allowed so self-hosted Git servers remain supported. The ext::/file:: transports and local paths are rejected; the raw url may only be paired with a stored credentialId whose username plausibly matches that host (exfiltration defense); and composePath/envFilePath are constrained to stay inside the cloned repository (path traversal).",
         "requestBody": {
           "required": true,
           "content": {
@@ -13485,11 +13571,14 @@
             }
           },
           "400": {
-            "description": "The url field is missing"
+            "description": "The url field is missing, the URL points at a loopback/link-local/metadata/reserved target, the URL is an unsupported transport, or the credential does not match the URL host"
           },
           "403": {
             "description": "Caller lacks the settings:manage permission"
           },
+          "404": {
+            "description": "The referenced credential does not exist"
+          },
           "500": {
             "description": "The connectivity test failed"
           }
@@ -13502,7 +13591,7 @@
             "bearerAuth": []
           }
         ],
-        "description": "credentialId from GET /api/git/credentials.",
+        "description": "credentialId from GET /api/git/credentials. SECURITY: the repository target is checked against the shared SSRF policy — loopback, link-local/cloud-metadata and other reserved dangerous targets are rejected, while ordinary private-LAN addresses are intentionally allowed so self-hosted Git servers remain supported. The ext::/file:: transports and local paths are rejected; the raw url may only be paired with a stored credentialId whose username plausibly matches that host (exfiltration defense).",
         "requestBody": {
           "required": true,
           "content": {

src/lib/server/db.ts

@@ -2295,6 +2295,7 @@ export interface GitStackData {
 	environmentId: number | null;
 	repositoryId: number;
 	composePath: string;
+	branch: string | null; // Per-stack branch override; null = use repository default
 	envFilePath: string | null;
 	autoUpdate: boolean;
 	autoUpdateSchedule: 'daily' | 'weekly' | 'custom';
@@ -2333,6 +2334,7 @@ export async function getGitStacks(environmentId?: number): Promise<GitStackWith
 			stackName: gitStacks.stackName,
 			environmentId: gitStacks.environmentId,
 			repositoryId: gitStacks.repositoryId,
+			branch: gitStacks.branch,
 			composePath: gitStacks.composePath,
 			envFilePath: gitStacks.envFilePath,
 			autoUpdate: gitStacks.autoUpdate,
@@ -2366,6 +2368,7 @@ export async function getGitStacks(environmentId?: number): Promise<GitStackWith
 			stackName: gitStacks.stackName,
 			environmentId: gitStacks.environmentId,
 			repositoryId: gitStacks.repositoryId,
+			branch: gitStacks.branch,
 			composePath: gitStacks.composePath,
 			envFilePath: gitStacks.envFilePath,
 			autoUpdate: gitStacks.autoUpdate,
@@ -2399,6 +2402,7 @@ export async function getGitStacks(environmentId?: number): Promise<GitStackWith
 		stackName: row.stackName,
 		environmentId: row.environmentId,
 		repositoryId: row.repositoryId,
+		branch: row.branch ?? null,
 		composePath: row.composePath,
 		envFilePath: row.envFilePath,
 		autoUpdate: row.autoUpdate,
@@ -2434,6 +2438,7 @@ export async function getGitStacksForEnvironmentOnly(environmentId: number): Pro
 		stackName: gitStacks.stackName,
 		environmentId: gitStacks.environmentId,
 		repositoryId: gitStacks.repositoryId,
+		branch: gitStacks.branch,
 		composePath: gitStacks.composePath,
 		envFilePath: gitStacks.envFilePath,
 		autoUpdate: gitStacks.autoUpdate,
@@ -2467,6 +2472,7 @@ export async function getGitStacksForEnvironmentOnly(environmentId: number): Pro
 		stackName: row.stackName,
 		environmentId: row.environmentId,
 		repositoryId: row.repositoryId,
+		branch: row.branch ?? null,
 		composePath: row.composePath,
 		envFilePath: row.envFilePath,
 		autoUpdate: row.autoUpdate,
@@ -2501,6 +2507,7 @@ export async function getGitStack(id: number): Promise<GitStackWithRepo | null>
 		stackName: gitStacks.stackName,
 		environmentId: gitStacks.environmentId,
 		repositoryId: gitStacks.repositoryId,
+		branch: gitStacks.branch,
 		composePath: gitStacks.composePath,
 		envFilePath: gitStacks.envFilePath,
 		autoUpdate: gitStacks.autoUpdate,
@@ -2536,6 +2543,7 @@ export async function getGitStack(id: number): Promise<GitStackWithRepo | null>
 		stackName: row.stackName,
 		environmentId: row.environmentId,
 		repositoryId: row.repositoryId,
+		branch: row.branch ?? null,
 		composePath: row.composePath,
 		envFilePath: row.envFilePath,
 		autoUpdate: row.autoUpdate,
@@ -2571,6 +2579,7 @@ export async function getGitStackByName(stackName: string, environmentId?: numbe
 		stackName: gitStacks.stackName,
 		environmentId: gitStacks.environmentId,
 		repositoryId: gitStacks.repositoryId,
+		branch: gitStacks.branch,
 		composePath: gitStacks.composePath,
 		envFilePath: gitStacks.envFilePath,
 		autoUpdate: gitStacks.autoUpdate,
@@ -2610,6 +2619,7 @@ export async function getGitStackByName(stackName: string, environmentId?: numbe
 		stackName: row.stackName,
 		environmentId: row.environmentId,
 		repositoryId: row.repositoryId,
+		branch: row.branch ?? null,
 		composePath: row.composePath,
 		envFilePath: row.envFilePath,
 		autoUpdate: row.autoUpdate,
@@ -2644,6 +2654,7 @@ export async function getGitStackByWebhookSecret(secret: string): Promise<GitSta
 		stackName: gitStacks.stackName,
 		environmentId: gitStacks.environmentId,
 		repositoryId: gitStacks.repositoryId,
+		branch: gitStacks.branch,
 		composePath: gitStacks.composePath,
 		envFilePath: gitStacks.envFilePath,
 		autoUpdate: gitStacks.autoUpdate,
@@ -2678,6 +2689,7 @@ export async function getGitStackByWebhookSecret(secret: string): Promise<GitSta
 		stackName: row.stackName,
 		environmentId: row.environmentId,
 		repositoryId: row.repositoryId,
+		branch: row.branch ?? null,
 		composePath: row.composePath,
 		envFilePath: row.envFilePath,
 		autoUpdate: row.autoUpdate,
@@ -2710,6 +2722,7 @@ export async function createGitStack(data: {
 	stackName: string;
 	environmentId?: number | null;
 	repositoryId: number;
+	branch?: string | null;
 	composePath?: string;
 	envFilePath?: string | null;
 	autoUpdate?: boolean;
@@ -2727,6 +2740,7 @@ export async function createGitStack(data: {
 		stackName: data.stackName,
 		environmentId: data.environmentId ?? null,
 		repositoryId: data.repositoryId,
+		branch: data.branch || null,
 		composePath: data.composePath || 'compose.yaml',
 		envFilePath: data.envFilePath || null,
 		contextDir: data.contextDir || null,
@@ -2749,6 +2763,7 @@ export async function updateGitStack(id: number, data: Partial<GitStackData>): P
 	if (data.stackName !== undefined) updateData.stackName = data.stackName;
 	if (data.repositoryId !== undefined) updateData.repositoryId = data.repositoryId;
 	if (data.composePath !== undefined) updateData.composePath = data.composePath;
+	if (data.branch !== undefined) updateData.branch = data.branch || null;
 	if (data.envFilePath !== undefined) updateData.envFilePath = data.envFilePath;
 	if (data.autoUpdate !== undefined) updateData.autoUpdate = data.autoUpdate;
 	if (data.autoUpdateSchedule !== undefined) updateData.autoUpdateSchedule = data.autoUpdateSchedule;
@@ -2821,6 +2836,7 @@ export async function getEnabledAutoUpdateGitStacks(): Promise<GitStackWithRepo[
 		stackName: row.stackName,
 		environmentId: row.environmentId,
 		repositoryId: row.repositoryId,
+		branch: row.branch ?? null,
 		composePath: row.composePath,
 		envFilePath: row.envFilePath,
 		autoUpdate: row.autoUpdate,
@@ -2886,6 +2902,7 @@ export async function getAllAutoUpdateGitStacks(): Promise<GitStackWithRepo[]> {
 		stackName: row.stackName,
 		environmentId: row.environmentId,
 		repositoryId: row.repositoryId,
+		branch: row.branch ?? null,
 		composePath: row.composePath,
 		autoUpdate: row.autoUpdate,
 		autoUpdateSchedule: row.autoUpdateSchedule,

src/lib/server/db/schema/index.ts

@@ -321,6 +321,7 @@ export const gitStacks = sqliteTable('git_stacks', {
 	stackName: text('stack_name').notNull(),
 	environmentId: integer('environment_id').references(() => environments.id, { onDelete: 'cascade' }),
 	repositoryId: integer('repository_id').notNull().references(() => gitRepositories.id, { onDelete: 'cascade' }),
+	branch: text('branch'), // Per-stack branch override; null = use repository default
 	composePath: text('compose_path').default('docker-compose.yml'), // Reverted to original value (#1110)
 	envFilePath: text('env_file_path'), // Path to .env file in repository (e.g., ".env", "config/.env.prod")
 	autoUpdate: integer('auto_update', { mode: 'boolean' }).default(false),

src/lib/server/db/schema/pg-schema.ts

@@ -324,6 +324,7 @@ export const gitStacks = pgTable('git_stacks', {
 	stackName: text('stack_name').notNull(),
 	environmentId: integer('environment_id').references(() => environments.id, { onDelete: 'cascade' }),
 	repositoryId: integer('repository_id').notNull().references(() => gitRepositories.id, { onDelete: 'cascade' }),
+	branch: text('branch'), // Per-stack branch override; null = use repository default
 	composePath: text('compose_path').default('docker-compose.yml'), // Reverted to original value (#1110)
 	envFilePath: text('env_file_path'), // Path to .env file in repository (e.g., ".env", "config/.env.prod")
 	autoUpdate: boolean('auto_update').default(false),

src/lib/server/git-branch-lookup.ts

@@ -0,0 +1,178 @@
+/**
+ * Security guards for user-supplied git repository URLs on the branch-lookup
+ * and env-preview flows (POST /api/git/branches, POST /api/git/preview-env).
+ *
+ * SECURITY CONTEXT (PR #1343 maintainer review, rounds 1+2):
+ *
+ *  1. SSRF — the URL is handed to a git subprocess whose libcurl resolves
+ *     EVERY legal IP encoding (decimal 2130706433, octal 0177.0.0.1, short
+ *     form 127.1, hex 0x7f000001, un-compressed v4-mapped IPv6). Hand-rolled
+ *     IP normalization is a rabbit hole — the SSRF check therefore delegates
+ *     to isSafeNotificationUrl (src/lib/server/url-safety.ts), which is
+ *     URL()-based, canonicalizes all of the encodings above, and is the same
+ *     battle-tested guard our secret-provider hosts use. We only prepend a
+ *     scheme so that ssh:// and scp-like URLs (which are valid git remotes
+ *     but not valid URL() inputs) can be canonicalized.
+ *
+ *  2. Credential affinity — a raw url + stored credentialId is ONLY allowed
+ *     when the credential's username is plausibly FOR that host (username ==
+ *     host, or a single-label credential username equal to the host). No
+ *     name-segment inference, no first-label matching: a single-label
+ *     credential username ("github", "admin", "git") plus an attacker
+ *     subdomain (github.evil.com) would otherwise deliver the decrypted
+ *     secret to the attacker. The repositoryId path is not subject to this
+ *     guard — the pairing is the user's own stored repository config.
+ *
+ *  3. Transport denylist — assertSafeRepoUrl (git-url-safety.ts) rejects the
+ *     ext::/fd::/file:: transports and local paths. listRemoteBranches calls
+ *     it explicitly so the denylist holds on every path into a git
+ *     subprocess, not only via buildRepoUrl.
+ *
+ * Import-light (no db/sqlite) so it stays unit-testable.
+ */
+
+import { isSafeNotificationUrl } from './url-safety';
+import { assertSafeRepoUrl } from './git-url-safety';
+import type { GitCredential } from './db';
+
+/**
+ * Parse the host out of a git repository URL.
+ *
+ * Supported forms:
+ *   https://host[:port]/path, http://...   → host (port stripped)
+ *   ssh://[user@]host[:port]/path          → host
+ *   git://host[:port]/path                 → host
+ *   [user@]host:path (scp-like)            → host
+ *   [fe80::1] / [fe80::1]:port            → fe80::1
+ *
+ * Returns null when no host can be determined (bare path — already rejected
+ * by assertSafeRepoUrl upstream, or a scheme we don't accept).
+ */
+export function parseRepoHost(url: string): string | null {
+	const u = (url || '').trim();
+	if (!u) return null;
+	const schemeMatch = u.match(/^[a-z][a-z0-9+.-]*:/i);
+	if (schemeMatch) {
+		const scheme = schemeMatch[0].slice(0, -1).toLowerCase();
+		if (!['http', 'https', 'ssh', 'git'].includes(scheme)) return null;
+		const rest = u.slice(schemeMatch[0].length).replace(/^\/\//, '');
+		// IPv6 in brackets: [fe80::1] or [fe80::1]:8080 — strip brackets.
+		const bracket = rest.match(/^\[([0-9a-fA-F:.]+)\]/);
+		if (bracket) return bracket[1].toLowerCase();
+		const hostPart = rest.split('/')[0] || '';
+		const atIdx = hostPart.lastIndexOf('@');
+		const hostWithPort = atIdx >= 0 ? hostPart.slice(atIdx + 1) : hostPart;
+		const host = hostWithPort.split(':')[0];
+		return host ? host.toLowerCase() : null;
+	}
+	// No scheme. IPv6 in brackets: [fe80::1], possibly with a port.
+	const bracket = u.match(/^\[([0-9a-fA-F:.]+)\](?::\d+)?$/);
+	if (bracket) return bracket[1].toLowerCase();
+	// scp-like: [user@]host:path
+	const colonIdx = u.indexOf(':');
+	if (colonIdx <= 0) return null; // no scheme, no scp colon → no host
+	const hostPart = u.slice(0, colonIdx);
+	const atIdx = hostPart.lastIndexOf('@');
+	const host = atIdx >= 0 ? hostPart.slice(atIdx + 1) : hostPart;
+	return host ? host.toLowerCase() : null;
+}
+
+// ---------------------------------------------------------------------------
+// Shared host safety check — ONE canonicalization path for every scheme.
+//
+// isSafeNotificationUrl is URL()-based: new URL() canonicalizes every
+// legal IP encoding (decimal 2130706433, hex 0x7f000001, octal, short-form
+// 127.1, v4-mapped IPv6) BEFORE the range check, and its hostname
+// denylist covers internal hostnames. For non-http(s) git schemes we can't
+// hand the original URL to it (URL() rejects ssh:// / git:// and scp-like
+// syntax), so we canonicalize the PARSED host (port already stripped by
+// parseRepoHost, brackets stripped for IPv6) under an https:// scheme and
+// run it through the same battle-tested check. This closes the encoded-IP
+// bypass on the ssh/git path: ipCategory matches only a plain dotted-quad,
+// so decimal/hex/short-form hosts sailed through it (2026-08-21
+// maintainer re-review).
+// ---------------------------------------------------------------------------
+function assertHostSafeFromParse(parsedHost: string): void {
+	// IPv6 literals need brackets for URL() to accept them — but ONLY if the
+	// host actually contains a colon. Wrapping a plain IPv4 literal
+	// (10.0.0.5) in brackets produces an invalid URL() input, which would
+	// be rejected as "not a valid URL" and block every LAN IP.
+	const host = parsedHost.includes(':') ? `[${parsedHost}]` : parsedHost;
+	const check = isSafeNotificationUrl(`https://${host}/`);
+	if (!check.ok) {
+		throw new Error(
+			`Repository URL host is not allowed (loopback, cloud-metadata or other reserved/dangerous target): ${check.reason}`
+		);
+	}
+}
+
+/**
+ * Guard 1: reject a git repository URL that points at a dangerous target
+ * (SSRF defense), or a hostname that resolves to internal infrastructure.
+ *
+ * Policy (shared isSafeNotificationUrl / dangerousHostReason, src/lib/server/
+ * url-safety.ts): loopback (127.x/::1), cloud-metadata / link-local
+ * (169.254.169.254), multicast/reserved and localhost are REJECTED.
+ * Ordinary private-LAN ranges (10.x / 192.168.x / 172.16-31.x) are INTENTIONALLY
+ * ALLOWED so self-hosted Git servers on the RFC1918 LAN keep working — this
+ * is Dockhand's self-hosted-service policy (same as the notification
+ * receivers and backup repos). Do NOT "fix" this into the strict
+ * isSafeWebhookUrl / privateIpReason policy (that blocks all private) —
+ * doing so would break self-hosted Git on a LAN.
+ *
+ * Every scheme is judged on the CANONICALIZED host through
+ * isSafeNotificationUrl (see assertHostSafeFromParse): http(s) via the
+ * original URL, ssh/git/scp-like via the parsed host. localhost is blocked
+ * explicitly so ssh://localhost and scp-like localhost stay covered by one
+ * code path.
+ */
+export function assertSafeRepoTarget(url: string): void {
+	assertSafeRepoUrl(url); // transport denylist (ext::/fd::/file::/local paths)
+	const host = parseRepoHost(url);
+	if (!host) {
+		throw new Error('Invalid repository URL for branch lookup');
+	}
+	if (host === 'localhost' || host.endsWith('.localhost')) {
+		throw new Error('Repository URL host is not allowed for branch lookup');
+	}
+	assertHostSafeFromParse(host);
+}
+
+/**
+ * Guard 2: a raw URL may only be paired with a stored password credential
+ * when the credential is plausibly FOR that host (credential-exfiltration
+ * defense).
+ *
+ * Rules:
+ *   - `ssh` / `none` credentials: ALWAYS allowed (SSH keys are validated by
+ *     the remote server; there is no secret to leak for `none`).
+ *   - `password` credentials:
+ *     the credential's username equals the URL host (PAT-style: the
+ *     username field holds the account name that the host expects).
+ *
+ * Deliberately NO name-segment inference and NO first-label matching: a
+ * single-label credential username ("github", "admin", "git") would match
+ * ANY attacker subdomain (github.evil.com / admin.evil.com) and deliver
+ * the decrypted secret there. Hostnames are compared exactly (case-insensitive,
+ * with a port stripped) — a single-label username only matches a single-label
+ * host, which cannot be an attacker-chosen subdomain of another host.
+ */
+export function assertCredentialHostMatch(url: string, credential: GitCredential): void {
+	if (!credential) return;
+	if (credential.authType === 'ssh' || credential.authType === 'none') return;
+
+	const host = parseRepoHost(url);
+	if (!host) {
+		throw new Error('Invalid repository URL for branch lookup');
+	}
+
+	const username = (credential.username || '').trim().toLowerCase();
+	// Username must match the full host exactly (PAT-style). A username
+	// containing a dot matches only a dot-containing host — never a
+	// subdomain of it.
+	if (username && username === host) return;
+
+	throw new Error(
+		'Stored credential does not match the repository URL host'
+	);
+}

src/lib/server/git.ts

@@ -19,6 +19,8 @@ import { deployStack, getStackDir } from './stacks';
 import { sendEventNotification } from './notifications';
 import { buildBasicAuthHeader } from './git-auth';
 import { assertSafeRepoUrl, assertSafeGitRef, repoFilePath } from './git-url-safety';
+import { assertSafeRepoTarget } from './git-branch-lookup';
+import { resolveStackBranch } from '../git-stack-branch';
 import {
 	parseManifest,
 	serializeManifest,
@@ -325,20 +327,89 @@ function buildRepoUrl(url: string, credential: GitCredential | null): string {
 	return url;
 }
 
-async function execGit(args: string[], cwd: string, env: GitEnv): Promise<{ stdout: string; stderr: string; code: number }> {
-	try {
+/**
+ * Hard timeout (ms) for the remote-branch lookup (git ls-remote) ONLY.
+ * The lookup is the single git call whose target URL can be driven by an
+ * attacker-chosen URL (POST /api/git/branches, the new-repository branch
+ * picker), so an unbounded ls-remote is a resource-exhaustion vector.
+ * NOTE: this constant is deliberately NOT applied to ordinary deploy/sync
+ * operations (clone / pull / fetch / rev-parse) — those target the
+ * operator's own repository over a controlled URL, and a legitimate
+ * large-repo clone or slow WAN fetch can exceed this limit, so they stay
+ * UNBOUNDED (execGit without an explicit timeout). */
+export const GIT_TIMEOUT_MS = Number(process.env.GIT_TIMEOUT_MS) || 20000;
+
+/**
+ * Run a git command.
+ *
+ * Timeouts are OPT-IN: the default is UNBOUNDED. Ordinary deploy/sync
+ * operations (clone, pull, fetch, rev-parse) are unbounded because their
+ * target is the operator's own repository and a slow network or large repo
+ * is a legitimate outcome — they must not be killed mid-flight. Callers
+ * that need a bounded operation (the remote-branch lookup, whose target
+ * URL is attacker-influenced) pass `timeoutMs` explicitly (see
+ * listRemoteBranches).
+ */
+function execGit(
+	args: string[],
+	cwd: string,
+	env: GitEnv,
+	timeoutMs?: number
+): Promise<{ stdout: string; stderr: string; code: number; timedOut?: boolean }> {
+	return new Promise((resolve) => {
+		let settled = false;
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+
 		const proc = nodeSpawn('git', args, {
 			cwd,
 			env,
 			stdio: ['pipe', 'pipe', 'pipe']
 		});
 
-		const result = await collectProcess(proc);
+		const finish = (
+			partial: { stdout: string; stderr: string; code: number; timedOut?: boolean }
+		) => {
+			if (settled) return;
+			settled = true;
+			// Only clear a timer if one was actually created — the default
+			// (no timeout) never creates one.
+			if (timer) clearTimeout(timer);
+			if (partial.timedOut) {
+				// The process is still running — kill it so the git subprocess
+				// (and any child ssh) cannot keep running after we give up.
+				proc.kill('SIGKILL');
+			}
+			resolve(partial);
+		};
 
-		return { stdout: result.stdout.trim(), stderr: result.stderr.trim(), code: result.exitCode };
-	} catch (err: any) {
-		return { stdout: '', stderr: err.message, code: 1 };
-	}
+		// Only arm a timer when a valid timeout was explicitly provided —
+		// undefined (or non-finite / non-positive) means "run unbounded".
+		const timer: ReturnType<typeof setTimeout> | undefined =
+			timeoutMs !== undefined && Number.isFinite(timeoutMs) && timeoutMs > 0
+				? setTimeout(() => {
+						finish({
+							stdout: Buffer.concat(stdoutChunks).toString(),
+							stderr: Buffer.concat(stderrChunks).toString(),
+							code: 124,
+							timedOut: true
+						});
+					}, timeoutMs)
+				: undefined;
+
+		proc.stdout?.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+		proc.stderr?.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+		proc.on('error', (err: any) => {
+			finish({ stdout: '', stderr: err.message, code: 1 });
+		});
+		proc.on('close', (code) => {
+			finish({
+				stdout: Buffer.concat(stdoutChunks).toString(),
+				stderr: Buffer.concat(stderrChunks).toString(),
+				code: code ?? 1
+			});
+		});
+	});
 }
 
 /**
@@ -641,6 +712,11 @@ export async function testRepositoryConfig(options: {
 		return { success: false, error: 'Repository URL is required' };
 	}
 
+	// Transport denylist (ext::/fd::/file::/local paths) — applied here so the
+	// denylist holds on every path into a git subprocess, not only via
+	// buildRepoUrl (same pattern as listRemoteBranches).
+	assertSafeRepoUrl(url);
+
 	// Fetch credential from database if credentialId is provided
 	const credential = credentialId ? await getGitCredential(credentialId) : null;
 	if (credentialId && !credential) {
@@ -654,6 +730,74 @@ export async function testRepositoryConfig(options: {
 	});
 }
 
+/**
+ * List remote branches for a repository URL using git ls-remote.
+ * Resolves credentials from the database if a credentialId is provided.
+ * Bounded by a hard timeout (default GIT_TIMEOUT_MS, 20s) so a dead or
+ * black-holed host cannot stall the request — see execGit. This is the
+ * only git operation with a timeout: its target URL is the one that can be
+ * attacker-influenced, so an unbounded ls-remote would be a resource-
+ * exhaustion vector.
+ *
+ * The transport denylist (ext::/fd::/file::/local paths) is applied HERE,
+ * explicitly, rather than only via buildRepoUrl — a future parser change in
+ * buildRepoUrl must not be able to reopen command execution on this path.
+ */
+export async function listRemoteBranches(options: {
+	url: string;
+	credentialId?: number | null;
+	timeoutMs?: number;
+}): Promise<{ branches: string[]; error?: string }> {
+	const { url, credentialId, timeoutMs } = options;
+
+	// The effective branch-lookup timeout: an explicitly provided (valid)
+	// override wins; otherwise the default GIT_TIMEOUT_MS. This is the ONLY
+	// bounded git operation — see execGit for why deploy/sync operations are
+	// left unbounded.
+	const effectiveTimeoutMs = timeoutMs ?? GIT_TIMEOUT_MS;
+
+	// Transport denylist — the same check buildRepoUrl applies, applied
+	// explicitly here so the denylist holds even if buildRepoUrl changes.
+	assertSafeRepoUrl(url);
+
+	// Fetch credential from database if credentialId is provided
+	const credential = credentialId ? await getGitCredential(credentialId) : null;
+
+	const env = await buildGitEnv(credential);
+	const repoUrl = buildRepoUrl(url, credential);
+
+	try {
+		const result = await execGit(
+			['ls-remote', '--heads', '--refs', repoUrl],
+			process.cwd(),
+			env,
+			effectiveTimeoutMs
+		);
+
+		if (result.timedOut) {
+			return { branches: [], error: `git ls-remote timed out after ${Math.round(effectiveTimeoutMs / 1000)}s` };
+		}
+
+		if (result.code !== 0) {
+			return { branches: [], error: cleanGitError(result.stderr) };
+		}
+
+		const branches = result.stdout.split('\n')
+			.filter(l => l.trim())
+			.map(l => {
+				const m = l.match(/refs\/heads\/(.+)$/);
+				return m ? m[1] : null;
+			})
+			.filter(Boolean) as string[];
+
+		return { branches };
+	} catch (error: any) {
+		return { branches: [], error: error.message };
+	} finally {
+		cleanupSshKey(credential);
+	}
+}
+
 export async function syncRepository(repoId: number): Promise<SyncResult> {
 	const repo = await getGitRepository(repoId);
 	if (!repo) {
@@ -872,6 +1016,13 @@ async function getPreviousCommit(repoPath: string, env: GitEnv): Promise<string
 	}
 }
 
+/**
+ * The effective branch a git stack deploys from is resolved by
+ * resolveStackBranch() (src/lib/git-stack-branch.ts) — a per-stack branch
+ * override (git_stacks.branch) wins; when it is unset, empty, or
+ * whitespace-only, the repository's default branch is used.
+ */
+
 export async function syncGitStack(stackId: number): Promise<SyncResult> {
 	const gitStack = await getGitStack(stackId);
 	if (!gitStack) {
@@ -901,8 +1052,14 @@ export async function syncGitStack(stackId: number): Promise<SyncResult> {
 		return { success: false, error: 'Repository not found' };
 	}
 
+	// Per-stack branch override wins; unset means the repository default
+	const effectiveBranch = resolveStackBranch(gitStack, repo);
+
 	console.log(`${logPrefix} Repository URL:`, repo.url);
 	console.log(`${logPrefix} Repository branch:`, repo.branch);
+	if (effectiveBranch !== repo.branch) {
+		console.log(`${logPrefix} Stack branch override:`, effectiveBranch);
+	}
 
 	const credential = repo.credentialId ? await getGitCredential(repo.credentialId) : null;
 	const repoPath = await getStackRepoPath(stackId, gitStack.stackName, gitStack.environmentId);
@@ -928,11 +1085,11 @@ export async function syncGitStack(stackId: number): Promise<SyncResult> {
 		}
 
 		console.log(`${logPrefix} Cloning repository...`);
-		assertSafeGitRef(repo.branch);
+		assertSafeGitRef(effectiveBranch);
 		const repoUrl = buildRepoUrl(repo.url, credential);
 
 		const result = await execGit(
-			['clone', '--filter=blob:none', '--branch', repo.branch, repoUrl, repoPath],
+			['clone', '--filter=blob:none', '--branch', effectiveBranch, repoUrl, repoPath],
 			process.cwd(),
 			env
 		);
@@ -1283,15 +1440,18 @@ export async function testGitStack(stackId: number): Promise<TestResult> {
 		return { success: false, error: 'Repository not found' };
 	}
 
+	// Per-stack branch override wins; unset means the repository default
+	const effectiveBranch = resolveStackBranch(gitStack, repo);
+
 	const credential = repo.credentialId ? await getGitCredential(repo.credentialId) : null;
 	const env = await buildGitEnv(credential);
-	assertSafeGitRef(repo.branch);
+	assertSafeGitRef(effectiveBranch);
 	const repoUrl = buildRepoUrl(repo.url, credential);
 
 	try {
 		// Use git ls-remote to test connection and get branch info
 		const result = await execGit(
-			['ls-remote', '--heads', '--refs', repoUrl, repo.branch],
+			['ls-remote', '--heads', '--refs', repoUrl, effectiveBranch],
 			process.cwd(),
 			env
 		);
@@ -1305,12 +1465,12 @@ export async function testGitStack(stackId: number): Promise<TestResult> {
 		// Parse the output to get commit hash
 		const lines = result.stdout.split('\n').filter(l => l.trim());
 		if (lines.length === 0) {
-			return { success: false, error: `Branch '${repo.branch}' not found in repository` };
+			return { success: false, error: `Branch '${effectiveBranch}' not found in repository` };
 		}
 
 		const match = lines[0].match(/^([a-f0-9]+)\s+refs\/heads\/(.+)$/);
 		const lastCommit = match ? match[1].substring(0, 7) : undefined;
-		const branch = match ? match[2] : repo.branch;
+		const branch = match ? match[2] : effectiveBranch;
 
 		cleanupSshKey(credential, env);
 
@@ -1368,6 +1528,9 @@ export async function deployGitStackWithProgress(
 		return { success: false, error: 'Repository not found' };
 	}
 
+	// Per-stack branch override wins; unset means the repository default
+	const effectiveBranch = resolveStackBranch(gitStack, repo);
+
 	const credential = repo.credentialId ? await getGitCredential(repo.credentialId) : null;
 	const repoPath = await getStackRepoPath(stackId, gitStack.stackName, gitStack.environmentId);
 	const env = await buildGitEnv(credential);
@@ -1394,13 +1557,13 @@ export async function deployGitStackWithProgress(
 			rmSync(repoPath, { recursive: true, force: true });
 		}
 
-		assertSafeGitRef(repo.branch);
+		assertSafeGitRef(effectiveBranch);
 		const repoUrl = buildRepoUrl(repo.url, credential);
 
 		// Step 3: Fetching (blobless clone - fetches all commits but blobs on-demand)
-		onProgress({ status: 'fetching', message: `Fetching branch ${repo.branch}...`, step: 3, totalSteps });
+		onProgress({ status: 'fetching', message: `Fetching branch ${effectiveBranch}...`, step: 3, totalSteps });
 		const cloneResult = await execGit(
-			['clone', '--filter=blob:none', '--branch', repo.branch, repoUrl, repoPath],
+			['clone', '--filter=blob:none', '--branch', effectiveBranch, repoUrl, repoPath],
 			process.cwd(),
 			env
 		);
@@ -1801,6 +1964,20 @@ export async function previewRepoEnvFiles(options: PreviewEnvOptions): Promise<P
 		// Build git environment with credentials
 		// Cast credential to GitCredential type (only uses id, authType, sshPrivateKey)
 		env = await buildGitEnv(credential as GitCredential | null);
+
+		// Security (PR #1343 maintainer review): the preview endpoint clones a
+		// USER-SUPPLIED URL and reads env files from it — the same SSRF / RCE /
+		// path-traversal surface as the branches endpoint. Apply the shared guards
+		// BEFORE any git subprocess or file read:
+		//  1. assertSafeRepoTarget — blocks loopback/link-local/metadata/reserved
+		//     hosts (SSRF) and the ext::/file:: transport denylist (RCE). Ordinary
+		//     private-LAN addresses are intentionally allowed (self-hosted Git).
+		//  2. repoFilePath — keeps composePath/envFilePath INSIDE the temp dir
+		//     (path traversal). Without this, `envFilePath: '../../secrets/x'`
+		//     reads a file outside the clone.
+		assertSafeRepoTarget(repoUrl);
+		const safeComposePath = repoFilePath(tempDir, composePath, 'Compose path');
+		const safeEnvFilePath = envFilePath ? repoFilePath(tempDir, envFilePath, 'Env file path') : null;
 		assertSafeGitRef(branch);
 		const authenticatedUrl = buildRepoUrl(repoUrl, credential as GitCredential | null);
 
@@ -1825,8 +2002,9 @@ export async function previewRepoEnvFiles(options: PreviewEnvOptions): Promise<P
 
 		console.log(`${logPrefix} Clone successful`);
 
-		// Determine the compose directory (where .env file should be)
-		const composeDir = dirname(composePath);
+		// Determine the compose directory (where .env file should be) — uses the
+		// VALIDATED path (already checked to be inside the temp dir).
+		const composeDir = dirname(safeComposePath);
 		const baseEnvPath = join(tempDir, composeDir, '.env');
 
 		const vars: Record<string, string> = {};
@@ -1846,9 +2024,10 @@ export async function previewRepoEnvFiles(options: PreviewEnvOptions): Promise<P
 			console.log(`${logPrefix} No .env file at ${baseEnvPath}`);
 		}
 
-		// Read additional env file if specified
-		if (envFilePath) {
-			const additionalEnvPath = join(tempDir, envFilePath);
+		// Read additional env file if specified — uses the VALIDATED path
+		// (already checked to be inside the temp dir).
+		if (safeEnvFilePath) {
+			const additionalEnvPath = safeEnvFilePath;
 			if (existsSync(additionalEnvPath)) {
 				console.log(`${logPrefix} Reading additional env file: ${additionalEnvPath}`);
 				const content = readFileSync(additionalEnvPath, 'utf-8');

src/lib/server/preview-env-handler.ts

@@ -0,0 +1,198 @@
+/**
+ * Preview-env handler core — import-light, dependency-injected.
+ *
+ * The POST /api/git/preview-env route (src/routes/api/git/preview-env/
+ * +server.ts) is a thin wrapper that resolves the real dependencies
+ * (authorize, getGitRepository, getGitCredential, previewRepoEnvFiles, the
+ * SSRF guards) and calls this function. The route performs the HTTP/status
+ * mapping (json(..., { status: NNN })), so the OpenAPI generator (which
+ * statically scans the +server.ts handler body) sees all status codes.
+ *
+ * Keeping the business/security logic here — with all external dependencies
+ * injected — makes the EXACT production pipeline (permission gate, body
+ * parsing, SSRF/credential/path guards, error handling) directly testable
+ * without importing the SvelteKit route (which transitively loads the native
+ * database layer) or leaving global mock.module() state behind.
+ *
+ * The authorization regression tests in tests/preview-env-security.test.ts
+ * execute this function with injected fakes. The tested function IS the
+ * production pipeline invoked by the POST route — if the route's
+ * `auth.can('git','edit')` gate is removed, the tests break.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PreviewEnvDependencies {
+	/** Resolve the auth context for the request cookies (authorization gate). */
+	authorize: (cookies: unknown) => Promise<PreviewEnvAuthContext>;
+	/** Look up an existing repository by id. */
+	getGitRepository: (id: number) => Promise<PreviewEnvRepository | null>;
+	/** Look up a stored credential by id. */
+	getGitCredential: (id: number) => Promise<PreviewEnvCredential | null>;
+	/** Clone the repo and read env files. */
+	previewRepoEnvFiles: (opts: PreviewEnvPreviewOptions) => Promise<PreviewEnvPreviewResult>;
+	/** SSRF + transport denylist guard. Throws on unsafe target. */
+	assertSafeRepoTarget: (url: string) => void;
+	/** Credential-exfiltration defense. Throws on host mismatch. */
+	assertCredentialHostMatch: (url: string, credential: PreviewEnvCredential) => void;
+}
+
+export interface PreviewEnvAuthContext {
+	authEnabled: boolean;
+	isAuthenticated: boolean;
+	user: unknown;
+	isAdmin: boolean;
+	isEnterprise: boolean;
+	can: (resource: string, action: string) => Promise<boolean>;
+}
+
+export interface PreviewEnvRepository {
+	url: string;
+	branch: string;
+	credentialId: number | null;
+}
+
+export interface PreviewEnvCredential {
+	id: number;
+	name: string;
+	authType: string;
+	username: string;
+	secret?: string;
+}
+
+export interface PreviewEnvPreviewOptions {
+	repoUrl: string;
+	branch: string;
+	credential: PreviewEnvCredential | null;
+	composePath: string;
+	envFilePath: string | null;
+}
+
+export interface PreviewEnvPreviewResult {
+	vars: Record<string, string>;
+	sources: Record<string, string>;
+	error?: string;
+}
+
+/**
+ * The result of the preview-env pipeline. The route maps this to an HTTP
+ * response (status + json body).
+ */
+export type PreviewEnvOutcome =
+	| { kind: 'success'; vars: Record<string, string>; sources: Record<string, string> }
+	| { kind: 'permission-denied' }
+	| { kind: 'bad-request'; message: string; vars?: Record<string, string>; sources?: Record<string, string> }
+	| { kind: 'not-found' }
+	| { kind: 'error'; message: string };
+
+// ---------------------------------------------------------------------------
+// Handler core
+// ---------------------------------------------------------------------------
+
+/**
+ * The preview-env handler pipeline. This is the SAME code path the POST route
+ * executes (the route resolves the real dependencies and forwards to this
+ * function), so testing this function with injected fakes exercises the real
+ * production logic — not a mirror.
+ *
+ * The `git:edit` permission gate (PR #1343) runs BEFORE `request.json()`
+ * (attacker-controlled input), repository/credential lookup, URL processing,
+ * and any git subprocess.
+ */
+export async function handlePreviewEnv(
+	deps: PreviewEnvDependencies,
+	args: { request: { json: () => Promise<any> }; cookies: unknown }
+): Promise<PreviewEnvOutcome> {
+	const auth = await deps.authorize(args.cookies);
+
+	// Permission gate (PR #1343): the endpoint clones a USER-SUPPLIED URL and
+	// reads env files from it, so it is gated on the git:edit permission —
+	// the EXACT same model as POST /api/git/branches. This single check covers
+	// every authenticated case:
+	//   - auth disabled        -> can('git','edit') is true, allowed to continue;
+	//   - auth enabled + unauthenticated -> can('git','edit') is false -> 403;
+	//   - auth enabled + read-only      -> can('git','edit') is false -> 403;
+	//   - auth enabled + git:edit       -> allowed to continue.
+	// (There is deliberately no separate 401 branch — an unauthenticated
+	// request simply lacks the git:edit permission and is denied, matching
+	// /api/git/branches.)
+	if (auth.authEnabled && !(await auth.can('git', 'edit'))) {
+		return { kind: 'permission-denied' };
+	}
+
+	try {
+		const data = await args.request.json();
+
+		if (!data.composePath || typeof data.composePath !== 'string') {
+			return { kind: 'bad-request', message: 'Compose path is required' };
+		}
+
+		let repoUrl: string;
+		let branch: string = 'main';
+		let credentialId: number | null = null;
+
+		if (data.repositoryId) {
+			// Use existing repository
+			const repo = await deps.getGitRepository(data.repositoryId);
+			if (!repo) {
+				return { kind: 'not-found' };
+			}
+			repoUrl = repo.url;
+			// An explicit branch (e.g. a per-stack override being previewed)
+			// wins over the repository default.
+			branch = typeof data.branch === 'string' && data.branch.trim() ? data.branch.trim() : repo.branch;
+			credentialId = repo.credentialId;
+		} else if (data.url) {
+			// New repository details
+			repoUrl = data.url;
+			branch = data.branch || 'main';
+			credentialId = data.credentialId || null;
+		} else {
+			return { kind: 'bad-request', message: 'Either repositoryId or url is required' };
+		}
+
+		// Get credential if specified
+		let credential: PreviewEnvCredential | null = null;
+		if (credentialId) {
+			credential = await deps.getGitCredential(credentialId);
+		}
+
+		// Security (PR #1343 maintainer review): the preview endpoint clones a
+		// USER-SUPPLIED URL and reads env files from it. Run the shared guards
+		// BEFORE previewRepoEnvFiles spawns git / reads files.
+		//  1. assertSafeRepoTarget — SSRF + transport denylist.
+		try {
+			deps.assertSafeRepoTarget(repoUrl);
+		} catch (e: any) {
+			return { kind: 'bad-request', message: e.message || 'Invalid repository URL' };
+		}
+		//  2. assertCredentialHostMatch — a raw url may only be paired with a
+		//     stored credential plausibly for that host (exfiltration defense).
+		//     The repositoryId path is safe (user's own stored config).
+		if (data.url && credentialId && credential) {
+			try {
+				deps.assertCredentialHostMatch(repoUrl, credential);
+			} catch (e: any) {
+				return { kind: 'bad-request', message: e.message || 'Invalid repository URL' };
+			}
+		}
+
+		const result = await deps.previewRepoEnvFiles({
+			repoUrl,
+			branch,
+			credential,
+			composePath: data.composePath,
+			envFilePath: data.envFilePath || null
+		});
+
+		if (result.error) {
+			return { kind: 'bad-request', message: result.error, vars: {}, sources: {} };
+		}
+
+		return { kind: 'success', vars: result.vars, sources: result.sources };
+	} catch (error: any) {
+		return { kind: 'error', message: error.message || 'Failed to preview env files' };
+	}
+}

src/routes/api/git/branches/+server.ts

@@ -0,0 +1,120 @@
+import { json } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { getGitRepository, getGitCredential } from '$lib/server/db';
+import { authorize } from '$lib/server/authorize';
+import { listRemoteBranches } from '$lib/server/git';
+import { assertSafeRepoTarget, assertCredentialHostMatch } from '$lib/server/git-branch-lookup';
+
+/**
+ * POST /api/git/branches
+ * List remote branches for a repository via `git ls-remote`.
+ *
+ * SECURITY (PR #1343 maintainer review, rounds 1+2): two guards run before
+ * any git subprocess is spawned.
+ *  1. assertSafeRepoTarget — the shared SSRF policy (delegated to
+ *     isSafeNotificationUrl, src/lib/server/url-safety.ts): loopback,
+ *     link-local / cloud-metadata and other reserved/dangerous targets are
+ *     rejected, while ordinary private-LAN addresses are INTENTIONALLY
+ *     ALLOWED so self-hosted Git servers on RFC1918 ranges (10.x /
+ *     192.168.x / 172.16-31.x) keep working. Runs on BOTH the `url` and
+ *     `repositoryId` paths (a stored repository's URL could also point
+ *     internal).
+ *  2. assertCredentialHostMatch — a raw `url` may only be paired with a
+ *     stored `credentialId` when the credential is plausibly for that host
+ *     (credential-exfiltration defense). The `repositoryId` path is safe —
+ *     the pairing is the user's own stored repository config, not an
+ *     attacker-chosen url+credential combo.
+ * The `ls-remote` itself is bounded by a hard timeout (see listRemoteBranches
+ * in src/lib/server/git.ts) — clone/pull/fetch stay unbounded.
+ *
+ * Body: {
+ *   repositoryId?: number,     // Existing repository (uses its url + credential)
+ *   url?: string,              // OR a new repository URL
+ *   credentialId?: number|null // Credential for the url (new-repo flow)
+ * }
+ *
+ * Returns: { branches: string[] }
+ */
+/**
+ * @openapi
+ * summary: List remote branches for a git repository via `git ls-remote`
+ * description: Accepts either repositoryId (an existing repository, using its stored URL and credential) or url + credentialId (a new repository). SECURITY: the repository target is checked against the shared SSRF policy — loopback, link-local/cloud-metadata and other reserved dangerous targets are rejected, while ordinary private-LAN addresses are intentionally allowed so self-hosted Git servers remain supported. A raw url may only be paired with a stored credentialId whose username plausibly matches that host (SSH credentials are always allowed). The ls-remote is bounded by a hard timeout.
+ * body: {repositoryId:integer, url:string, credentialId:integer}
+ * body-example: {"url":"https://github.com/example/repo.git","credentialId":2}
+ * resp-200: {branches:array<string>!}
+ * resp-200-example: {"branches":["main","develop","feature/test"]}
+ * resp-400: The URL points at a loopback/link-local/metadata/reserved target, the credential does not match the URL host, or neither repositoryId nor url was supplied
+ * resp-403: Permission denied (requires git:edit)
+ * resp-404: The referenced repository does not exist
+ * resp-500: Failed to fetch branches (ls-remote error or timeout)
+ */
+export const POST: RequestHandler = async ({ request, cookies }) => {
+	const auth = await authorize(cookies);
+	if (auth.authEnabled && !await auth.can('git', 'edit')) {
+		return json({ error: 'Permission denied' }, { status: 403 });
+	}
+
+	try {
+		const body = await request.json();
+		const { repositoryId, url, credentialId } = body as {
+			repositoryId?: number;
+			url?: string;
+			credentialId?: number | null;
+		};
+
+		let repoUrl: string;
+		let credId: number | undefined;
+
+		if (repositoryId) {
+			const repo = await getGitRepository(repositoryId);
+			if (!repo) {
+				return json({ error: 'Repository not found' }, { status: 404 });
+			}
+			repoUrl = repo.url;
+			credId = repo.credentialId ?? undefined;
+		} else if (url) {
+			repoUrl = url;
+			credId = credentialId ?? undefined;
+		} else {
+			return json({ error: 'repositoryId or url is required' }, { status: 400 });
+		}
+
+		// Guard 1 (SSRF): the shared SSRF policy rejects loopback /
+		// link-local / cloud-metadata / reserved targets; ordinary
+		// private-LAN addresses are intentionally allowed (self-hosted Git).
+		// Runs on BOTH paths — a stored repository's URL could also point
+		// internal.
+		try {
+			assertSafeRepoTarget(repoUrl);
+		} catch (e: any) {
+			return json({ error: e.message || 'Invalid repository URL' }, { status: 400 });
+		}
+
+		// Guard 2 (credential exfiltration): when a raw url is paired with a
+		// stored credential, verify the credential is plausibly for that host.
+		// The repositoryId path is safe — the pairing is the user's own stored
+		// repository config, not an attacker-chosen url+credential combo.
+		if (url && credId != null) {
+			const credential = await getGitCredential(credId);
+			if (!credential) {
+				return json({ error: 'Credential not found' }, { status: 404 });
+			}
+			try {
+				assertCredentialHostMatch(repoUrl, credential);
+			} catch (e: any) {
+				return json({ error: e.message || 'Invalid repository URL' }, { status: 400 });
+			}
+		}
+
+		const result = await listRemoteBranches({ url: repoUrl, credentialId: credId });
+
+		if (result.error) {
+			return json({ error: 'Failed to fetch branches: ' + result.error }, { status: 500 });
+		}
+
+		return json({ branches: result.branches });
+	} catch (error: any) {
+		console.error('Failed to fetch branches:', error);
+		return json({ error: 'Failed to fetch branches' }, { status: 500 });
+	}
+};

src/routes/api/git/preview-env/+server.ts

@@ -2,13 +2,32 @@ import { json } from '@sveltejs/kit';
 import type { RequestHandler } from './$types';
 import { getGitRepository, getGitCredential } from '$lib/server/db';
 import { previewRepoEnvFiles } from '$lib/server/git';
+import { assertSafeRepoTarget, assertCredentialHostMatch } from '$lib/server/git-branch-lookup';
 import { authorize } from '$lib/server/authorize';
-
+import { handlePreviewEnv, type PreviewEnvAuthContext, type PreviewEnvCredential, type PreviewEnvRepository, type PreviewEnvPreviewOptions, type PreviewEnvPreviewResult } from '$lib/server/preview-env-handler';
 /**
  * POST /api/git/preview-env
  * Clone a git repository to a temp directory and read env files for preview.
  * Used when creating a new git stack to populate the env editor.
  *
+ * SECURITY (PR #1343 maintainer review): the endpoint clones a
+ * USER-SUPPLIED URL and reads env files from it, so it is gated on the
+ * `git:edit` permission (same model as /api/git/branches) — an authenticated
+ * read-only user cannot use it to clone an arbitrary repository. Three guards
+ * run BEFORE any git subprocess is spawned / files are read:
+ *  1. assertSafeRepoTarget — the shared SSRF policy. Loopback, link-local /
+ *     cloud-metadata and other reserved/dangerous targets are rejected, while
+ *     ordinary private-LAN addresses are intentionally allowed so self-hosted
+ *     Git servers on RFC1918 ranges (10.x / 192.168.x / 172.16-31.x) keep
+ *     working. The ext::/file:: transports and local paths are rejected.
+ *  2. assertCredentialHostMatch — a raw `url` may only be paired with a
+ *     stored `credentialId` when the credential is plausibly for that host
+ *     (credential-exfiltration defense). The `repositoryId` path is safe — the
+ *     pairing is the user's own stored repository config, not an
+ *     attacker-chosen url+credential combo.
+ *  3. repoFilePath — composePath/envFilePath are constrained to stay inside
+ *     the cloned repository (path traversal).
+ *
  * Body: {
  *   repositoryId?: number,           // Existing repository
  *   url?: string,                    // OR new repo URL
@@ -29,76 +48,52 @@ import { authorize } from '$lib/server/authorize';
 /**
  * @openapi
  * summary: Clone a repo to a temp dir and preview its merged env-file variables for the git-stack env editor
- * description: repositoryId from GET /api/git/repositories. credentialId from GET /api/git/credentials.
+ * description: repositoryId from GET /api/git/repositories. credentialId from GET /api/git/credentials. SECURITY: requires the git:edit permission when authentication is enabled (403 otherwise). The repository target is checked against the shared SSRF policy — loopback, link-local/cloud-metadata and other reserved dangerous targets are rejected, while ordinary private-LAN addresses are intentionally allowed so self-hosted Git servers remain supported. The ext::/file:: transports and local paths are rejected; the raw url may only be paired with a stored credentialId whose username plausibly matches that host (exfiltration defense); and composePath/envFilePath are constrained to stay inside the cloned repository (path traversal).
  * body: {repositoryId:integer, url:string, branch:string, credentialId:integer, composePath:string!, envFilePath:string}
  * body-example: {"repositoryId":3,"composePath":"docker-compose.yml","envFilePath":".env.prod"}
  * resp-200: {vars:object!, sources:object!}
- * resp-400: composePath missing, neither repositoryId nor url supplied, or the repo/env-file preview reported an error
- * resp-401: Authentication required
+ * resp-400: composePath missing, neither repositoryId nor url supplied, the URL points at a loopback/link-local/metadata/reserved target, the URL is an unsupported transport (ext::/file::), the credential does not match the URL host, the compose/env path escapes the repository, or the repo/env-file preview reported an error
+ * resp-403: Permission denied (requires the git:edit permission — same model as /api/git/branches; an unauthenticated or read-only user is denied here rather than via a separate 401)
  * resp-404: The referenced repository does not exist
  * resp-500: Failed to preview the env files (clone or read error)
  */
 export const POST: RequestHandler = async ({ request, cookies }) => {
-	const auth = await authorize(cookies);
+	// Thin SvelteKit route wrapper. Resolves the real dependencies and calls
+	// the import-light, dependency-injected handler core
+	// (src/lib/server/preview-env-handler.ts), which runs the EXACT production
+	// pipeline: the `git:edit` permission gate, body parsing, SSRF/credential
+	// guards, and the env-file preview. This route performs the HTTP/status
+	// mapping so the OpenAPI generator (which statically scans the handler
+	// body) sees all status codes.
+	const deps = {
+		// authorize() returns the full auth context (authEnabled, can, …).
+		authorize: async (_cookies: unknown) => {
+			const auth = await authorize(cookies);
+			return auth as PreviewEnvAuthContext;
+		},
+		getGitRepository: async (id: number) => getGitRepository(id) as Promise<PreviewEnvRepository | null>,
+		getGitCredential: async (id: number) => getGitCredential(id) as Promise<PreviewEnvCredential | null>,
+		previewRepoEnvFiles: async (opts: PreviewEnvPreviewOptions) =>
+			previewRepoEnvFiles(opts) as Promise<PreviewEnvPreviewResult>,
+		assertSafeRepoTarget,
+		assertCredentialHostMatch: assertCredentialHostMatch as (url: string, credential: PreviewEnvCredential) => void
+	};
+	const outcome = await handlePreviewEnv(deps, { request, cookies });
 
-	// Basic permission check - must be able to create stacks
-	if (auth.authEnabled && !auth.isAuthenticated) {
-		return json({ error: 'Authentication required' }, { status: 401 });
-	}
-
-	try {
-		const data = await request.json();
-
-		if (!data.composePath || typeof data.composePath !== 'string') {
-			return json({ error: 'Compose path is required' }, { status: 400 });
+	switch (outcome.kind) {
+		case 'success':
+			return json({ vars: outcome.vars, sources: outcome.sources });
+		case 'permission-denied':
+			return json({ error: 'Permission denied' }, { status: 403 });
+		case 'bad-request': {
+			const body: Record<string, unknown> = { error: outcome.message };
+			if (outcome.vars) body.vars = outcome.vars;
+			if (outcome.sources) body.sources = outcome.sources;
+			return json(body, { status: 400 });
 		}
-
-		let repoUrl: string;
-		let branch: string = 'main';
-		let credentialId: number | null = null;
-
-		if (data.repositoryId) {
-			// Use existing repository
-			const repo = await getGitRepository(data.repositoryId);
-			if (!repo) {
-				return json({ error: 'Repository not found' }, { status: 404 });
-			}
-			repoUrl = repo.url;
-			branch = repo.branch;
-			credentialId = repo.credentialId;
-		} else if (data.url) {
-			// New repository details
-			repoUrl = data.url;
-			branch = data.branch || 'main';
-			credentialId = data.credentialId || null;
-		} else {
-			return json({ error: 'Either repositoryId or url is required' }, { status: 400 });
-		}
-
-		// Get credential if specified
-		let credential = null;
-		if (credentialId) {
-			credential = await getGitCredential(credentialId);
-		}
-
-		const result = await previewRepoEnvFiles({
-			repoUrl,
-			branch,
-			credential,
-			composePath: data.composePath,
-			envFilePath: data.envFilePath || null
-		});
-
-		if (result.error) {
-			return json({ vars: {}, sources: {}, error: result.error }, { status: 400 });
-		}
-
-		return json({
-			vars: result.vars,
-			sources: result.sources
-		});
-	} catch (error: any) {
-		console.error('Failed to preview env files:', error);
-		return json({ error: error.message || 'Failed to preview env files' }, { status: 500 });
+		case 'not-found':
+			return json({ error: 'Repository not found' }, { status: 404 });
+		case 'error':
+			return json({ error: outcome.message }, { status: 500 });
 	}
 };

src/routes/api/git/repositories/test/+server.ts

@@ -1,6 +1,8 @@
 import { json } from '@sveltejs/kit';
 import type { RequestHandler } from './$types';
 import { testRepositoryConfig } from '$lib/server/git';
+import { getGitCredential } from '$lib/server/db';
+import { assertSafeRepoTarget, assertCredentialHostMatch } from '$lib/server/git-branch-lookup';
 import { authorize } from '$lib/server/authorize';
 
 /**
@@ -17,13 +19,14 @@ import { authorize } from '$lib/server/authorize';
 /**
  * @openapi
  * summary: Test an unsaved repository configuration (url/branch/credentialId) before creating it
- * description: credentialId from GET /api/git/credentials.
+ * description: credentialId from GET /api/git/credentials. SECURITY: the repository target is checked against the shared SSRF policy — loopback, link-local/cloud-metadata and other reserved dangerous targets are rejected, while ordinary private-LAN addresses are intentionally allowed so self-hosted Git servers remain supported. The ext::/file:: transports and local paths are rejected; the raw url may only be paired with a stored credentialId whose username plausibly matches that host (exfiltration defense).
  * body: {url:string!, branch:string, credentialId:integer}
  * body-example: {"url":"https://github.com/example/homelab.git","branch":"main","credentialId":2}
  * resp-200: {success:boolean!, error:string}
  * resp-200-example: {"success":true}
- * resp-400: The url field is missing
+ * resp-400: The url field is missing, the URL points at a loopback/link-local/metadata/reserved target, the URL is an unsupported transport, or the credential does not match the URL host
  * resp-403: Caller lacks the settings:manage permission
+ * resp-404: The referenced credential does not exist
  * resp-500: The connectivity test failed
  */
 export const POST: RequestHandler = async ({ request, cookies }) => {
@@ -39,6 +42,29 @@ export const POST: RequestHandler = async ({ request, cookies }) => {
 			return json({ error: 'Repository URL is required' }, { status: 400 });
 		}
 
+		// Security (PR #1343 maintainer review): the test endpoint spawns git
+		// (ls-remote + clone) with a USER-SUPPLIED url + credentialId. Run the
+		// shared guards BEFORE testRepositoryConfig spawns anything.
+		//  1. assertSafeRepoTarget — SSRF + transport denylist.
+		try {
+			assertSafeRepoTarget(body.url);
+		} catch (e: any) {
+			return json({ success: false, error: e.message || 'Invalid repository URL' }, { status: 400 });
+		}
+		//  2. assertCredentialHostMatch — raw url + stored credential must be
+		//     plausibly for that host (exfiltration defense).
+		if (body.credentialId != null && body.credentialId !== undefined) {
+			const credential = await getGitCredential(body.credentialId);
+			if (!credential) {
+				return json({ success: false, error: 'Credential not found' }, { status: 404 });
+			}
+			try {
+				assertCredentialHostMatch(body.url, credential);
+			} catch (e: any) {
+				return json({ success: false, error: e.message || 'Invalid repository URL' }, { status: 400 });
+			}
+		}
+
 		const result = await testRepositoryConfig({
 			url: body.url,
 			branch: body.branch || 'main',

src/routes/api/git/stacks/+server.ts

@@ -154,6 +154,12 @@ export const POST: RequestHandler = async (event) => {
 			stackName: trimmedStackName,
 			environmentId: data.environmentId || null,
 			repositoryId: repositoryId,
+			// Per-stack branch override — only when targeting an existing repository.
+			// In new-repo mode data.branch becomes the repository's default instead;
+			// the stack inherits it (branch stays null).
+			...(data.repositoryId && typeof data.branch === 'string' && data.branch.trim()
+				? { branch: data.branch.trim() }
+				: {}),
 			composePath: data.composePath || 'compose.yaml',
 			envFilePath: data.envFilePath || null,
 			autoUpdate: data.autoUpdate || false,

src/routes/api/git/stacks/[id]/+server.ts

@@ -2,6 +2,7 @@ import { json } from '@sveltejs/kit';
 import type { RequestHandler } from './$types';
 import { getGitStack, updateGitStack, deleteGitStack, deleteStackSource, updateStackSourceName, updateStackEnvVarsName, setStackEnvVars, getStackEnvVars, deleteStackEnvVars, updateStackSource } from '$lib/server/db';
 import { deleteGitStackFiles, deployGitStack } from '$lib/server/git';
+import { normalizeStackBranchUpdate } from '$lib/git-stack-branch';
 import { authorize } from '$lib/server/authorize';
 import { registerSchedule, unregisterSchedule } from '$lib/server/scheduler';
 import { auditGitStack } from '$lib/server/audit';
@@ -109,8 +110,24 @@ export const PUT: RequestHandler = async (event) => {
 		}
 
 		const oldStackName = existing.stackName;
+
+		// Per-stack branch override is a partial update. The shared normalizer
+		// (normalizeStackBranchUpdate, src/lib/git-stack-branch.ts) encodes the
+		// API contract:
+		//   - `branch` key ABSENT  -> leave the stored value untouched;
+		//   - explicit null         -> clear the override (inherit repo default);
+		//   - blank / whitespace    -> normalised to clear;
+		//   - non-blank string      -> set the override (stored trimmed).
+		// updateGitStack writes the column only when the key is defined
+		// (`data.branch !== undefined`), so we pass `undefined` for the
+		// "absent" case to leave the stored value untouched.
+		const branchNext = normalizeStackBranchUpdate(existing.branch, data);
+		const branchValue: string | null | undefined =
+			'branch' in data ? branchNext.next : undefined;
+
 		const updated = await updateGitStack(id, {
 			stackName: data.stackName,
+			branch: branchValue,
 			composePath: data.composePath,
 			envFilePath: data.envFilePath,
 			autoUpdate: data.autoUpdate,

src/routes/stacks/+page.svelte

@@ -51,6 +51,7 @@
 	import { ErrorDialog } from '$lib/components/ui/error-dialog';
 	import { formatHostPortUrl } from '$lib/utils/url';
 	import { formatBytes, formatBytesCompact } from '$lib/utils/format';
+	import { effectiveStackBranch } from '$lib/git-stack-branch';
 
 	type SortField = 'name' | 'containers' | 'status' | 'cpu' | 'memory';
 	type SortDirection = 'asc' | 'desc';
@@ -938,7 +939,7 @@
 		return stack.status;
 	}
 
-	async function openGitModal(gitStack?: any) {
+	async function openGitModal(gitStack: any = undefined) {
 		editingGitStack = gitStack || null;
 		// Fetch repositories and credentials before opening modal
 		try {
@@ -1115,10 +1116,13 @@
 		editingStackName = name;
 		stackModalReadonly = true;
 		const src = getStackSource(name);
+		// Effective branch: per-stack override wins, else repository default
+		// (shared with the server-side resolver in src/lib/git-stack-branch.ts).
+		const eff = effectiveStackBranch(src?.gitStack ?? null, src?.repository ?? undefined);
 		stackModalGitInfo = {
 			commit: src?.gitStack?.lastCommit || undefined,
 			url: src?.repository?.url || undefined,
-			branch: src?.repository?.branch || undefined
+			branch: eff.branch
 		};
 		showEditModal = true;
 	}

src/routes/stacks/BranchCombobox.svelte

@@ -0,0 +1,147 @@
+<script lang="ts">
+	import { ChevronDown, Check, GitBranch, Loader2 } from 'lucide-svelte';
+	import * as Command from '$lib/components/ui/command';
+	import * as Popover from '$lib/components/ui/popover';
+	import { buttonVariants } from '$lib/components/ui/button';
+	import { cn } from '$lib/utils';
+
+	/**
+	 * Free-text, searchable branch picker.
+	 *
+	 * Reuses the repository's existing Popover + Command primitives (the same
+	 * interaction/style pattern as TimezoneSelector.svelte) so the user can
+	 * both pick a *discovered* branch and type an *arbitrary* branch name.
+	 *
+	 * Behaviour contract (maintainer review for the new-repository branch
+	 * field):
+	 *  - fetched branches appear in the list and are searchable/selectable;
+	 *  - typing a branch NOT in the list offers "Use \"<query>\"", and clicking
+	 *    it (or pressing Enter) selects that exact value;
+	 *  - if branch enumeration fails or returns nothing, the user can still
+	 *    type and select any branch manually (the "Use \"<query>\"" row always
+	 *    appears when the trimmed query is non-blank);
+	 *  - an existing value that a later enumeration did NOT return is retained
+	 *    (never silently reset), and the trigger keeps showing it;
+	 *  - while enumeration is in flight a loader is shown but the field stays
+	 *    usable;
+	 *  - keyboard selection (ArrowUp/Down + Enter) works for both fetched rows
+	 *    and the free-text row.
+	 */
+	interface Props {
+		/** Current branch value (e.g. "main"). */
+		value: string;
+		/** Discovered branch names (from /api/git/branches). */
+		branches: string[];
+		/** True while branch enumeration is in flight. */
+		loading: boolean;
+		/** Called with the selected value (a fetched branch or the typed name). */
+		onchange?: (value: string) => void;
+		/** Called when the user clears the field (empty value). */
+		onclear?: () => void;
+		id?: string;
+		class?: string;
+		placeholder?: string;
+	}
+
+	let {
+		value = $bindable('main'),
+		branches = [],
+		loading = false,
+		onchange,
+		onclear,
+		id,
+		class: className,
+		placeholder = 'main'
+	}: Props = $props();
+
+	let open = $state(false);
+	let searchQuery = $state('');
+
+	function selectBranch(branch: string) {
+		value = branch;
+		open = false;
+		searchQuery = '';
+		onchange?.(branch);
+	}
+
+	function clearBranch() {
+		value = '';
+		open = false;
+		searchQuery = '';
+		onclear?.();
+	}
+
+	// Filtered fetched branches, ordered so the current value (if not in the
+	// fetched list) still surfaces near the top for easy re-selection.
+	const filteredBranches = $derived(
+		searchQuery
+			? branches.filter((b) => b.toLowerCase().includes(searchQuery.toLowerCase()))
+			: branches
+	);
+
+	// Offer the typed name as a selectable row when it is non-blank and is not
+	// already one of the fetched branches.
+	const freeTextBranch = $derived(
+		searchQuery.trim() && !branches.includes(searchQuery.trim()) ? searchQuery.trim() : ''
+	);
+
+	// Display: show the current value; fall back to the placeholder when empty
+	// (e.g. no branch chosen -> "main").
+	const displayValue = value || placeholder;
+</script>
+
+<Popover.Root bind:open>
+	<Popover.Trigger>
+		<span
+			role="combobox"
+			aria-expanded={open}
+			class={cn(buttonVariants({ variant: 'outline' }), 'w-full justify-between cursor-pointer select-none', className)}
+			{id}
+		>
+			<span class="flex items-center gap-2 truncate">
+				<GitBranch class="h-4 w-4 shrink-0 text-muted-foreground" />
+				{#if loading}
+					<Loader2 class="h-4 w-4 animate-spin" />
+					<span class="text-muted-foreground">Loading branches…</span>
+				{:else}
+					<span class="truncate">{displayValue}</span>
+				{/if}
+			</span>
+			<ChevronDown class="ml-2 h-4 w-4 shrink-0 opacity-50" />
+		</span>
+	</Popover.Trigger>
+	<Popover.Content class="w-[350px] p-0 z-[200]" align="start">
+		<Command.Root shouldFilter={false}>
+			<Command.Input bind:value={searchQuery} placeholder="Type a branch name…" />
+			<Command.List class="max-h-[300px]">
+				{#if loading}
+					<Command.Empty>Loading branches…</Command.Empty>
+				{:else}
+					{#if filteredBranches.length > 0}
+						<Command.Group heading="Branches">
+							{#each filteredBranches as branch}
+								<Command.Item value={branch} onSelect={() => selectBranch(branch)}>
+									<Check class={cn('mr-2 h-4 w-4', value === branch ? 'opacity-100' : 'opacity-0')} />
+									<span class="truncate">{branch}</span>
+								</Command.Item>
+							{/each}
+						</Command.Group>
+					{/if}
+					{#if freeTextBranch}
+						<Command.Group heading="Custom">
+							<Command.Item value={freeTextBranch} onSelect={() => selectBranch(freeTextBranch)}>
+								<GitBranch class="mr-2 h-4 w-4" />
+								<span class="truncate">Use "{freeTextBranch}"</span>
+							</Command.Item>
+						</Command.Group>
+					{/if}
+					{#if filteredBranches.length === 0 && !freeTextBranch && !loading}
+						<Command.Empty>
+							Type a branch name (e.g. "main") or pick from the list.
+						</Command.Empty>
+					{/if}
+				{/if}
+			</Command.List>
+		</Command.Root>
+	</Popover.Content>
+</Popover.Root>

src/routes/stacks/GitSourceBadge.svelte

@@ -3,14 +3,22 @@
 	import { GitBranch, GitCommitHorizontal } from 'lucide-svelte';
 	import { forgeIcon } from '$lib/utils/git-forge';
 	import { appSettings } from '$lib/stores/settings';
+import { effectiveStackBranch } from '$lib/git-stack-branch';
 
 	interface Props {
-		source: { repository?: { url?: string; branch?: string } | null; gitStack?: { lastCommit?: string | null } | null };
+		source: { repository?: { url?: string; branch?: string } | null; gitStack?: { lastCommit?: string | null; branch?: string | null } | null };
 	}
 	let { source }: Props = $props();
 
 	const ForgeIcon = $derived(forgeIcon(source.repository?.url));
 	const showHash = $derived(!!source.gitStack?.lastCommit && $appSettings.showGitCommitHash);
+	// Effective branch: per-stack override wins, else repository default
+	// (shared with the server-side resolver in src/lib/git-stack-branch.ts).
+	const eff = $derived(
+		effectiveStackBranch(source.gitStack ?? null, source.repository ?? undefined)
+	);
+	const effectiveBranch = eff.branch;
+	const isPerStackBranch = eff.perStack === true;
 	// A tooltip is only worth showing when there's real git info in it.
 	const hasGitInfo = $derived(!!source.gitStack?.lastCommit || !!source.repository);
 </script>
@@ -41,10 +49,13 @@
 					</div>
 				{/if}
 				{#if source.repository}
-					{#if source.repository.branch}
+					{#if effectiveBranch}
 						<div class="flex items-center gap-2">
 							<GitBranch class="w-3.5 h-3.5 shrink-0 text-muted-foreground" />
-							<span class="text-xs">{source.repository.branch}</span>
+							<span class="text-xs">{effectiveBranch}</span>
+							{#if isPerStackBranch}
+								<span class="text-[10px] text-muted-foreground">(per-stack)</span>
+							{/if}
 						</div>
 					{/if}
 					<div class="flex items-center gap-2">

src/routes/stacks/GitStackModal.svelte

@@ -4,7 +4,6 @@
 	import * as Dialog from '$lib/components/ui/dialog';
 	import * as Select from '$lib/components/ui/select';
 	import { Label } from '$lib/components/ui/label';
-	import { Badge } from '$lib/components/ui/badge';
 	import { Input } from '$lib/components/ui/input';
 	import { TogglePill } from '$lib/components/ui/toggle-pill';
 	import { Loader2, GitBranch, RefreshCw, Webhook, Rocket, RefreshCcw, Copy, Check, XCircle, FolderGit2, Github, Key, KeyRound, Lock, FileText, HelpCircle, GripVertical, X, Download, Hammer, ArrowDownToLine, Zap, FolderOpen, Ban, TriangleAlert, Settings2, Archive } from 'lucide-svelte';
@@ -17,6 +16,7 @@
 	import CronEditor from '$lib/components/cron-editor.svelte';
 	import StackEnvVarsPanel from '$lib/components/StackEnvVarsPanel.svelte';
 	import SecretProviderPicker from '$lib/components/SecretProviderPicker.svelte';
+	import BranchCombobox from './BranchCombobox.svelte';
 	import { type EnvVar, type ValidationResult } from '$lib/components/StackEnvVarsEditor.svelte';
 	import { toast } from 'svelte-sonner';
 	import { focusFirstInput } from '$lib/utils';
@@ -45,13 +45,14 @@
 		name: string;
 		url: string;
 		branch: string;
-		credential_id: number | null;
+		credentialId: number | null;
 	}
 
 	interface GitStack {
 		id: number;
 		stackName: string;
 		repositoryId: number;
+		branch?: string | null; // Per-stack branch override; null = use repository default
 		environmentId: number | null;
 		composePath: string;
 		envFilePath: string | null;
@@ -149,6 +150,21 @@
 	let showExistsWarning = $state(false);
 	let errors = $state<{ stackName?: string; repository?: string; repoName?: string; repoUrl?: string; webhookSecret?: string }>({});
 
+	// Branch selection
+	let formBranch = $state<string | null>(null);
+	let branches = $state<string[]>([]);
+	let branchesLoading = $state(false);
+	// Monotonic token that guards against a stale branch-enumeration response
+	// overwriting `branches` for a newer repository URL (the $effect below can
+	// fire multiple times as the repo selection changes; a slow response for
+	// repo A must not clobber the branch list belonging to repo B).
+	let branchesFetchSeq = 0;
+
+	// Sentinel select value meaning "no per-stack override — use the repository's
+	// default branch". Contains ':' which is invalid in git refs, so it can never
+	// collide with a real branch name.
+	const REPO_DEFAULT_BRANCH_VALUE = ':repository-default:';
+
 	// Stack name validation: Docker Compose requires lowercase; must start with a
 	// letter or number, and contain only lowercase letters, numbers, hyphens, underscores
 	const STACK_NAME_REGEX = /^[a-z0-9][a-z0-9_-]*$/;
@@ -361,6 +377,8 @@
 
 			if (formRepoMode === 'existing') {
 				body.repositoryId = formRepositoryId;
+				// Send the selected branch so env files are previewed from it (per-stack override)
+				body.branch = formBranch || undefined;
 			} else {
 				body.url = formNewRepoUrl;
 				body.branch = formNewRepoBranch || 'main';
@@ -448,9 +466,11 @@
 			formForceRedeploy = gitStack.forceRedeploy ?? false;
 			formDeployNow = false;
 			formSecretProviderId = null;
-			
+
 			// Load secret provider binding
 			loadSecretProviderBindingForStack(gitStack.stackName);
+			// Per-stack branch override; null means "use the repository default"
+			formBranch = gitStack.branch ?? null;
 
 			// Load env files and overrides SYNCHRONOUSLY to avoid race conditions
 			// Wait for all loads to complete before allowing any other effect to run
@@ -497,6 +517,41 @@
 		}
 	}
 
+	async function fetchBranches() {
+		const seq = ++branchesFetchSeq;
+		branchesLoading = true;
+		branches = [];
+		try {
+			const body: Record<string, any> = {};
+			if (formRepoMode === 'existing' && formRepositoryId) {
+				body.repositoryId = formRepositoryId;
+			} else if (formRepoMode === 'new' && formNewRepoUrl) {
+				body.url = formNewRepoUrl;
+				body.credentialId = formNewRepoCredentialId;
+			} else {
+				return;
+			}
+			const response = await fetch('/api/git/branches', {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify(body)
+			});
+			// A newer fetch (or a repo change) superseded this one — drop the
+			// stale response so it cannot overwrite the new repo's branch list.
+			if (seq !== branchesFetchSeq) return;
+			if (response.ok) {
+				const data = await response.json();
+				if (seq !== branchesFetchSeq) return;
+				branches = data.branches || [];
+			}
+		} catch (e) {
+			if (seq !== branchesFetchSeq) return;
+			console.error('Failed to fetch branches:', e);
+		} finally {
+			if (seq === branchesFetchSeq) branchesLoading = false;
+		}
+	}
+
 	async function saveGitStack(deployAfterSave: boolean = false) {
 		errors = {};
 		let hasErrors = false;
@@ -589,6 +644,9 @@
 
 			if (formRepoMode === 'existing') {
 				body.repositoryId = formRepositoryId;
+				// Per-stack branch override — sent on both create and update so the
+				// stack payload is the single source of truth (null = inherit repo default)
+				body.branch = formBranch || null;
 			} else {
 				// Create new repo inline
 				body.repoName = formNewRepoName;
@@ -616,9 +674,10 @@
 			}
 
 			// Check if deployment failed
-			if (data.deployResult && !data.deployResult.success) {
+			const deployResult = data.deployResult as { success?: boolean; error?: string } | undefined;
+			if (deployResult && !deployResult.success) {
 				toast.error('Deployment failed', {
-					description: data.deployResult.error || 'Unknown error'
+					description: deployResult.error || 'Unknown error'
 				});
 				onSaved(); // Still refresh the list to show the new stack
 				onClose(); // Close modal, error shown as toast
@@ -634,6 +693,21 @@
 		}
 	}
 
+	// Fetch branches when repository selection changes
+	$effect(() => {
+		if (formRepoMode === 'existing' && formRepositoryId) {
+			void fetchBranches();
+			// A fresh stack inherits the repository's default until a branch is
+			// picked. When editing, the stored per-stack override (set in
+			// resetForm) must be preserved — null means repository default.
+			if (!gitStack) formBranch = null;
+		} else if (formRepoMode === 'new' && formNewRepoUrl) {
+			void fetchBranches();
+		} else {
+			branches = [];
+		}
+	});
+
 	// Auto-populate stack name from selected repo and compose path (only if user hasn't manually edited)
 	$effect(() => {
 		if (formRepoMode === 'existing' && formRepositoryId && !gitStack && !formStackNameUserModified) {
@@ -807,6 +881,42 @@
 								No repositories configured. Click "Add new" to add one.
 							</p>
 						{/if}
+						<!-- Branch selection for existing repository -->
+						{#if formRepoMode === 'existing' && selectedRepo}
+							<div class="space-y-2">
+								<Label for="existing-repo-branch">Branch</Label>
+								<Select.Root type="single" value={formBranch || REPO_DEFAULT_BRANCH_VALUE} onValueChange={(v) => { formBranch = v === REPO_DEFAULT_BRANCH_VALUE ? null : v; }}>
+									<Select.Trigger class="w-full">
+										<span class="flex items-center gap-2">
+											<GitBranch class="w-4 h-4 text-muted-foreground" />
+											{#if branchesLoading}
+												<Loader2 class="w-4 h-4 animate-spin" />
+											{:else if formBranch}
+												{formBranch}
+											{:else}
+												<span class="text-muted-foreground">Repository default ({selectedRepo.branch})</span>
+											{/if}
+										</span>
+									</Select.Trigger>
+									<Select.Content>
+										<Select.Item value={REPO_DEFAULT_BRANCH_VALUE}>
+											<span class="flex items-center gap-2">
+												<GitBranch class="w-4 h-4 text-muted-foreground" />
+												Repository default ({selectedRepo.branch})
+											</span>
+										</Select.Item>
+										{#if branches.length > 0}
+											{#each branches as branch}
+												{#if branch !== selectedRepo.branch}
+													<Select.Item value={branch}>{branch}</Select.Item>
+												{/if}
+											{/each}
+										{/if}
+									</Select.Content>
+								</Select.Root>
+								<p class="text-xs text-muted-foreground">Branch this stack deploys from. "Repository default" follows the branch configured on the repository.</p>
+							</div>
+						{/if}
 					{:else}
 						<div class="space-y-3 p-3 border rounded-md bg-muted/30">
 							<div class="space-y-2">
@@ -838,7 +948,21 @@
 							<div class="grid grid-cols-2 gap-3">
 								<div class="space-y-2">
 									<Label for="new-repo-branch">Branch</Label>
-									<Input id="new-repo-branch" bind:value={formNewRepoBranch} placeholder="main" />
+									<!-- Free-text, searchable branch picker. Supports both discovered
+									     branches and arbitrary typed names (maintainer review: a new/
+									     private repository whose branch enumeration fails must not force the
+									     user onto "main" — they can type the known branch name instead). The
+									     "main" default is preserved when no branch has been chosen, and a
+									     value not returned by enumeration is never silently reset. Server-side
+									     Git ref validation remains authoritative. -->
+									<BranchCombobox
+										id="new-repo-branch"
+										value={formNewRepoBranch}
+										branches={branches}
+										loading={branchesLoading}
+										placeholder="main"
+									/>
+									<p class="text-xs text-muted-foreground">Branch to deploy. Type a name (e.g. "main") or pick from the list.</p>
 								</div>
 								<div class="space-y-2">
 									<Label for="new-repo-credential">Credential</Label>
@@ -916,13 +1040,46 @@
 					<div class="flex items-center gap-2 text-xs text-muted-foreground bg-muted/50 rounded-md px-3 py-2">
 						<FolderGit2 class="w-3.5 h-3.5 shrink-0" />
 						<span class="truncate" title={selectedRepo.url}>{selectedRepo.url}</span>
-						{#if selectedRepo.branch}
-							<Badge variant="outline" class="text-2xs py-0 px-1.5 shrink-0">{selectedRepo.branch}</Badge>
-						{/if}
 					</div>
 				</div>
 			{/if}
 
+			{#if gitStack && selectedRepo}
+				<div class="space-y-2">
+					<Label for="stack-branch">Branch</Label>
+					<Select.Root type="single" value={formBranch || REPO_DEFAULT_BRANCH_VALUE} onValueChange={(v) => { formBranch = v === REPO_DEFAULT_BRANCH_VALUE ? null : v; }}>
+						<Select.Trigger class="w-full">
+							<span class="flex items-center gap-2">
+								<GitBranch class="w-4 h-4 text-muted-foreground" />
+								{#if branchesLoading}
+									<Loader2 class="w-4 h-4 animate-spin" />
+								{:else if formBranch}
+									{formBranch}
+								{:else}
+									<span class="text-muted-foreground">Repository default ({selectedRepo.branch})</span>
+								{/if}
+							</span>
+						</Select.Trigger>
+						<Select.Content>
+							<Select.Item value={REPO_DEFAULT_BRANCH_VALUE}>
+								<span class="flex items-center gap-2">
+									<GitBranch class="w-4 h-4 text-muted-foreground" />
+									Repository default ({selectedRepo.branch})
+								</span>
+							</Select.Item>
+							{#if branches.length > 0}
+								{#each branches as branch}
+									{#if branch !== selectedRepo.branch}
+										<Select.Item value={branch}>{branch}</Select.Item>
+									{/if}
+								{/each}
+							{/if}
+						</Select.Content>
+					</Select.Root>
+					<p class="text-xs text-muted-foreground">Branch this stack deploys from. "Repository default" follows the branch configured on the repository.</p>
+				</div>
+			{/if}
+
 			<div class="space-y-2">
 				<Label for="compose-path">Compose file path</Label>
 				<Input id="compose-path" bind:value={formComposePath} placeholder="compose.yaml" />