@akash-chowdhury-24/deployhub 2.0.34 → 2.0.35

package/README.md

@@ -297,6 +297,10 @@ deployhub logs                       # last deployment logs
 
 `buildId` looks like `{semver}-{stamp}` where the stamp is a short git SHA when available, otherwise a CI run id, otherwise a high-resolution timestamp. When `DOCKER_IMAGE_TAG` is left unset, Docker and Kubernetes use that same `buildId` as the image tag — so you can correlate an artifact in storage with the image that was pushed.
 
+**Docker and Kubernetes image rollback:** DeployHub first looks for that `buildId` tag in the local Docker cache. If it is missing (the normal case on a GitHub Actions runner), it **pulls the image from the registry**. Rebuild-from-artifact is only tried if that pull also fails. Interpreted backends (Python, Node, PHP, Rails) still cannot rebuild from the artifact alone — keep `pipeline.docker` enabled so the original deploy pushed the tag. After a Docker rollback starts the container, DeployHub runs the same port-publish check as a normal deploy.
+
+For session notes on how these behaviors were proven, see `CONTEXT.md`.
+
 ### Rollback is scoped per environment
 
 Each environment maintains its own independent deploy history. When you roll back an environment, DeployHub only considers builds that were actually deployed **to that environment** — never builds deployed to a different environment, even if they're more recent or share the same project.
@@ -458,7 +462,7 @@ Best when you serve static files from your own VPS or cloud VM. DeployHub upload
 | Deploy type | You provide |
 |-------------|-------------|
 | **ssh** | `SSH_HOST`, `SSH_USER`, `SSH_KEY`, deploy path |
-| **docker** | Docker host access / image registry per your setup |
+| **docker** | Image registry; then **Where should the container run?** — local (this machine / CI), SSH (remote Linux — `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH` like **ec2**), or raw `DOCKER_HOST` |
 | **ec2** | SSH credentials to EC2 instance |
 | **azure-vm** / **gcp-vm** | SSH to VM |
 | **kubernetes** | Cluster credentials (via env / kubeconfig) |
@@ -523,6 +527,7 @@ Backends always deploy to a **self-hosted target** (SSH, Docker, EC2, Azure VM,
 | Storage | At least one provider |
 | Configure deployment? | Yes for storage + deploy |
 | Deployment type | ssh (most common), docker, ec2, kubernetes, … |
+| Where should the container run? | Docker only: local / SSH (same `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH` as **ec2**) / raw `DOCKER_HOST` — see [Docker](#docker) |
 | App name | PM2 process name on server |
 | Health check URL | e.g. `https://api.example.com/health` |
 
@@ -700,6 +705,8 @@ The deploy workflow (`deployhub.yml`) installs the correct language runtime (Nod
 
 When an environment uses Kubernetes, the workflow installs `kubectl` and writes kubeconfig from secrets — but only when that run actually needs cluster access (push with a push-triggered k8s env, or workflow_dispatch / rollback targeting a k8s env, `all`, or blank). Plain pushes that only auto-deploy non-k8s environments (e.g. EC2 development) skip those steps.
 
+Map a git branch per environment during `init` / `env add` (`environments.<env>.branch`). The workflow then triggers only on those branches (for example `main` → production, `dev` → staging); other branches never run the pipeline. `workflow_dispatch` still lets you pick an environment by name. If you rename or delete a branch on GitHub, update `environments.<env>.branch` and run `deployhub sync-workflows` — doctor cannot see remote branch changes.
+
 To run a deploy manually: **Actions → DeployHub → Run workflow**.
 
 ### CI rollback (`deployhub-rollback.yml`)
@@ -712,6 +719,8 @@ To run a deploy manually: **Actions → DeployHub → Run workflow**.
 
 Already-initialized projects that only have `deployhub.yml` will not get the rollback workflow from a re-run of unrelated commands — run **`deployhub sync-workflows`** once to regenerate both workflow files from your current `deployhub.config.json`, then commit and push.
 
+Docker and Kubernetes CI rollback **pulls** the restored `buildId` image from the registry when it is not cached on the runner (the usual case). Rebuild-from-artifact is only the last fallback — see [Rollback behavior](#rollback-behavior).
+
 ---
 
 ## Choosing storage providers
@@ -751,7 +760,7 @@ DeployHub supports six deployment targets. Pick based on what infrastructure you
 | Method | Best for | You need already |
 |--------|----------|------------------|
 | **ssh** | Any Linux VPS or bare-metal server you control | Server with SSH, key pair, app runtime |
-| **docker** | Containerized apps (Dockerfile or docker-compose.yml) | Docker locally or on a remote host |
+| **docker** | Containerized apps (Dockerfile or docker-compose.yml) | Docker locally, a remote Linux host via SSH, or a raw `DOCKER_HOST` URI |
 | **ec2** | AWS users with an existing EC2 instance | Running EC2 instance, security group, key pair |
 | **azure-vm** | Azure users with an existing virtual machine | Running Azure VM, NSG allowing SSH |
 | **gcp-vm** | GCP users with an existing Compute Engine VM | Running VM, firewall rule for SSH, metadata SSH key |
@@ -791,6 +800,14 @@ Install Nginx if it is not already present:
 
 DeployHub detects whether the server uses Debian-style `sites-available` or RHEL-style `conf.d` at deploy time and writes a **uniquely named** config file for your project only — it does not overwrite unrelated Nginx configs.
 
+**SSH-mode Docker** (`remote.mode: "ssh"`) does not use the deploy-path or Nginx steps above. The remote Linux host needs **Docker installed** and the SSH user in the `docker` group:
+
+```bash
+sudo usermod -aG docker your-ssh-user
+```
+
+Then **reconnect** (group membership applies on the next login). `deployhub doctor` reports this if missing (it prints the exact `usermod` line). See [Docker](#docker) below.
+
 ### SSH
 
 **Verification:** Real-world verified DEPLOY and ROLLBACK.
@@ -834,29 +851,41 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 
 ### Docker
 
-**Verification:** Real-world verified DEPLOY and ROLLBACK (local and CI).
+**Verification:** Real-world verified DEPLOY and ROLLBACK (local, SSH remote, and CI).
 
 **Prerequisites:**
-- [ ] Docker installed (`docker --version` works)
+- [ ] Docker installed (`docker --version` works) — on this machine / CI for **local** and **raw**; on the remote Linux host for **ssh**
 - [ ] Registry account if pushing private images
 - [ ] `docker-compose.yml` in project if you use multi-service Compose (not auto-generated)
+- [ ] **SSH mode only:** [one-time server setup](#one-time-server-setup-before-your-first-deploy) — Docker on the host and the SSH user in the `docker` group (`sudo usermod -aG docker <user>`, then reconnect)
+
+`init` and `env add` ask **Where should the container run?**
+
+| Choice | Mode | Meaning |
+|--------|------|---------|
+| Locally (this machine or CI runner) | `local` | Same machine as the CLI or GitHub Actions runner |
+| Remote Linux server via SSH (recommended for production) | `ssh` | DeployHub validates the connection and runs `docker pull`/`run` over SSH. Set `SSH_HOST`, `SSH_USER`, and `SSH_KEY_PATH` (same names as the **ec2** method) |
+| Advanced: raw Docker host URI | `raw` | You set `DOCKER_HOST` (`tcp://` or a custom `ssh://` setup you already manage) |
+
+**Port (SSH mode):** a published port is required (asked as **Default port** during init / `env add`). Deploy fails clearly if it is missing, rather than starting an unreachable container. `deployhub doctor` and `deployhub verify` check that the running container has the mapping.
 
 **What DeployHub automates:**
 - Starter `Dockerfile` at project root when none exists (framework-aware; skipped if you already have one)
 - `.dockerignore` when missing (never overwrites an existing one)
-- `.env.example` for image name, registry, remote `DOCKER_HOST`
-- Docker daemon connectivity test during `init`
+- `.env.example` for image name, registry, remote `DOCKER_HOST`, and SSH vars when `remote.mode` is `ssh`
+- Docker daemon connectivity test during `init` (local / raw); SSH key, host reachability, remote daemon, and `docker` group permission when mode is `ssh`
 - Reuses the image built in the pipeline `docker` stage when present; otherwise builds from the artifact
 - Registry login + push when `DOCKER_REGISTRY_USERNAME` / `DOCKER_REGISTRY_TOKEN` are set
 - Auto-generates a unique image tag per build when `DOCKER_IMAGE_TAG` is unset (git SHA → CI run id → timestamp)
-- `docker compose up` or build/push/run during deploy
+- `docker compose up` or build/push/run during deploy (`-p` for SSH-mode `docker run`)
 
 **After `init`:**
 1. Set `DOCKER_IMAGE_NAME` in `.env` (e.g. `myuser/myapp` for Docker Hub)
 2. For private registries (or any push): set `DOCKER_REGISTRY_USERNAME` and `DOCKER_REGISTRY_TOKEN`
 3. Leave `DOCKER_IMAGE_TAG` unset for a unique tag each build — set it only if you intentionally want a fixed tag
-4. For a remote Linux host, choose **Remote Linux server via SSH** at init (`remote.mode: "ssh"`) and set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH` — DeployHub runs `docker pull`/`run` over node-ssh. Use `DOCKER_HOST` only for the advanced raw CLI transport (`tcp://` or a custom `ssh://` setup you already manage)
-5. Run `deployhub doctor`, then `git push origin main`
+4. For **ssh** mode: set `SSH_HOST`, `SSH_USER`, `SSH_KEY_PATH` (same names as the **ec2** method). Add GitHub Secrets `SSH_HOST`, `SSH_USER`, `SSH_KEY` for CI
+5. For **raw** mode only: set `DOCKER_HOST` to a URI you already manage (`tcp://` or custom `ssh://`)
+6. Run `deployhub doctor`, then `git push origin main`
 
 | Variable | Description | Example | Where to get it |
 |----------|-------------|---------|-----------------|
@@ -867,6 +896,7 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 | `DOCKER_REGISTRY_TOKEN` | Registry password/token | *(secret)* | Docker Hub / GHCR PAT |
 | `DOCKER_HOST` | Advanced raw daemon URI (optional) | `tcp://host:2376` | Only if you manage TLS/ssh:// yourself |
 | `SSH_HOST` / `SSH_USER` / `SSH_KEY_PATH` | Remote Linux via SSH (`remote.mode: ssh`) | `203.0.113.10` / `ubuntu` / `~/.ssh/key.pem` | Same names as EC2 |
+| `SSH_KEY` | Private key contents (CI only) | `-----BEGIN...` | Same key as `SSH_KEY_PATH` |
 
 ### AWS EC2
 
@@ -1013,7 +1043,7 @@ DeployHub detects whether the server uses Debian-style `sites-available` or RHEL
 - Cluster connectivity test during `init`
 - On deploy: registry login → reuse or build image → push (unique tag unless `DOCKER_IMAGE_TAG` is set) → ensure namespace exists (prompt locally / auto-create in CI) → `kubectl apply` → `kubectl set image` with the full resolved image ref → `kubectl rollout restart` when that ref is unchanged so pods pick up a new digest
 
-> **Limitation — interpreted backends (Node / Python / PHP / Rails) + rollback:** Kubernetes rollback forces a rebuild from the restored artifact when the exact `buildId` image is not already local. Those artifacts ship source/`composer.json` (etc.) but **not** installed deps (`vendor/`, `node_modules`, …), so DeployHub **refuses** with a clear error instead of a confusing Docker build failure. Successful rollback needs the restored image tag already present locally (or a prior `pipeline.docker` build that produced it). Same rule as standalone Docker deploy fallback.
+> **Limitation — interpreted backends (Node / Python / PHP / Rails) + rollback:** Kubernetes rollback uses the same image-resolution helper as Docker: local cache first, then **pull from the registry** (the normal case on a GitHub Actions runner). Rebuild-from-artifact is only the last fallback. Those artifacts ship source/`composer.json` (etc.) but **not** installed deps (`vendor/`, `node_modules`, …), so DeployHub **refuses** with a clear error instead of a confusing Docker build failure. Keep `pipeline.docker` so the original deploy pushed that tag. Same rule as standalone Docker.
 
 > **Limitation — multiple Kubernetes clusters:** A generated workflow writes **one** kubeconfig file per job. Multiple Kubernetes environments that target **different clusters** in the same workflow run are not yet fully supported (follow-up). Same-cluster multi-namespace / multi-env is fine.
 
@@ -1203,7 +1233,7 @@ Add these secrets in your repository (Settings → Secrets and variables → Act
 | `DOCKER_IMAGE_NAME`, `DOCKER_REGISTRY_USERNAME`, `DOCKER_REGISTRY_TOKEN`, `DOCKER_REGISTRY_URL`, `DOCKER_HOST` | Docker deployment (`DOCKER_IMAGE_TAG` optional) |
 | `KUBECONFIG`, `KUBE_CONTEXT`, `KUBE_NAMESPACE`, `DOCKER_IMAGE_NAME`, `DOCKER_REGISTRY_USERNAME`, `DOCKER_REGISTRY_TOKEN`, `DOCKER_REGISTRY_URL`, `DOCKER_IMAGE_TAG`, `KUBE_IMAGE_PULL_SECRET` | Kubernetes — **`KUBECONFIG` in GitHub Secrets must be the kubeconfig file contents (or base64), not a filesystem path**. `DOCKER_IMAGE_TAG`, `KUBE_NAMESPACE`, `DOCKER_REGISTRY_URL`, and `KUBE_IMAGE_PULL_SECRET` are optional |
 
-**Kubernetes rollback vs deploy — registry credentials:** Kubernetes **rollback** specifically **requires** `DOCKER_REGISTRY_USERNAME` and `DOCKER_REGISTRY_TOKEN`. Rollback rebuilds and must push a fresh image tagged with the restored `buildId`; without registry credentials it fails loudly and early (a rollback that cannot push can never succeed against a real cluster). This is stricter than a normal Kubernetes **deploy**, which may still allow local-only / no-push flows in some setups. If deploy worked without those secrets but rollback fails asking for them, that asymmetry is intentional.
+**Kubernetes rollback vs deploy — registry credentials:** Kubernetes **rollback** specifically **requires** `DOCKER_REGISTRY_USERNAME` and `DOCKER_REGISTRY_TOKEN`. Rollback pulls the restored `buildId` tag when it is not local, then must still push that image for the cluster; without registry credentials it fails loudly and early (a rollback that cannot push can never succeed against a real cluster). Rebuild-from-artifact is only the last fallback (interpreted backends refuse). This is stricter than a normal Kubernetes **deploy**, which may still allow local-only / no-push flows in some setups. If deploy worked without those secrets but rollback fails asking for them, that asymmetry is intentional.
 
 See [Deployment method guides](#deployment-method-guides) for full per-method variable tables with examples.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akash-chowdhury-24/deployhub",
-  "version": "2.0.34",
+  "version": "2.0.35",
   "description": "Zero-configuration deployment and artifact manager",
   "type": "module",
   "main": "./src/cli/index.js",

package/src/commands/doctor.js

@@ -13,7 +13,7 @@ import {
 import { loadEnvArtifactHistory } from '../storage/index.js';
 import { testProvider } from '../storage/index.js';
 import { getDeploymentProvider } from '../deployment/index.js';
-import { PROVIDER_ENV_MAP, STORAGE_PROVIDER_IDS, getRollbackWorkflowDoctorCheck, getWorkflowDriftDoctorChecks } from '../utils/github-actions.js';
+import { PROVIDER_ENV_MAP, STORAGE_PROVIDER_IDS, getRollbackWorkflowDoctorCheck, getWorkflowDriftDoctorChecks, getBranchMappingDoctorCheck } from '../utils/github-actions.js';
 import { printDoctorFooter } from '../utils/author.js';
 import { createLocalProvider } from '../storage/providers/local.js';
 import {
@@ -1404,6 +1404,11 @@ export function registerDoctorCommand(program) {
       }
 
       if (config) {
+        const branchCheck = getBranchMappingDoctorCheck(config);
+        if (branchCheck) {
+          informationalCheckNames.add(branchCheck.name);
+          results.push(await runCheck(branchCheck.name, async () => branchCheck));
+        }
         const driftChecks = await getWorkflowDriftDoctorChecks(cwd, config);
         for (const check of driftChecks) {
           results.push(await runCheck(check.name, async () => check));

package/src/commands/init.js

@@ -28,7 +28,6 @@ import {
   promptServerDeployment,
   buildServerEnvEntry,
   getDockerEnvSecrets,
-  applyInitTriggerDefaults,
   formatMultiEnvTriggerReminder,
   SSH_BASED,
 } from '../deployment/init-prompts.js';
@@ -37,6 +36,11 @@ import {
   formatSecretChecklistLine,
 } from '../deployment/deployment-env.js';
 import { confirmValueIfContainsSpaces, normalizeInitHealthCheckUrl } from '../deployment/init-helpers.js';
+import {
+  getWorkflowPushBranches,
+  formatBranchMappingSummary,
+  getEnvTrigger,
+} from '../core/environments.js';
 
 const FRONTEND_CHOICES = [
   { name: 'React', value: 'react' },
@@ -383,6 +387,8 @@ export function registerInitCommand(program) {
               ...(opts.envName ? { envName: opts.envName } : {}),
               existingEnvNames: Object.keys(environments),
               portDefault: singleConfig?.port ?? backendConfig?.port,
+              defaultTrigger: deploy.length === 0 ? 'push' : 'manual',
+              defaultBranch: 'main',
             }
           );
           primaryDeployType = deployAnswers.deployType;
@@ -463,7 +469,8 @@ export function registerInitCommand(program) {
         defaultEnvironment = picked.defaultEnvironment;
       }
 
-      applyInitTriggerDefaults(environments, deploy, defaultEnvironment);
+      // Trigger + branch come from per-env prompts (default: first env push/main,
+      // additional envs manual). Do not clobber those answers here.
 
       const version = await getProjectVersion(cwd);
       let hasDocker =
@@ -585,7 +592,14 @@ export function registerInitCommand(program) {
       console.log('  • .env.example');
       console.log('');
 
-      if (deploy.length >= 2 && defaultEnvironment) {
+      if (deploy.length > 0) {
+        const mapped = getWorkflowPushBranches(config);
+        console.log(chalk.cyan(formatBranchMappingSummary(mapped)));
+        console.log('');
+      }
+
+      const hasManualEnv = deploy.some((name) => getEnvTrigger(environments[name]) === 'manual');
+      if (deploy.length >= 2 && defaultEnvironment && hasManualEnv) {
         console.log(
           chalk.yellow(
             formatMultiEnvTriggerReminder(String(defaultEnvironment), deploy)

package/src/core/config.js

@@ -15,6 +15,7 @@ import {
   buildEnvironmentEntry,
   resolveEnvTargets,
   mergeMethodSettingsIntoEnv,
+  normalizeGitBranchName,
 } from './environments.js';
 
 const SideConfigSchema = z.object({
@@ -83,6 +84,8 @@ const EnvironmentSchema = z.object({
   enabled: z.boolean().default(true),
   method: z.string(),
   trigger: z.enum(['push', 'manual']).default('manual'),
+  /** Git branch that auto-deploys this environment on push. Omitted = grandfathered main-only. */
+  branch: z.string().min(1).optional(),
   config: MethodConfigSchema.default({}),
 });
 
@@ -206,6 +209,7 @@ function extractMethodConfig(entry) {
       key === 'enabled' ||
       key === 'method' ||
       key === 'trigger' ||
+      key === 'branch' ||
       key === 'config' ||
       key === 'type'
     ) {
@@ -218,6 +222,16 @@ function extractMethodConfig(entry) {
   return config;
 }
 
+/**
+ * Preserve `environments.<env>.branch` across migration without inventing one.
+ * @param {Record<string, unknown>} entry
+ * @returns {{ branch?: string }}
+ */
+function copyEnvBranch(entry) {
+  const parsed = normalizeGitBranchName(entry.branch);
+  return parsed.ok ? { branch: parsed.name } : {};
+}
+
 /**
  * @param {Record<string, unknown>} raw
  * @returns {boolean}
@@ -280,6 +294,7 @@ export function migrateConfigToEnvironments(raw) {
           enabled: entry.enabled !== false,
           method: String(entry.method),
           trigger: entry.trigger === 'push' ? 'push' : 'manual',
+          ...copyEnvBranch(entry),
           config: extractMethodConfig(entry),
         };
         continue;
@@ -292,6 +307,7 @@ export function migrateConfigToEnvironments(raw) {
         enabled,
         method,
         trigger: entry.trigger === 'push' ? 'push' : 'manual',
+        ...copyEnvBranch(entry),
         config: extractMethodConfig(entry),
       };
     }

package/src/core/environments.js

@@ -139,6 +139,120 @@ export function getEnvTrigger(envEntry) {
   return e.trigger === 'push' ? 'push' : 'manual';
 }
 
+/**
+ * Normalize a git branch name from config / prompts.
+ * Strips a leading `refs/heads/` if the user pasted a full ref.
+ *
+ * @param {unknown} input
+ * @returns {{ ok: true, name: string } | { ok: false, error: string }}
+ */
+export function normalizeGitBranchName(input) {
+  const trimmed = typeof input === 'string' ? input.trim() : '';
+  if (!trimmed) {
+    return { ok: false, error: 'Branch name cannot be empty.' };
+  }
+  const stripped = trimmed.replace(/^refs\/heads\//, '');
+  if (!stripped) {
+    return { ok: false, error: 'Branch name cannot be empty.' };
+  }
+  if (/\s/.test(stripped)) {
+    return { ok: false, error: 'Branch name cannot contain whitespace.' };
+  }
+  return { ok: true, name: stripped };
+}
+
+/**
+ * @param {unknown} envEntry
+ * @returns {string|null}
+ */
+export function getEnvBranch(envEntry) {
+  if (!envEntry || typeof envEntry !== 'object') return null;
+  const parsed = normalizeGitBranchName(
+    /** @type {Record<string, unknown>} */ (envEntry).branch
+  );
+  return parsed.ok ? parsed.name : null;
+}
+
+/**
+ * True when at least one environment has opted into `branch` mapping.
+ * Absence of every `branch` field = grandfathered main-only push trigger.
+ *
+ * @param {Record<string, unknown>} [config]
+ * @returns {boolean}
+ */
+export function configHasBranchMapping(config) {
+  const envs = /** @type {Record<string, unknown>} */ (config?.environments || {});
+  return Object.values(envs).some((entry) => getEnvBranch(entry) != null);
+}
+
+/**
+ * Current git branch for a GitHub Actions push run.
+ * Tags and missing refs return null (no environment matches).
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function resolvePushBranchName(env = process.env) {
+  const ref = env.GITHUB_REF;
+  if (typeof ref === 'string' && ref.startsWith('refs/heads/')) {
+    return ref.slice('refs/heads/'.length) || null;
+  }
+  // Some harnesses set GITHUB_REF_NAME without GITHUB_REF.
+  if (typeof env.GITHUB_REF_NAME === 'string' && env.GITHUB_REF_NAME.trim()) {
+    if (typeof ref === 'string' && ref.startsWith('refs/tags/')) return null;
+    return env.GITHUB_REF_NAME.trim();
+  }
+  return null;
+}
+
+/**
+ * Unique `on.push.branches` list for the generated workflow.
+ *
+ * - No environment has `branch` → `['main']` (today's hardcoded trigger).
+ * - Otherwise: unique branches of enabled `trigger: push` environments
+ *   (an enabled push env without `branch` defaults to `main`).
+ *   `main` is listed first when present. Empty if nothing should auto-trigger.
+ *
+ * @param {Record<string, unknown>} [config]
+ * @returns {string[]}
+ */
+export function getWorkflowPushBranches(config) {
+  const envs = /** @type {Record<string, unknown>} */ (config?.environments || {});
+  if (!configHasBranchMapping(config || {})) {
+    return ['main'];
+  }
+
+  /** @type {string[]} */
+  const collected = [];
+  const seen = new Set();
+  for (const entry of Object.values(envs)) {
+    if (!isEnvEnabled(entry) || getEnvTrigger(entry) !== 'push') continue;
+    const branch = getEnvBranch(entry) || 'main';
+    if (seen.has(branch)) continue;
+    seen.add(branch);
+    collected.push(branch);
+  }
+
+  if (collected.includes('main')) {
+    return ['main', ...collected.filter((b) => b !== 'main')];
+  }
+  return collected;
+}
+
+/**
+ * Init / doctor copy. The second line makes the exclusion explicit.
+ *
+ * @param {string[]} branches
+ * @returns {string}
+ */
+export function formatBranchMappingSummary(branches) {
+  const list = branches.length > 0 ? branches.join(', ') : '(none)';
+  return [
+    `Branches mapped to an environment: ${list}`,
+    'Pushes to any other branch will not trigger DeployHub.',
+  ].join('\n');
+}
+
 /**
  * @param {Record<string, unknown>} config
  * @returns {string|null}
@@ -196,7 +310,7 @@ export function getEnabledEnvironmentNames(config) {
  *
  * @param {string} method
  * @param {Record<string, unknown>} [settings]
- * @param {{ enabled?: boolean, trigger?: 'push'|'manual' }} [meta]
+ * @param {{ enabled?: boolean, trigger?: 'push'|'manual', branch?: string }} [meta]
  */
 export function buildEnvironmentEntry(method, settings = {}, meta = {}) {
   const cleaned = { ...settings };
@@ -204,11 +318,16 @@ export function buildEnvironmentEntry(method, settings = {}, meta = {}) {
   delete cleaned.method;
   delete cleaned.enabled;
   delete cleaned.trigger;
+  delete cleaned.branch;
   delete cleaned.config;
+  const trigger = meta.trigger === 'push' ? 'push' : 'manual';
+  const branchParsed =
+    trigger === 'push' && meta.branch != null ? normalizeGitBranchName(meta.branch) : null;
   return {
     enabled: meta.enabled !== false,
     method,
-    trigger: meta.trigger === 'push' ? 'push' : 'manual',
+    trigger,
+    ...(branchParsed?.ok ? { branch: branchParsed.name } : {}),
     config: cleaned,
   };
 }
@@ -311,6 +430,12 @@ export default {
   getEnvSettings,
   isEnvEnabled,
   getEnvTrigger,
+  normalizeGitBranchName,
+  getEnvBranch,
+  configHasBranchMapping,
+  resolvePushBranchName,
+  getWorkflowPushBranches,
+  formatBranchMappingSummary,
   resolveDefaultEnvironmentName,
   getEnabledEnvironmentNames,
   buildEnvironmentEntry,

package/src/core/stages.js

@@ -21,12 +21,17 @@ import {
   resolveDefaultEnvironmentName,
   isEnvEnabled,
   getEnvTrigger,
+  configHasBranchMapping,
+  getEnvBranch,
+  resolvePushBranchName,
 } from './environments.js';
 
 /**
  * Environments to deploy during `deployhub build` (pipeline.deploy).
  * - Local: default environment only (promote elsewhere via `deploy --env`).
- * - GitHub Actions push: every enabled env with trigger "push".
+ * - GitHub Actions push: every enabled env with trigger "push" whose `branch`
+ *   matches the push ref. Configs with no `branch` on any environment keep
+ *   today's behavior (all push-triggered envs, regardless of ref).
  * - workflow_dispatch: none here (explicit deploy step handles --env).
  *
  * Separate from workflow secret injection: CI may inject secrets for all
@@ -41,8 +46,16 @@ export function pipelineDeployTargets(config, env = process.env) {
     return [];
   }
   if (env.GITHUB_ACTIONS === 'true' || env.GITHUB_ACTIONS === '1') {
-    return Object.entries(config.environments || {})
-      .filter(([, entry]) => isEnvEnabled(entry) && getEnvTrigger(entry) === 'push')
+    const pushEnvs = Object.entries(config.environments || {}).filter(
+      ([, entry]) => isEnvEnabled(entry) && getEnvTrigger(entry) === 'push'
+    );
+    if (!configHasBranchMapping(config)) {
+      return pushEnvs.map(([name]) => name);
+    }
+    const branch = resolvePushBranchName(env);
+    if (!branch) return [];
+    return pushEnvs
+      .filter(([, entry]) => (getEnvBranch(entry) || 'main') === branch)
       .map(([name]) => name);
   }
   const def = resolveDefaultEnvironmentName(config);

package/src/deployment/init-prompts.js

@@ -1,6 +1,6 @@
 import inquirer from 'inquirer';
 import chalk from 'chalk';
-import { createEnvNamePromptValidate } from '../core/environments.js';
+import { createEnvNamePromptValidate, normalizeGitBranchName } from '../core/environments.js';
 import {
   suggestSshUser,
   listKubeContexts,
@@ -58,15 +58,18 @@ export function backendProcessNamePromptMessage(framework, projectName, projectT
  * @param {'frontend'|'backend'|'both'} projectType
  * @param {Record<string, unknown>|null} backendConfig
  * @param {{
-   *   envName?: string,
-   *   existingEnvNames?: string[],
-   *   deployType?: string,
-   *   nonInteractive?: boolean,
-   *   portDefault?: number,
-   * }} [options]
-   *   — when envName is set, skip the name prompt; existingEnvNames blocks in-session / config duplicates
-   *   — deployType skips the method list; nonInteractive uses defaults (requires deployType)
-   *   — portDefault seeds the docker "Default port" prompt (init / env add)
+ *   envName?: string,
+ *   existingEnvNames?: string[],
+ *   deployType?: string,
+ *   nonInteractive?: boolean,
+ *   portDefault?: number,
+ *   defaultTrigger?: 'push'|'manual',
+ *   defaultBranch?: string,
+ * }} [options]
+ *   — when envName is set, skip the name prompt; existingEnvNames blocks in-session / config duplicates
+ *   — deployType skips the method list; nonInteractive uses defaults (requires deployType)
+ *   — portDefault seeds the docker "Default port" prompt (init / env add)
+ *   — defaultTrigger / defaultBranch seed the trigger-type and branch prompts
  */
 export async function promptServerDeployment(
   projectName,
@@ -128,20 +131,79 @@ export async function promptServerDeployment(
 
   const deployType = base.deployType;
 
+  /** @type {Record<string, unknown>} */
+  let methodAnswers;
   if (deployType === 'kubernetes') {
-    return promptKubernetesDeployment(base, projectName, projectType, {
+    methodAnswers = await promptKubernetesDeployment(base, projectName, projectType, {
       existingEnvNames,
     });
-  }
-
-  if (deployType === 'docker') {
-    return promptDockerDeployment(base, projectName, projectType, {
+  } else if (deployType === 'docker') {
+    methodAnswers = await promptDockerDeployment(base, projectName, projectType, {
       backendConfig,
       portDefault: options.portDefault,
     });
+  } else {
+    methodAnswers = await promptSshBasedDeployment(
+      base,
+      projectName,
+      projectType,
+      backendConfig,
+      deployType
+    );
+  }
+
+  const triggerMeta = await promptTriggerAndBranch(options);
+  return { ...methodAnswers, ...triggerMeta };
+}
+
+/**
+ * Trigger type + (when push) which branch fires this environment.
+ * `--yes` skips this entirely so existing non-interactive env add stays branch-less.
+ *
+ * @param {{ defaultTrigger?: 'push'|'manual', defaultBranch?: string }} [options]
+ */
+export async function promptTriggerAndBranch(options = {}) {
+  const defaultTrigger = options.defaultTrigger === 'push' ? 'push' : 'manual';
+  const defaultBranch =
+    typeof options.defaultBranch === 'string' && options.defaultBranch.trim()
+      ? options.defaultBranch.trim()
+      : 'main';
+
+  const { trigger } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'trigger',
+      message: 'When should this environment deploy?',
+      choices: [
+        { name: 'On git push to a branch', value: 'push' },
+        { name: 'Manually (GitHub Actions → Run workflow)', value: 'manual' },
+      ],
+      default: defaultTrigger,
+    },
+  ]);
+
+  if (trigger !== 'push') {
+    return { trigger: 'manual' };
   }
 
-  return promptSshBasedDeployment(base, projectName, projectType, backendConfig, deployType);
+  const { branch } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'branch',
+      message: 'Which branch triggers this environment?',
+      default: defaultBranch,
+      validate: (input) => {
+        const result = normalizeGitBranchName(input);
+        return result.ok ? true : result.error;
+      },
+    },
+  ]);
+
+  const parsed = normalizeGitBranchName(branch);
+  return {
+    trigger: 'push',
+    branch: parsed.ok ? parsed.name : defaultBranch,
+  };
 }
 
 /**
@@ -658,12 +720,15 @@ export function buildServerEnvEntry(
     settings.kubeNamespace = deployAnswers.kubeNamespace || projectName;
     settings.dockerImageName = deployAnswers.dockerImageName || projectName;
     settings.dockerRegistryUrl = deployAnswers.dockerRegistryUrl || '';
-    return {
-      enabled: true,
-      method: 'kubernetes',
-      trigger: 'manual',
-      config: settings,
-    };
+    return withTriggerAndBranch(
+      {
+        enabled: true,
+        method: 'kubernetes',
+        trigger: 'manual',
+        config: settings,
+      },
+      deployAnswers
+    );
   }
 
   if (deployAnswers.deployType === 'docker') {
@@ -689,12 +754,15 @@ export function buildServerEnvEntry(
     if (Number.isInteger(n) && n >= 1 && n <= 65535) {
       settings.port = n;
     }
-    return {
-      enabled: true,
-      method: 'docker',
-      trigger: 'manual',
-      config: settings,
-    };
+    return withTriggerAndBranch(
+      {
+        enabled: true,
+        method: 'docker',
+        trigger: 'manual',
+        config: settings,
+      },
+      deployAnswers
+    );
   }
 
   settings.host = deployAnswers.host || '';
@@ -731,12 +799,34 @@ export function buildServerEnvEntry(
     settings.path = settings.deployPath;
   }
 
-  return {
-    enabled: true,
-    method: deployAnswers.deployType,
-    trigger: 'manual',
-    config: settings,
-  };
+  return withTriggerAndBranch(
+    {
+      enabled: true,
+      method: deployAnswers.deployType,
+      trigger: 'manual',
+      config: settings,
+    },
+    deployAnswers
+  );
+}
+
+/**
+ * Overlay prompt answers onto the env entry. `--yes` / missing answers keep
+ * trigger `manual` and omit `branch` (backward compatible).
+ *
+ * @param {{ enabled: boolean, method: string, trigger: string, config: Record<string, unknown>, branch?: string }} entry
+ * @param {Record<string, unknown>} deployAnswers
+ */
+function withTriggerAndBranch(entry, deployAnswers) {
+  const trigger = deployAnswers.trigger === 'push' ? 'push' : 'manual';
+  entry.trigger = trigger;
+  if (trigger === 'push' && deployAnswers.branch != null) {
+    const parsed = normalizeGitBranchName(deployAnswers.branch);
+    if (parsed.ok) entry.branch = parsed.name;
+  } else {
+    delete entry.branch;
+  }
+  return entry;
 }
 
 /**

package/src/utils/github-actions.js

@@ -22,6 +22,8 @@ import {
   getEnabledEnvironmentNames,
   isEnvEnabled,
   getEnvSettings,
+  getWorkflowPushBranches,
+  formatBranchMappingSummary,
 } from '../core/environments.js';
 import { resolvePhpVersion } from './php-version.js';
 
@@ -573,6 +575,33 @@ function formatEnvironmentChoiceOptions(environments) {
   return options.map((n) => `          - ${n}`).join('\n');
 }
 
+/**
+ * YAML token for a git branch in `on.push.branches`.
+ * Unquoted when the name is a simple identifier; JSON-quoted otherwise.
+ *
+ * @param {string} branch
+ * @returns {string}
+ */
+function formatYamlBranchToken(branch) {
+  if (/^[A-Za-z0-9._-]+$/.test(branch)) return branch;
+  return JSON.stringify(branch);
+}
+
+/**
+ * `on.push` block listing exactly the mapped trigger branches — or omitted
+ * when mapping mode has no enabled push environments (dispatch-only).
+ *
+ * @param {string[]} branches
+ * @returns {string}
+ */
+export function formatPushTriggerYaml(branches) {
+  if (!branches || branches.length === 0) return '';
+  const list = branches.map(formatYamlBranchToken).join(', ');
+  return `  push:
+    branches: [${list}]
+`;
+}
+
 /**
  * @param {Set<string>} envVars
  * @param {string} [indent]
@@ -678,6 +707,9 @@ export function generateWorkflowYaml(
 
   const envChoiceOptions = formatEnvironmentChoiceOptions(environments);
   const hasEnvs = envNames.length > 0;
+  const cfgForBranches = { ...(config || {}), environments };
+  const pushBranches = getWorkflowPushBranches(cfgForBranches);
+  const pushTriggerYaml = formatPushTriggerYaml(pushBranches);
   const dispatchInputs = hasEnvs
     ? `  workflow_dispatch:
     inputs:
@@ -708,9 +740,7 @@ ${envBlock}
 
   const workflow = `${getWorkflowHeaderComment()}name: DeployHub
 on:
-  push:
-    branches: [main]
-${dispatchInputs}jobs:
+${pushTriggerYaml}${dispatchInputs}jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
@@ -1036,13 +1066,17 @@ export function expectedWorkflowSecretKeysFromConfig(config, kind = 'rollback')
  * @param {string} yamlText
  * @param {import('../core/config.js').DeployHubConfig} config
  * @param {string} [filename]
- * @returns {{ drifted: boolean, missingEnvs: string[], missingSecrets: string[], summary: string }}
+ * @returns {{ drifted: boolean, missingEnvs: string[], missingSecrets: string[], missingBranches: string[], extraBranches: string[], summary: string }}
  */
 export function detectWorkflowConfigDrift(yamlText, config, filename = DEPLOY_WORKFLOW_FILENAME) {
   /** @type {string[]} */
   const missingEnvs = [];
   /** @type {string[]} */
   const missingSecrets = [];
+  /** @type {string[]} */
+  const missingBranches = [];
+  /** @type {string[]} */
+  const extraBranches = [];
 
   let parsed;
   try {
@@ -1052,12 +1086,21 @@ export function detectWorkflowConfigDrift(yamlText, config, filename = DEPLOY_WO
       drifted: false,
       missingEnvs,
       missingSecrets,
+      missingBranches,
+      extraBranches,
       summary: '',
     };
   }
 
   if (!parsed || typeof parsed !== 'object') {
-    return { drifted: false, missingEnvs, missingSecrets, summary: '' };
+    return {
+      drifted: false,
+      missingEnvs,
+      missingSecrets,
+      missingBranches,
+      extraBranches,
+      summary: '',
+    };
   }
 
   const envNames = getEnabledEnvironmentNames(config);
@@ -1081,7 +1124,30 @@ export function detectWorkflowConfigDrift(yamlText, config, filename = DEPLOY_WO
     if (!fileSecrets.has(key)) missingSecrets.push(key);
   }
 
-  const drifted = missingEnvs.length > 0 || missingSecrets.length > 0;
+  if (kind === 'deploy') {
+    const expectedBranches = getWorkflowPushBranches(config);
+    const actualRaw = root?.on?.push?.branches;
+    /** @type {string[]} */
+    const actualBranches = Array.isArray(actualRaw)
+      ? actualRaw.map(String)
+      : typeof actualRaw === 'string'
+        ? [actualRaw]
+        : [];
+    const actualSet = new Set(actualBranches);
+    const expectedSet = new Set(expectedBranches);
+    for (const b of expectedBranches) {
+      if (!actualSet.has(b)) missingBranches.push(b);
+    }
+    for (const b of actualBranches) {
+      if (!expectedSet.has(b)) extraBranches.push(b);
+    }
+  }
+
+  const drifted =
+    missingEnvs.length > 0 ||
+    missingSecrets.length > 0 ||
+    missingBranches.length > 0 ||
+    extraBranches.length > 0;
   /** @type {string[]} */
   const parts = [];
   if (missingEnvs.length > 0) {
@@ -1095,11 +1161,23 @@ export function detectWorkflowConfigDrift(yamlText, config, filename = DEPLOY_WO
       `missing secret(s): ${shown.join(', ')}${missingSecrets.length > 4 ? ', …' : ''}`
     );
   }
+  if (missingBranches.length > 0 || extraBranches.length > 0) {
+    const bits = [];
+    if (missingBranches.length > 0) {
+      bits.push(`missing ${missingBranches.map((b) => `"${b}"`).join(', ')}`);
+    }
+    if (extraBranches.length > 0) {
+      bits.push(`extra ${extraBranches.map((b) => `"${b}"`).join(', ')}`);
+    }
+    parts.push(`${bits.join('; ')} in on.push.branches`);
+  }
 
   return {
     drifted,
     missingEnvs,
     missingSecrets,
+    missingBranches,
+    extraBranches,
     summary: parts.join('; '),
   };
 }
@@ -1148,6 +1226,24 @@ export async function getWorkflowDriftDoctorChecks(cwd, config) {
   return checks;
 }
 
+/**
+ * Doctor helper: informational line listing which branches invoke the workflow.
+ * Always pass: true — same pattern as workflow-drift (never blocks doctor exit).
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @returns {{ name: string, pass: boolean, message: string } | null}
+ */
+export function getBranchMappingDoctorCheck(config) {
+  const envCount = Object.keys(config.environments || {}).length;
+  if (envCount === 0) return null;
+  const branches = getWorkflowPushBranches(config);
+  return {
+    name: 'Branch mapping',
+    pass: true,
+    message: formatBranchMappingSummary(branches).replace(/\n/g, ' '),
+  };
+}
+
 /**
  * Extract a comparable base semver from a package.json dependency value
  * (`^2.0.19`, `~2.0.19`, `2.0.19`). Returns null for `latest`, git URLs,