@akash-chowdhury-24/deployhub 2.0.40 → 2.0.43

package/README.md

@@ -120,6 +120,9 @@ This interactive wizard will:
 - Configure build commands and output directory
 - Set up storage providers (AWS, Google Drive, Azure, GCP, Dropbox, Local)
 - Optionally configure deployment targets (SSH, Docker, EC2, Azure VM, GCP VM, Kubernetes)
+- For Docker: **Where should the container run?** (`local` / `ssh` / `raw`)
+- For push-triggered environments: **Which branch triggers this environment?**
+- Optional deploy hooks and optional DeployHub-managed `.env`
 - Generate `deployhub.config.json`
 - Generate `.github/workflows/deployhub.yml` and `.github/workflows/deployhub-rollback.yml`
 - Generate `.env.example`
@@ -353,9 +356,25 @@ deployhub sync-workflows                        # regenerate deployhub.yml + dep
 | First / grandfathered env in multi-env `init` | `"push"` |
 | Additional environments | `"manual"` — deploy only via Actions → Run workflow or `deployhub deploy --env` |
 
-Multi-env `init` prints a reminder naming which environments are push vs manual and how to edit `deployhub.config.json` (`environments.<name>.trigger`) if you want a different mix. After changing triggers or envs, run `deployhub sync-workflows` and commit the regenerated YAML.
+Multi-env `init` prints a reminder naming which environments are push vs manual and how to edit `deployhub.config.json` (`environments.<name>.trigger`) if you want a different mix. After changing triggers, branches, or envs, run `deployhub sync-workflows` and commit the regenerated YAML.
 
-On a GitHub Actions **push**, `deployhub build` only auto-deploys environments with `trigger: "push"`. Environments with `trigger: "manual"` are never deployed on push — even though their secrets are present in the job for dispatch/rollback.
+On a GitHub Actions **push**, `deployhub build` only auto-deploys environments with `trigger: "push"` whose `branch` matches the push ref. Environments with `trigger: "manual"` are never deployed on push — even though their secrets are present in the job for dispatch/rollback.
+
+### Branch-to-environment mapping
+
+Each environment can name the git branch that triggers it (`environments.<env>.branch`). `init` / `env add` ask when the trigger is push:
+
+```
+? Which branch triggers this environment?
+```
+
+The generated workflow's `on.push.branches` lists **only** those mapped branches. A push to an unmapped branch (for example a personal working branch that feeds `dev` via PR) **never invokes the workflow at all** — not a skipped deploy, no pipeline run. `workflow_dispatch` (Actions → Run workflow) is unaffected: you still pick an environment by name.
+
+Because storage history is per-environment and only written when a real pipeline run for that environment completes, an environment's rollback history can only ever contain builds that came from its own mapped branch.
+
+Configs with **no** `branch` field anywhere keep today's behavior (push trigger is `main` only). If you rename or delete a branch on GitHub, edit `environments.<env>.branch` and run `deployhub sync-workflows` — doctor cannot see remote branch changes.
+
+How branch mapping was proven (generated YAML, history isolation): `CONTEXT.md`.
 
 ### Secret naming
 
@@ -699,13 +718,13 @@ git commit -m "Add DeployHub CI"
 
 1. Open **Settings → Secrets and variables → Actions** in your GitHub repo.
 2. Add every secret listed at the end of `deployhub init` (storage + deployment).
-3. Push to `main` or `master` — the deploy workflow triggers on push.
+3. Push to a mapped branch (default `main` / `master`) — the deploy workflow triggers on push.
 
 The deploy workflow (`deployhub.yml`) installs the correct language runtime (Node, Python, PHP, Java, Go, .NET, Ruby) based on your `deployhub.config.json`, installs DeployHub, runs `deployhub build`, and uses your secrets. For PHP projects, CI uses `shivammathur/setup-php` (default **8.4**; override with `phpVersion` / `backend.phpVersion`).
 
 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.
+Push triggers follow [branch-to-environment mapping](#branch-to-environment-mapping) (`environments.<env>.branch`). Example: `main` → production, `dev` → staging; a push to any other branch never starts this workflow. `workflow_dispatch` still lets you pick an environment by name.
 
 To run a deploy manually: **Actions → DeployHub → Run workflow**.
 
@@ -755,17 +774,26 @@ You can enable **multiple providers** — DeployHub uploads to all of them in pa
 
 ## Custom deploy hooks
 
-SSH-based deploys (`ssh`, `ec2`, `azure-vm`, `gcp-vm`, and `docker` with `remote.mode: "ssh"`) can run your own commands on the remote host as part of deploy and rollback. Use them for migrations, cache clearing, or a notification — anything you currently SSH in to do by hand.
+SSH-based deploys (`ssh`, `ec2`, `azure-vm`, `gcp-vm`, and `docker` with `remote.mode: "ssh"`) can run your own commands on the remote host as part of deploy and rollback. Use them for host bootstrap, migrations, codegen, cache clearing, or a notification — anything you currently SSH in to do by hand.
+
+Config shape: `environments.<env>.config.hooks` with four stage arrays. Each entry is `{ command, continueOnError, reconnect, timeoutMs }` (`command` is required; the rest are optional).
 
 | Hook | When it runs | Typical use | Failure default |
 |------|----------------|-------------|-----------------|
-| `preDeploy` | After the artifact/image is ready and the host is reachable, **before** the running app/container is replaced or started | DB migrations that must finish before new code runs | Abort the deploy (`continueOnError: false`) |
-| `postDeploy` | After the app is up (SSH start / docker-ssh port publish) | Cache warm, Slack ping, non-critical cleanup | Continue (`continueOnError: true` when added via `init` / `env add`) |
+| `preDeploy` | After the artifact/image is ready and the host is reachable, **before** extract / `docker stop` | Host bootstrap (`dnf install -y docker`, `usermod`). **Not** for codegen that needs the new files | Abort the deploy (`continueOnError: false`) |
+| `postInstall` | After the framework's dependency install (`pip install` / `npm install` / `composer install` / `bundle install`) and **before** the app process starts. Plain `ssh` / `ec2` / `azure-vm` / `gcp-vm` only | `prisma generate`, Django `collectstatic`, any codegen that needs installed deps **and** the extracted artifact | Abort (`continueOnError: false`) |
+| `postDeploy` | After the app is up (SSH start / docker-ssh port publish). **Skipped on rollback** | Cache warm, Slack ping, non-critical cleanup | Continue (`continueOnError: true` when added via `init` / `env add`) |
 | `rollback` | During `deployhub rollback`, in the same slot as `preDeploy` — before the restored version takes over | Your own down-migration. DeployHub does not reverse migrations for you | Abort the rollback (`continueOnError: false`) |
 
-Commands run over the **existing** SSH session (not a second connection), unless a successful hook sets `"reconnect": true`. Kubernetes and Docker `local` / `raw` modes do not support hooks (no persistent remote shell session); configuring them there fails loudly at deploy/rollback.
+On rollback, `postInstall` **reuses the same stage name** (unlike `preDeploy`, which is replaced by the `rollback` stage). Codegen must run against the **restored** files, not leftover generated output from the version you are rolling back from.
+
+`postInstall` is **not** asked or run for Docker `remote.mode: "ssh"`. Docker installs dependencies at **image build** time, not at deploy time, so there is no remote `pip install` / `npm install` slot between extract and `docker run`. Put `prisma generate` (and similar) in the Dockerfile. Kubernetes and Docker `local` / `raw` do not support hooks (no persistent remote shell session); configuring them there fails loudly at deploy/rollback.
+
+> **Hooks do not `cd` for you.** Commands run in the SSH user's home directory unless you `cd` explicitly (`cd /var/www/app && …`). Loading a `.env` in the deploy path requires `set -a && . ./.env && set +a` **in the same command** — `cd` alone does not export those variables.
 
-On docker-ssh, `preDeploy` / `rollback` run **before** remote registry login and `docker stop`/`run`, so a hook can install Docker on a bare host. `postDeploy` runs **after** the port-publish inspect check (`docker inspect` confirms `0.0.0.0:<port>->`). A hook that curls the app's published port therefore sees a container DeployHub already treated as published. If that inspect fails, `postDeploy` does not run.
+Commands run over the **existing** SSH session (not a second connection), unless a successful hook sets `"reconnect": true`. Optional `timeoutMs` overrides the session default (`DEPLOYHUB_SSH_EXEC_TIMEOUT_MS`, 120s) so a hung command fails instead of hanging CI.
+
+On docker-ssh, `preDeploy` / `rollback` run **before** remote registry login and `docker stop`/`run`, so a hook can install Docker on a bare host. `postDeploy` runs **after** the port-publish inspect check (`docker inspect` confirms `0.0.0.0:<port>->`). A hook that curls the app's published port therefore sees a container DeployHub already treated as published. If that inspect fails, `postDeploy` does not run. `postInstall` is skipped entirely on this method.
 
 Hook `command` strings are raw remote shell — there is **no** `{{buildId}}` / `{{containerName}}` / `{{port}}` / `{{environment}}` substitution. Hardcode values per environment (or read them from the remote environment). Extra Docker environments use an env-scoped container name (`{project}-{env}`; the first/grandfathered env stays `{project}`), so a hook that `docker exec myapp …` on staging will miss `myapp-staging`.
 
@@ -773,7 +801,9 @@ Hook commands that look like they embed a secret (`--password`, `-p secret`, `TO
 
 Set `"reconnect": true` on a hook when the command only takes effect on a **new SSH login** — the usual case is `sudo usermod -aG docker $USER`. After that command succeeds, DeployHub closes the current session and opens a new one before the next hook or deploy step. Failed commands never reconnect. Omitted / `false` (the default) never reconnects.
 
-`init` and `env add` ask optionally — default is skip. After each command they ask **Add another … command?** so one stage can collect several entries (no cap), and whether that command needs an SSH reconnect (`[y/N]`, default N). `--yes` / non-interactive env add still writes no hooks. Example:
+`init` and `env add` ask optionally — default is skip. After each command they ask **Add another … command?** so one stage can collect several entries (no cap), and whether that command needs an SSH reconnect (`[y/N]`, default N). `--yes` / non-interactive env add still writes no hooks.
+
+Example — Amazon Linux bare host bootstrap (the docker-ssh `preDeploy` case) plus FastAPI + Prisma on SSH (the case that required `postInstall`):
 
 ```json
 "environments": {
@@ -781,8 +811,11 @@ Set `"reconnect": true` on a hook when the command only takes effect on a **new
     "config": {
       "hooks": {
         "preDeploy": [
-          { "command": "sudo usermod -aG docker ec2-user", "reconnect": true },
-          { "command": "docker exec myapp python manage.py migrate", "continueOnError": false, "timeoutMs": 60000 }
+          { "command": "sudo dnf install -y docker && sudo systemctl enable --now docker", "timeoutMs": 180000 },
+          { "command": "sudo usermod -aG docker ec2-user", "reconnect": true }
+        ],
+        "postInstall": [
+          { "command": "cd /var/www/app && python3.11 -m prisma generate", "continueOnError": false }
         ],
         "postDeploy": [
           { "command": "curl -s https://hooks.slack.com/services/T000/B000/xxx -d deployed", "continueOnError": true }
@@ -796,6 +829,75 @@ Set `"reconnect": true` on a hook when the command only takes effect on a **new
 }
 ```
 
+When that `postInstall` also needs values from a DeployHub-managed `.env` (already on disk by then — see [DeployHub-managed `.env`](#deployhub-managed-env)):
+
+```json
+{ "command": "cd /var/www/app && set -a && . ./.env && set +a && prisma generate", "continueOnError": false }
+```
+
+`preDeploy` cannot run `prisma generate` on a fresh host: the artifact has not been unzipped yet, so `schema.prisma` is missing. `postDeploy` is too late: uvicorn already imported `from prisma import Prisma` and crashed with `Client hasn't been generated yet.` `postInstall` sits after `pip install` / `npm install` and before process start. The same `postInstall` command re-runs during rollback against the restored schema.
+
+How hooks were proven on real hosts (including bare-host Docker install and Prisma codegen): `CONTEXT.md`.
+
+---
+
+## DeployHub-managed `.env`
+
+> **Two ways to get a `.env` onto your server — don't mix them:**
+> - **Managed** (`envFileSecretName` configured): DeployHub writes it for you from a GitHub Secret, and **OVERWRITES** it on every deploy to pick up secret updates.
+> - **Hand-placed** (nothing configured): you put a `.env` on the server yourself once; DeployHub never touches it, on any future deploy or rollback.
+
+| Mode | How it gets onto the server | Redeploy / rollback |
+|------|-----------------------------|---------------------|
+| **DeployHub-managed** (`environments.<env>.config.envFileSecretName` is set) | You paste the **full contents** of `.env` as a GitHub Secret. DeployHub SFTP-uploads it on every deploy. | **Overwritten every deploy** (and every rollback) with the **current** secret value. Secret updates take effect on the next deploy. `.env` is not versioned per `buildId`. |
+| **Hand-placed** (no `envFileSecretName`) | You SSH in and create `.env` yourself under the deploy path. | **Left untouched.** `unzip -o` / `rsync -a` (no `--delete`) do not wipe extra files. This is the older behavior. |
+
+> Rolling back **code** does not revert a secret change. Managed `.env` is not versioned per `buildId` — rollback re-delivers the **current** GitHub Secret. If you are rolling back because an env-var change broke the app, revert the secret as well (otherwise rollback still writes the broken value).
+
+### Setup (GitHub Secret)
+
+`init` / `env add` ask (SSH, EC2, Azure VM, GCP VM, and Docker `remote.mode: "ssh"` only; skipped for Kubernetes and Docker local/raw):
+
+```
+? Does this project have a .env file that should be deployed to the server? [y/N]
+```
+
+If yes, paste the **full contents** of the file as a GitHub Secret named:
+
+- First / grandfathered environment: `ENV_FILE`
+- Additional environments: `STAGING_ENV_FILE`, `PRODUCTION_ENV_FILE`, … (same `{ENV}_` prefix as `SSH_HOST`)
+
+Then confirm. DeployHub **cannot** verify the secret exists ahead of time (GitHub Secrets are write-only). `deployhub doctor` reports that the **name** is referenced in the workflow, and says plainly that the **value** cannot be checked.
+
+If `envFileSecretName` is set but the GitHub Secret was never created, is empty, or the name is misspelled, deploy **fails immediately** with:
+
+```text
+Managed .env is configured (GitHub Secret "ENV_FILE") but the value is missing or empty.
+```
+
+GitHub Actions injects an empty string for a missing secret, which hits this check. No empty `.env` is written to the target.
+
+Config stores only the secret **name**:
+
+```json
+"config": {
+  "envFileSecretName": "ENV_FILE"
+}
+```
+
+Never put the `.env` contents in `deployhub.config.json`. After adding the secret, run `deployhub sync-workflows` so `ENV_FILE` (or `STAGING_ENV_FILE`) is injected into the Actions job.
+
+Transfer is binary SFTP (`ssh.putFile` — the same mechanism as the artifact zip), not `echo "$CONTENT" > .env`. Special characters (`$`, quotes, backticks, multi-line values) stay intact, and the secret never appears in `[ssh] $ …` / `[docker] $ …` command logs. The remote file is `chmod 600` and owned by the deploy user.
+
+### Where the file lands
+
+- **SSH / EC2 / Azure VM / GCP VM:** `{deployPath}/.env` (fullstack: both frontend and backend deploy paths). Apps that already load `.env` from the working directory (python-dotenv, etc.) pick it up with no extra flags. The file is written **after** unzip/rsync and **before** `postInstall` / process start, so a hook like `cd /var/www/app && set -a && . ./.env && set +a && prisma generate` sees the managed values. `preDeploy` runs before extract, so `.env` is not there yet on a fresh host.
+- **Docker `remote.mode: "ssh"`:** `/opt/deployhub/envs/<project>-<env>/.env` on the **host**, then `docker run --env-file <that path> …` is wired in automatically. Project **and** environment are in the path so two apps (or staging + production) on one host never share a file. If `envFileSecretName` is unset, `docker run` is unchanged (no `--env-file`). `/opt/deployhub` is created automatically on first deploy. The one-time `sudo mkdir -p /opt/deployhub/envs && sudo chown $USER:$USER /opt/deployhub` step is a **rare fallback** — only if the host has neither a writable `/opt` nor passwordless sudo (see [one-time server setup](#one-time-server-setup-before-your-first-deploy)). Docker-ssh has no `postInstall`; bake codegen into the image.
+
+Kubernetes is out of scope for this feature.
+
+How managed `.env` was proven (byte-identical SFTP, empty-secret fail, postInstall sourcing): `CONTEXT.md`.
+
 ---
 
 ## Choosing a deployment method
@@ -830,6 +932,8 @@ sudo chown your-ssh-user:your-ssh-user /var/www/your-app-name
 
 Replace `/var/www/your-app-name` with your actual deploy path and `your-ssh-user` with your configured `SSH_USER` (e.g. `ec2-user` on Amazon Linux, `ubuntu` on Ubuntu). Without this, DeployHub cannot write your build output — `deployhub doctor` will catch it and show the exact fix.
 
+**Manually placed files (`.env`, etc.):** SSH / EC2 / Azure VM / GCP VM redeploy and rollback do **not** wipe the deploy directory. Extraction uses `unzip -o` (fullstack: `rsync -a` with no `--delete`) so only files present in the artifact are added or overwritten; a `.env` you place on the server yourself is left untouched **when this environment does not use DeployHub-managed `.env`**. If `envFileSecretName` is set, DeployHub **overwrites** `{deployPath}/.env` on every deploy — see [DeployHub-managed `.env`](#deployhub-managed-env). Do not mix the two modes. Keep secrets out of the zip. Docker-SSH is container-based and does not use this directory extract (managed `.env` for Docker-SSH uses `/opt/deployhub/envs/<project>-<env>/.env` + `--env-file`).
+
 **Frontend deploys** that auto-activate `nginx.conf` also need **passwordless sudo** for Nginx test/reload (and `cp` into `/etc/nginx/`). After installing Nginx, run `sudo visudo` and add a line like:
 
 ```bash
@@ -853,6 +957,17 @@ 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.
 
+**Managed `.env` directory:** DeployHub creates `/opt/deployhub/envs/<project>-<env>/` automatically on the first managed docker-ssh deploy — `mkdir -p`, then passwordless `sudo mkdir`/`chown` if the SSH user cannot write `/opt` (the same class of auto-create as SSH deploy-path `ensureWritableDeployDir`). Typical Ubuntu / Amazon Linux cloud images already have passwordless sudo for the default user, so there is **no extra one-time mkdir**.
+
+If the SSH user cannot write `/opt` **and** has no passwordless sudo, deploy fails with the exact commands (same class of message as the docker-group `usermod` line above):
+
+```bash
+sudo mkdir -p /opt/deployhub/envs
+sudo chown $USER:$USER /opt/deployhub
+```
+
+Then retry the deploy. `deployhub doctor` cannot create that path (it does not write files over SSH).
+
 You can also put that bootstrap in **preDeploy hooks** on a bare host (install Docker, `usermod`, `"reconnect": true`). Registry login runs **after** preDeploy, so those hooks get a chance to install `docker` before `docker login`. Failed login used to abort first (`docker: command not found`) and skip the hooks.
 
 ### SSH
@@ -904,7 +1019,7 @@ You can also put that bootstrap in **preDeploy hooks** on a bare host (install D
 - [ ] 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). A `preDeploy` hook can install Docker and run that `usermod` with `"reconnect": true`; registry login happens after preDeploy.
+- [ ] **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). Managed `.env` directories under `/opt/deployhub/envs` are created automatically when the SSH user can write `/opt` or has passwordless sudo. A `preDeploy` hook can install Docker and run that `usermod` with `"reconnect": true`; registry login happens after preDeploy.
 
 `init` and `env add` ask **Where should the container run?**
 
@@ -920,7 +1035,7 @@ You can also put that bootstrap in **preDeploy hooks** on a bare host (install D
 - 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`, 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`
+- Docker daemon connectivity test during `init` (local / raw); SSH key validity, SSH host reachability, remote Docker daemon reachable, and remote Docker permission (`docker` group) 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)
@@ -1175,6 +1290,9 @@ Prefer `deployhub init` over hand-writing config — it sets adapters, workflow,
 | `Deploy requires storage upload` | Add at least one storage provider in config |
 | AWS / GDrive check fails in `doctor` | Run `deployhub storage add <provider>` and match GitHub Secrets |
 | SSH deploy fails | Verify `SSH_KEY_PATH` points to your private `.pem` file (or `SSH_KEY` in CI); user can write to deploy path; port 22 open |
+| SSH-mode Docker: permission denied talking to dockerd | SSH user is not in the `docker` group. On the server: `sudo usermod -aG docker <user>`, then reconnect. `deployhub doctor` prints this line. |
+| Docker-ssh container running but app unreachable | Missing published port. Set `environments.<env>.config.port` (asked as **Default port**). Doctor / `deployhub verify` check `0.0.0.0:<port>->`. |
+| `Managed .env is configured … missing or empty` | Add the GitHub Secret named in `envFileSecretName` (full `.env` file contents). Doctor cannot check the value — GitHub Secrets are write-only. |
 | Wrong output uploaded | Fix `buildOutput` in config (`dist` vs `build` vs `.next`) |
 | Tests fail in CI | Set `"pipeline": { "test": false }` temporarily, or fix tests |
 | Monorepo subfolders | Edit `buildCommand` paths in `deployhub.config.json` after init |
@@ -1223,7 +1341,7 @@ Run `deployhub doctor` after any config change.
 | `deployhub clean` | Remove old local artifacts |
 | `deployhub update` | Check for CLI updates |
 
-**Tests:** `npm test` — currently **442 passing** across the Jest suites (1 skipped).
+**Tests:** `npm test` — currently **466 passing** across the Jest suites (1 skipped).
 
 ## Storage vs deployment lookup credentials
 
@@ -1278,6 +1396,7 @@ Add these secrets in your repository (Settings → Secrets and variables → Act
 | `AZURE_VM_LOOKUP_SUBSCRIPTION_ID`, `AZURE_VM_LOOKUP_RESOURCE_GROUP`, `AZURE_VM_LOOKUP_VM_NAME` | Optional Azure VM IP lookup |
 | `GCP_VM_LOOKUP_PROJECT_ID`, `GCP_ZONE`, `GCP_INSTANCE_NAME`, `GCP_VM_LOOKUP_KEY_FILE` | Optional GCP VM IP lookup (project/key distinct from GCP Storage) |
 | `DOCKER_IMAGE_NAME`, `DOCKER_REGISTRY_USERNAME`, `DOCKER_REGISTRY_TOKEN`, `DOCKER_REGISTRY_URL`, `DOCKER_HOST` | Docker deployment (`DOCKER_IMAGE_TAG` optional) |
+| `ENV_FILE` / `{ENV}_ENV_FILE` | DeployHub-managed `.env` — **full file contents**, only when `envFileSecretName` is set. Grandfathered env uses `ENV_FILE`; additional envs use `STAGING_ENV_FILE`, `PRODUCTION_ENV_FILE`, … (same prefix as `SSH_HOST`) |
 | `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 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.

package/package.json

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

package/src/commands/doctor.js

@@ -54,6 +54,7 @@ import {
   preferredPhpFpmUnitName,
 } from '../utils/php-fpm.js';
 import { getHooksDoctorChecks } from '../deployment/hooks.js';
+import { getEnvFileDoctorChecks } from '../deployment/env-file.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -1414,6 +1415,15 @@ export function registerDoctorCommand(program) {
           informationalCheckNames.add(hookCheck.name);
           results.push(await runCheck(hookCheck.name, async () => hookCheck));
         }
+        let workflowText = '';
+        const deployWorkflowPath = path.join(cwd, '.github', 'workflows', 'deployhub.yml');
+        if (await fs.pathExists(deployWorkflowPath)) {
+          workflowText = await fs.readFile(deployWorkflowPath, 'utf8');
+        }
+        for (const envFileCheck of getEnvFileDoctorChecks(config, { workflowText })) {
+          informationalCheckNames.add(envFileCheck.name);
+          results.push(await runCheck(envFileCheck.name, async () => envFileCheck));
+        }
         const driftChecks = await getWorkflowDriftDoctorChecks(cwd, config);
         for (const check of driftChecks) {
           results.push(await runCheck(check.name, async () => check));

package/src/core/config.js

@@ -76,14 +76,24 @@ const MethodConfigSchema = z
     /**
      * Remote shell hooks for SSH-based methods (ssh / ec2 / azure-vm / gcp-vm /
      * docker remote.mode ssh). Rejected on kubernetes and docker local/raw.
+     * `postInstall` is ssh/ec2/azure-vm/gcp-vm only (after remote dep install,
+     * before process start). Docker-ssh skips it: deps install at image build.
      */
     hooks: z
       .object({
         preDeploy: z.array(HookCommandSchema).optional(),
+        postInstall: z.array(HookCommandSchema).optional(),
         postDeploy: z.array(HookCommandSchema).optional(),
         rollback: z.array(HookCommandSchema).optional(),
       })
       .optional(),
+    /**
+     * GitHub Secret *name* whose value is the full .env file. Never store the
+     * secret value here. SSH methods overwrite deployPath/.env every deploy;
+     * docker remote.mode ssh writes /opt/deployhub/envs/<project>-<env>/.env
+     * and passes --env-file. Unset = hand-placed .env (if any) is left alone.
+     */
+    envFileSecretName: z.string().min(1).optional(),
     appName: z.string().optional(),
     framework: z.string().optional(),
     port: z.number().optional(),

package/src/deployment/deployment-env.js

@@ -424,27 +424,62 @@ function dockerHasExplicitRemoteMode(settings) {
   return mode === 'ssh' || mode === 'local' || mode === 'raw';
 }
 
+/** Added only when environments.<env>.config.envFileSecretName is set. */
+const MANAGED_ENV_FILE_DEF = {
+  key: 'ENV_FILE',
+  optionalReason:
+    'only when this environment uses a DeployHub-managed .env (envFileSecretName in config)',
+  comment: [
+    'FULL CONTENTS of the project .env file (paste as a GitHub Secret).',
+    'Uploaded to the server on every deploy (including rollback) via SFTP — never committed.',
+    'Overwrites the remote .env each deploy. Do not also hand-place a .env for this environment.',
+  ],
+  when: 'optional',
+};
+
+/**
+ * @param {string} deployType
+ * @param {Record<string, unknown>|null|undefined} settings
+ * @returns {boolean}
+ */
+function methodSupportsManagedEnvFile(deployType, settings) {
+  if (deployType === 'ssh' || deployType === 'ec2' || deployType === 'azure-vm' || deployType === 'gcp-vm') {
+    return true;
+  }
+  if (deployType === 'docker') {
+    return resolveDockerRemoteMode(settings || {}, {}) === 'ssh';
+  }
+  return false;
+}
+
 /**
  * Per-env docker defs: ssh mode adds SSH_* and drops raw DOCKER_HOST;
  * explicit local drops DOCKER_HOST; configs with no remote.mode keep legacy defs.
+ * ENV_FILE is appended only when envFileSecretName is set on a supported method.
  *
  * @param {string} deployType
  * @param {Record<string, unknown>|null} [settings]
  * @returns {EnvVarDef[]}
  */
 export function getMethodEnvDefs(deployType, settings = null) {
-  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
-  if (deployType !== 'docker') return defs;
-  const s = settings || {};
-  if (!dockerHasExplicitRemoteMode(s)) {
-    return defs;
-  }
-  const mode = resolveDockerRemoteMode(s, {});
-  if (mode === 'ssh') {
-    return [...defs.filter((d) => !DOCKER_HOST_KEYS.has(d.key)), ...DOCKER_SSH_ENV_VARS];
+  let defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+  if (deployType === 'docker') {
+    const s = settings || {};
+    if (dockerHasExplicitRemoteMode(s)) {
+      const mode = resolveDockerRemoteMode(s, {});
+      if (mode === 'ssh') {
+        defs = [...defs.filter((d) => !DOCKER_HOST_KEYS.has(d.key)), ...DOCKER_SSH_ENV_VARS];
+      } else if (mode === 'local') {
+        defs = defs.filter((d) => !DOCKER_HOST_KEYS.has(d.key));
+      }
+    }
   }
-  if (mode === 'local') {
-    return defs.filter((d) => !DOCKER_HOST_KEYS.has(d.key));
+  const secretName =
+    settings && typeof settings.envFileSecretName === 'string'
+      ? settings.envFileSecretName.trim()
+      : '';
+  if (secretName && methodSupportsManagedEnvFile(deployType, settings)) {
+    defs = [...defs, MANAGED_ENV_FILE_DEF];
   }
   return defs;
 }

package/src/deployment/env-file.js

@@ -0,0 +1,344 @@
+/**
+ * DeployHub-managed .env: GitHub Secret name in config, binary SFTP of the
+ * secret value onto the deploy target. SSH methods write deployPath/.env
+ * (overwrite every deploy). Docker remote.mode "ssh" writes a per-project-
+ * per-env host path and passes --env-file to docker run.
+ *
+ * Never interpolate secret content into a shell command — the [ssh]/[docker]
+ * `$ …` logger prints every exec() string verbatim.
+ */
+
+import fs from 'fs-extra';
+import os from 'os';
+import path from 'path';
+import { createLogger } from '../logger/index.js';
+import { shellQuote } from '../utils/shell-quote.js';
+import { getEnvMethod, getEnvSettings } from '../core/environments.js';
+import { resolveDockerRemoteMode } from '../utils/docker-remote-mode.js';
+import { prefixSecretKey } from './deployment-env.js';
+
+/** Unprefixed GitHub Actions / process.env key after secret overlay. */
+export const MANAGED_ENV_FILE_UNPREFIXED_KEY = 'ENV_FILE';
+
+/** Host directory for docker-ssh managed env files (project+env scoped). */
+export const DOCKER_MANAGED_ENV_ROOT = '/opt/deployhub/envs';
+
+const SSH_BASED_METHODS = new Set(['ssh', 'ec2', 'azure-vm', 'gcp-vm']);
+
+/**
+ * @param {unknown} settings
+ * @returns {string|null}
+ */
+export function getEnvFileSecretName(settings = {}) {
+  const name = settings && /** @type {Record<string, unknown>} */ (settings).envFileSecretName;
+  if (typeof name !== 'string') return null;
+  const trimmed = name.trim();
+  return trimmed || null;
+}
+
+/**
+ * @param {Record<string, unknown>} [settings]
+ * @returns {boolean}
+ */
+export function envHasManagedEnvFile(settings = {}) {
+  return getEnvFileSecretName(settings) != null;
+}
+
+/**
+ * First environment (init / empty existing list) → ENV_FILE.
+ * Additional environments → {ENV}_ENV_FILE (same grandfathering as SSH_HOST).
+ *
+ * @param {string} envName
+ * @param {string[]} [existingEnvNames]
+ * @returns {string}
+ */
+export function suggestEnvFileSecretName(envName, existingEnvNames = []) {
+  if (!Array.isArray(existingEnvNames) || existingEnvNames.length === 0) {
+    return MANAGED_ENV_FILE_UNPREFIXED_KEY;
+  }
+  return prefixSecretKey(envName || 'production', MANAGED_ENV_FILE_UNPREFIXED_KEY);
+}
+
+/**
+ * @param {string|undefined} method
+ * @param {Record<string, unknown>} [settings]
+ * @returns {boolean}
+ */
+export function envFileSupportedForMethod(method, settings = {}) {
+  if (SSH_BASED_METHODS.has(String(method || ''))) return true;
+  if (method === 'docker') {
+    return resolveDockerRemoteMode(settings) === 'ssh';
+  }
+  return false;
+}
+
+/**
+ * Throw if a managed .env is configured on a method that cannot deliver it.
+ * No-op when envFileSecretName is unset (additive).
+ *
+ * @param {string|undefined} method
+ * @param {Record<string, unknown>} [settings]
+ * @param {string} [envName]
+ */
+export function assertEnvFileAllowed(method, settings = {}, envName = 'this environment') {
+  if (!envHasManagedEnvFile(settings)) return;
+  if (envFileSupportedForMethod(method, settings)) return;
+
+  let why;
+  if (method === 'kubernetes') {
+    why = 'Kubernetes is out of scope for DeployHub-managed .env (no SSH file transfer / docker --env-file).';
+  } else if (method === 'docker') {
+    why =
+      `Docker remote.mode "${resolveDockerRemoteMode(settings)}" has no DeployHub-managed SSH session ` +
+      `(managed .env requires remote.mode "ssh").`;
+  } else {
+    why = `Method "${method}" does not support DeployHub-managed .env.`;
+  }
+  throw new Error(
+    `Managed .env is configured for environment "${envName}" but is not supported: ${why} ` +
+      `Remove environments.${envName}.config.envFileSecretName or use ssh / ec2 / azure-vm / gcp-vm / docker (remote.mode ssh).`
+  );
+}
+
+/**
+ * Read the secret value from CI env. After applyEnvSecretOverlay the unprefixed
+ * ENV_FILE key is populated for prefixed environments. Never log the return value.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @param {Record<string, unknown>} [settings]
+ * @returns {string|null} null when not configured
+ */
+export function readManagedEnvFileContent(env = {}, settings = {}) {
+  const name = getEnvFileSecretName(settings);
+  if (!name) return null;
+  const raw = env[MANAGED_ENV_FILE_UNPREFIXED_KEY] ?? env[name];
+  if (raw == null || raw === '') {
+    throw new Error(
+      `Managed .env is configured (GitHub Secret "${name}") but the value is missing or empty. ` +
+        `Add that secret with the FULL CONTENTS of your .env file. ` +
+        `DeployHub cannot verify the secret exists ahead of time (GitHub Secrets are write-only).`
+    );
+  }
+  return String(raw);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function sanitizePathSegment(value) {
+  return (
+    String(value || 'app')
+      .replace(/[^a-zA-Z0-9._-]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'app'
+  );
+}
+
+/**
+ * @param {string} remotePath
+ * @returns {string}
+ */
+function stripTrailingSlash(remotePath) {
+  const s = String(remotePath || '').replace(/\\/g, '/');
+  if (s.length > 1 && s.endsWith('/')) return s.replace(/\/+$/, '');
+  return s || '/';
+}
+
+/**
+ * @param {string} remotePath
+ * @returns {string}
+ */
+function posixDirname(remotePath) {
+  const normalized = stripTrailingSlash(remotePath);
+  const idx = normalized.lastIndexOf('/');
+  if (idx <= 0) return '/';
+  return normalized.slice(0, idx);
+}
+
+/**
+ * Docker-ssh host path: /opt/deployhub/envs/<project>-<env>/.env
+ * Always project AND environment scoped so two apps on one host never collide.
+ *
+ * @param {{ project?: string }} config
+ * @param {string} envName
+ * @returns {string}
+ */
+export function resolveDockerManagedEnvRemotePath(config, envName) {
+  const project = sanitizePathSegment(config?.project || 'app');
+  const env = sanitizePathSegment(envName || 'default');
+  return `${DOCKER_MANAGED_ENV_ROOT}/${project}-${env}/.env`;
+}
+
+/**
+ * SSH methods: deployPath/.env. Full-stack writes both frontend and backend
+ * deploy paths (same secret — one environment, two processes).
+ *
+ * @param {{ projectType?: string }} config
+ * @param {Record<string, unknown>} settings
+ * @returns {string[]}
+ */
+export function resolveSshManagedEnvRemotePaths(config, settings = {}) {
+  const projectType = config?.projectType || 'frontend';
+  const deployPath = stripTrailingSlash(
+    String(settings.deployPath || settings.path || '/var/www/app')
+  );
+  if (projectType === 'both') {
+    const fe = stripTrailingSlash(String(settings.frontendDeployPath || deployPath));
+    const be = stripTrailingSlash(String(settings.backendDeployPath || deployPath));
+    return [...new Set([`${fe}/.env`, `${be}/.env`])];
+  }
+  return [`${deployPath}/.env`];
+}
+
+/**
+ * Write content to a local temp file, SFTP it with ssh.putFile (binary, never
+ * shell-interpolated), chmod 600, then delete the local temp file.
+ *
+ * @param {{
+ *   ssh: { putFile: Function },
+ *   session: { exec: Function },
+ *   content: string,
+ *   remotePath: string,
+ *   user: string,
+ *   log?: { info: Function },
+ * }} opts
+ */
+export async function uploadManagedEnvFile(opts) {
+  const { ssh, session, content, remotePath, user } = opts;
+  const log = opts.log || createLogger('deploy');
+  if (typeof content !== 'string') {
+    throw new Error('Managed .env content must be a string');
+  }
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'deployhub-env-'));
+  const localPath = path.join(tmpDir, '.env');
+  try {
+    await fs.writeFile(localPath, content, { encoding: 'utf8', mode: 0o600 });
+    const parent = posixDirname(remotePath);
+    const parentQ = shellQuote(parent);
+    const remoteQ = shellQuote(remotePath);
+    const userQ = shellQuote(user);
+    log.info(`Uploading managed .env to ${remotePath}`);
+    const dockerHostRoot = '/opt/deployhub';
+    const underDockerRoot =
+      parent === DOCKER_MANAGED_ENV_ROOT || parent.startsWith(`${DOCKER_MANAGED_ENV_ROOT}/`);
+    // Chown /opt/deployhub (not just the leaf) so later projects can mkdir as the
+    // deploy user without sudo — same idea as README `chown $USER:$USER /opt/deployhub`.
+    const chownTarget = underDockerRoot ? dockerHostRoot : parent;
+    const chownQ = shellQuote(chownTarget);
+    try {
+      await session.exec(ssh, `mkdir -p ${parentQ}`);
+    } catch {
+      try {
+        await session.exec(
+          ssh,
+          `sudo -n mkdir -p ${parentQ} && sudo -n chown -R ${userQ}:${userQ} ${chownQ}`
+        );
+      } catch {
+        throw new Error(
+          `Cannot create ${parent} for managed .env (the SSH user cannot write there).\n` +
+            `  Run this on your server once:\n` +
+            `    sudo mkdir -p ${parent}\n` +
+            `    sudo chown ${user}:${user} ${chownTarget}\n` +
+            `  (or grant passwordless sudo for mkdir/chown).`
+        );
+      }
+    }
+    await session.exec(
+      ssh,
+      `if [ ! -w ${parentQ} ]; then sudo -n chown ${userQ}:${userQ} ${parentQ}; fi`
+    );
+    await ssh.putFile(localPath, remotePath);
+    await session.exec(ssh, `chmod 600 ${remoteQ}`);
+    try {
+      await session.exec(ssh, `chown ${userQ}:${userQ} ${remoteQ}`);
+    } catch {
+      await session.exec(ssh, `sudo -n chown ${userQ}:${userQ} ${remoteQ}`);
+    }
+  } finally {
+    await fs.remove(tmpDir).catch(() => {});
+  }
+}
+
+/**
+ * Collect secret names referenced as ${{ secrets.NAME }} in workflow YAML.
+ * Local copy so env-file.js does not import github-actions.js (cycle risk).
+ *
+ * @param {string} yaml
+ * @returns {string[]}
+ */
+function extractWorkflowSecretKeys(yaml) {
+  /** @type {Set<string>} */
+  const keys = new Set();
+  const re = /\$\{\{\s*secrets\.([A-Z0-9_]+)\s*\}\}/g;
+  let match;
+  while ((match = re.exec(String(yaml || ''))) !== null) {
+    keys.add(match[1]);
+  }
+  return [...keys];
+}
+
+/**
+ * Informational doctor lines — pass: true, never blocks.
+ * Cannot verify the secret VALUE (GitHub Secrets are write-only).
+ *
+ * @param {Record<string, unknown>} config
+ * @param {{ workflowText?: string }} [options]
+ * @returns {{ name: string, pass: boolean, message: string }[]}
+ */
+export function getEnvFileDoctorChecks(config, options = {}) {
+  const envs = /** @type {Record<string, unknown>} */ (config.environments || {});
+  const workflowKeys = new Set(extractWorkflowSecretKeys(options.workflowText || ''));
+  const hasWorkflowText =
+    typeof options.workflowText === 'string' && options.workflowText.length > 0;
+  /** @type {{ name: string, pass: boolean, message: string }[]} */
+  const checks = [];
+
+  for (const [name, entry] of Object.entries(envs)) {
+    const settings = getEnvSettings(entry);
+    const secretName = getEnvFileSecretName(settings);
+    if (!secretName) continue;
+    const method = getEnvMethod(entry);
+    const supported = envFileSupportedForMethod(method, settings);
+    const listed = workflowKeys.has(secretName);
+    let listing;
+    if (!hasWorkflowText) {
+      listing =
+        `Workflow file not available here — cannot confirm "${secretName}" is in the secret list. ` +
+        `Run deployhub sync-workflows after enabling managed .env.`;
+    } else if (listed) {
+      listing = `GitHub Secret "${secretName}" is referenced in the deploy workflow's secret list.`;
+    } else {
+      listing =
+        `GitHub Secret "${secretName}" is NOT referenced in the deploy workflow ` +
+        `(run deployhub sync-workflows).`;
+    }
+    const limitation =
+      'Secret VALUES cannot be verified (GitHub Secrets are write-only).';
+    const overwrite =
+      'DeployHub-managed .env is overwritten every deploy; do not also hand-place a .env for this environment.';
+    checks.push({
+      name: `Managed .env (${name})`,
+      pass: true,
+      message: supported
+        ? `Managed .env for '${name}': ${listing} ${limitation} ${overwrite}`
+        : `Managed .env configured for '${name}' (secret "${secretName}") but ${method} does not deliver it — remove envFileSecretName or use an SSH-based method / docker remote.mode ssh. ${limitation}`,
+    });
+  }
+  return checks;
+}
+
+export default {
+  MANAGED_ENV_FILE_UNPREFIXED_KEY,
+  DOCKER_MANAGED_ENV_ROOT,
+  getEnvFileSecretName,
+  envHasManagedEnvFile,
+  suggestEnvFileSecretName,
+  envFileSupportedForMethod,
+  assertEnvFileAllowed,
+  readManagedEnvFileContent,
+  resolveDockerManagedEnvRemotePath,
+  resolveSshManagedEnvRemotePaths,
+  uploadManagedEnvFile,
+  getEnvFileDoctorChecks,
+};

package/src/deployment/hooks.js

@@ -1,7 +1,9 @@
 /**
- * Per-environment remote shell hooks (preDeploy / postDeploy / rollback).
+ * Per-environment remote shell hooks (preDeploy / postInstall / postDeploy / rollback).
  * One implementation for ssh, ec2, azure-vm, gcp-vm, and docker remote.mode ssh.
  * Callers must pass the deploy's existing SSH session — do not connect again.
+ * `postInstall` is invoked only from ssh.js `runBackendStartSequence` (plain SSH
+ * methods). Docker-ssh never runs it — image build already installed dependencies.
  */
 
 import { createLogger } from '../logger/index.js';
@@ -9,10 +11,10 @@ import { formatRemoteCommandFailure } from '../utils/shell-quote.js';
 import { getEnvMethod, getEnvSettings } from '../core/environments.js';
 import { resolveDockerRemoteMode } from '../utils/docker-remote-mode.js';
 
-/** @typedef {'preDeploy'|'postDeploy'|'rollback'} HookStage */
+/** @typedef {'preDeploy'|'postInstall'|'postDeploy'|'rollback'} HookStage */
 
 /** @type {HookStage[]} */
-export const HOOK_STAGES = ['preDeploy', 'postDeploy', 'rollback'];
+export const HOOK_STAGES = ['preDeploy', 'postInstall', 'postDeploy', 'rollback'];
 
 const SSH_BASED_METHODS = new Set(['ssh', 'ec2', 'azure-vm', 'gcp-vm']);
 
@@ -75,16 +77,17 @@ function normalizeHookList(raw) {
 
 /**
  * @param {Record<string, unknown>} [settings]
- * @returns {{ preDeploy: ReturnType<typeof normalizeHookList>, postDeploy: ReturnType<typeof normalizeHookList>, rollback: ReturnType<typeof normalizeHookList> }}
+ * @returns {{ preDeploy: ReturnType<typeof normalizeHookList>, postInstall: ReturnType<typeof normalizeHookList>, postDeploy: ReturnType<typeof normalizeHookList>, rollback: ReturnType<typeof normalizeHookList> }}
  */
 export function getEnvHooks(settings = {}) {
   const raw = settings.hooks;
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    return { preDeploy: [], postDeploy: [], rollback: [] };
+    return { preDeploy: [], postInstall: [], postDeploy: [], rollback: [] };
   }
   const h = /** @type {Record<string, unknown>} */ (raw);
   return {
     preDeploy: normalizeHookList(h.preDeploy),
+    postInstall: normalizeHookList(h.postInstall),
     postDeploy: normalizeHookList(h.postDeploy),
     rollback: normalizeHookList(h.rollback),
   };
@@ -96,7 +99,13 @@ export function getEnvHooks(settings = {}) {
  */
 export function envHasAnyHooks(settings = {}) {
   const h = getEnvHooks(settings);
-  return h.preDeploy.length + h.postDeploy.length + h.rollback.length > 0;
+  return (
+    h.preDeploy.length +
+      h.postInstall.length +
+      h.postDeploy.length +
+      h.rollback.length >
+    0
+  );
 }
 
 /**
@@ -241,6 +250,7 @@ export function getHooksDoctorChecks(config) {
     const h = getEnvHooks(settings);
     const parts = [];
     if (h.preDeploy.length) parts.push(`${h.preDeploy.length} preDeploy`);
+    if (h.postInstall.length) parts.push(`${h.postInstall.length} postInstall`);
     if (h.postDeploy.length) parts.push(`${h.postDeploy.length} postDeploy`);
     if (h.rollback.length) parts.push(`${h.rollback.length} rollback`);
     const method = getEnvMethod(entry);

package/src/deployment/index.js

@@ -11,6 +11,7 @@ import {
   getEnvSettings,
 } from '../core/environments.js';
 import { assertHooksAllowed } from './hooks.js';
+import { assertEnvFileAllowed } from './env-file.js';
 import { applyEnvSecretOverlay } from './deployment-env.js';
 import { recordEnvDeployment } from '../storage/index.js';
 import { buildArtifactRemoteKey } from '../utils/build-id.js';
@@ -84,6 +85,7 @@ export async function deployToAll(config, artifactDir, envNames) {
 
     const method = getEnvMethod(envConfig);
     assertHooksAllowed(method, getEnvSettings(envConfig), envName);
+    assertEnvFileAllowed(method, getEnvSettings(envConfig), envName);
     const provider = getDeploymentProvider(method, config, envName);
     log.info(`Deploying to ${envName} (${method})...`);
     await provider.deploy(artifactDir);
@@ -133,6 +135,7 @@ export async function rollbackAll(config, artifactDir, envNames, meta) {
     const envConfig = config.environments[envName];
     const method = getEnvMethod(envConfig);
     assertHooksAllowed(method, getEnvSettings(envConfig), envName);
+    assertEnvFileAllowed(method, getEnvSettings(envConfig), envName);
     const provider = getDeploymentProvider(method, config, envName);
     await provider.rollback(artifactDir, meta);
   }

package/src/deployment/init-prompts.js

@@ -1,6 +1,7 @@
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import { createEnvNamePromptValidate, normalizeGitBranchName } from '../core/environments.js';
+import { suggestEnvFileSecretName } from './env-file.js';
 import {
   suggestSshUser,
   listKubeContexts,
@@ -154,12 +155,17 @@ export async function promptServerDeployment(
 
   const triggerMeta = await promptTriggerAndBranch(options);
   const hookMeta = await promptDeployHooksIfSupported(deployType, methodAnswers);
-  return { ...methodAnswers, ...triggerMeta, ...hookMeta };
+  const envFileMeta = await promptManagedEnvFileIfSupported(deployType, methodAnswers, {
+    existingEnvNames,
+    envName: methodAnswers.envName || options.envName,
+  });
+  return { ...methodAnswers, ...triggerMeta, ...hookMeta, ...envFileMeta };
 }
 
 /**
- * Optional pre/post/rollback commands. Skipped unless the method has a
- * DeployHub-managed SSH session (ssh / ec2 / azure-vm / gcp-vm / docker-ssh).
+ * Optional pre/post-install/post/rollback commands. Skipped unless the method
+ * has a DeployHub-managed SSH session (ssh / ec2 / azure-vm / gcp-vm / docker-ssh).
+ * `postInstall` is ssh-based only — Docker-ssh installs deps at image build time.
  *
  * @param {string} deployType
  * @param {Record<string, unknown>} methodAnswers
@@ -170,7 +176,65 @@ async function promptDeployHooksIfSupported(deployType, methodAnswers) {
   if (!sshBased && !dockerSsh) {
     return {};
   }
-  return promptDeployHooks();
+  return promptDeployHooks({ includePostInstall: sshBased });
+}
+
+/**
+ * Optional DeployHub-managed .env (GitHub Secret). Same method scope as hooks:
+ * ssh / ec2 / azure-vm / gcp-vm / docker-ssh. `--yes` never enters this path.
+ *
+ * @param {string} deployType
+ * @param {Record<string, unknown>} methodAnswers
+ * @param {{ existingEnvNames?: string[], envName?: string }} [options]
+ */
+async function promptManagedEnvFileIfSupported(deployType, methodAnswers, options = {}) {
+  const sshBased = SSH_BASED.includes(deployType);
+  const dockerSsh = deployType === 'docker' && methodAnswers.remoteMode === 'ssh';
+  if (!sshBased && !dockerSsh) {
+    return {};
+  }
+  return promptManagedEnvFile({
+    envName: options.envName || methodAnswers.envName || 'production',
+    existingEnvNames: options.existingEnvNames || [],
+  });
+}
+
+/**
+ * @param {{ envName?: string, existingEnvNames?: string[] }} [options]
+ * @returns {Promise<{ envFileSecretName?: string }>}
+ */
+export async function promptManagedEnvFile(options = {}) {
+  const envName = options.envName || 'production';
+  const existingEnvNames = options.existingEnvNames || [];
+  const suggested = suggestEnvFileSecretName(envName, existingEnvNames);
+
+  const { deployEnvFile } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'deployEnvFile',
+      message: 'Does this project have a .env file that should be deployed to the server?',
+      default: false,
+    },
+  ]);
+  if (!deployEnvFile) return {};
+
+  console.log(
+    chalk.gray(
+      `\n  Paste the FULL CONTENTS of your .env file as a GitHub Secret named ${suggested}, then confirm below.\n` +
+        `  DeployHub cannot verify the secret exists ahead of time (GitHub Secrets are write-only).\n`
+    )
+  );
+
+  await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'envFileSecretAdded',
+      message: `Confirm once you've added the secret ${suggested}`,
+      default: false,
+    },
+  ]);
+
+  return { envFileSecretName: suggested };
 }
 
 /**
@@ -247,11 +311,13 @@ async function promptHookStageCommands(opts) {
 }
 
 /**
+ * @param {{ includePostInstall?: boolean }} [options]
  * @returns {Promise<{ hooks?: Record<string, { command: string, continueOnError: boolean }[]> }>}
  */
-export async function promptDeployHooks() {
+export async function promptDeployHooks(options = {}) {
   /** @type {Record<string, { command: string, continueOnError: boolean }[]>} */
   const hooks = {};
+  const includePostInstall = options.includePostInstall !== false;
 
   const preDeploy = await promptHookStageCommands({
     firstConfirmName: 'addPreDeploy',
@@ -263,6 +329,19 @@ export async function promptDeployHooks() {
   });
   if (preDeploy.length) hooks.preDeploy = preDeploy;
 
+  if (includePostInstall) {
+    const postInstall = await promptHookStageCommands({
+      firstConfirmName: 'addPostInstall',
+      firstMessage:
+        'Add a post-install command? (e.g. prisma generate, collectstatic — runs after dependencies install, before the app starts)',
+      anotherMessage: 'Add another post-install command?',
+      commandMessage: 'Post-install command:',
+      abortMessage: 'Abort deploy if this command fails?',
+      abortDefault: true,
+    });
+    if (postInstall.length) hooks.postInstall = postInstall;
+  }
+
   const postDeploy = await promptHookStageCommands({
     firstConfirmName: 'addPostDeploy',
     firstMessage: 'Add a post-deploy command? (e.g. clear cache, notify)',
@@ -885,6 +964,7 @@ export function buildServerEnvEntry(
       settings.port = n;
     }
     attachHooksFromAnswers(settings, deployAnswers);
+    attachEnvFileFromAnswers(settings, deployAnswers);
     return withTriggerAndBranch(
       {
         enabled: true,
@@ -931,6 +1011,7 @@ export function buildServerEnvEntry(
   }
 
   attachHooksFromAnswers(settings, deployAnswers);
+  attachEnvFileFromAnswers(settings, deployAnswers);
   return withTriggerAndBranch(
     {
       enabled: true,
@@ -951,11 +1032,23 @@ function attachHooksFromAnswers(settings, deployAnswers) {
   const raw = deployAnswers && deployAnswers.hooks;
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return;
   const hooks = /** @type {Record<string, unknown>} */ (raw);
-  if (hooks.preDeploy || hooks.postDeploy || hooks.rollback) {
+  if (hooks.preDeploy || hooks.postInstall || hooks.postDeploy || hooks.rollback) {
     settings.hooks = hooks;
   }
 }
 
+/**
+ * Store the GitHub Secret *name* only — never the .env contents.
+ * @param {Record<string, unknown>} settings
+ * @param {Record<string, unknown>} deployAnswers
+ */
+function attachEnvFileFromAnswers(settings, deployAnswers) {
+  const name = deployAnswers && deployAnswers.envFileSecretName;
+  if (typeof name === 'string' && name.trim()) {
+    settings.envFileSecretName = name.trim();
+  }
+}
+
 /**
  * Overlay prompt answers onto the env entry. `--yes` / missing answers keep
  * trigger `manual` and omit `branch` (backward compatible).

package/src/deployment/providers/docker.js

@@ -6,6 +6,12 @@ import { resolveDockerContainerName } from '../../utils/docker-container-name.js
 import { getEnvSettings, mergeMethodSettingsIntoEnv } from '../../core/environments.js';
 import { createSshExecSession } from '../ssh-connection.js';
 import { assertHooksAllowed, runDeployHooks } from '../hooks.js';
+import {
+  assertEnvFileAllowed,
+  readManagedEnvFileContent,
+  resolveDockerManagedEnvRemotePath,
+  uploadManagedEnvFile,
+} from '../env-file.js';
 import { resolveDockerRemoteMode } from '../../utils/docker-remote-mode.js';
 import {
   resolveDockerSshTarget,
@@ -68,6 +74,10 @@ export function createDockerProvider(config, envName, env = process.env) {
    */
   async function deploy(artifactDir, options = {}) {
     assertHooksAllowed('docker', settings, envName);
+    assertEnvFileAllowed('docker', settings, envName);
+    // Fail fast (before image pull / SSH): missing or empty GitHub Secret must
+    // not reach uploadManagedEnvFile. Actions injects "" for a never-created name.
+    readManagedEnvFileContent(effectiveEnv, settings);
     const imageRef = options.fullImage || fullImage;
     log.info(`Deploying via Docker (image: ${imageRef})...`);
 
@@ -159,7 +169,15 @@ export function createDockerProvider(config, envName, env = process.env) {
    */
   async function deployOverSsh(imageRef, port, options = {}) {
     const isRollback = options.isRollback === true;
-    const cmds = buildRemoteDockerCommands(imageRef, containerName, {}, { publishPort: port });
+    // Current secret value (not the old build's). Rollback re-delivers this too —
+    // managed .env is not versioned per buildId.
+    const envContent = readManagedEnvFileContent(effectiveEnv, settings);
+    const envFilePath =
+      envContent != null ? resolveDockerManagedEnvRemotePath(config, envName) : undefined;
+    const cmds = buildRemoteDockerCommands(imageRef, containerName, {}, {
+      publishPort: port,
+      envFile: envFilePath,
+    });
     const session = sshSession();
     let ssh = await session.connect();
     try {
@@ -184,6 +202,17 @@ export function createDockerProvider(config, envName, env = process.env) {
         );
       }
 
+      if (envContent != null && envFilePath) {
+        await uploadManagedEnvFile({
+          ssh,
+          session,
+          content: envContent,
+          remotePath: envFilePath,
+          user: sshTarget().user,
+          log,
+        });
+      }
+
       await session.exec(ssh, cmds.stop);
       await session.exec(ssh, cmds.rm);
       await session.exec(ssh, cmds.pull, {

package/src/deployment/providers/ssh.js

@@ -3,6 +3,11 @@ import { createLogger } from '../../logger/index.js';
 import { getEnvSettings } from '../../core/config.js';
 import { createSshExecSession } from '../ssh-connection.js';
 import { runDeployHooks } from '../hooks.js';
+import {
+  readManagedEnvFileContent,
+  resolveSshManagedEnvRemotePaths,
+  uploadManagedEnvFile,
+} from '../env-file.js';
 import {
   getNginxSitesAvailablePath,
   getNginxSitesEnabledPath,
@@ -253,9 +258,23 @@ export function createSshProvider(config, envName, env = process.env) {
     await assertPidAliveAfterStart(ssh, targetPath);
   }
 
+  /**
+   * After the framework's package-manager install (and any built-in migrate
+   * / artisan steps), before stop/start. Same stage name on rollback so
+   * codegen re-runs against the restored files. No-op when the env has no
+   * `postInstall` hooks.
+   *
+   * @param {import('node-ssh').NodeSSH} ssh
+   * @returns {Promise<import('node-ssh').NodeSSH>}
+   */
+  async function runPostInstallHooks(ssh) {
+    return runDeployHooks({ session, ssh, settings, stage: 'postInstall' });
+  }
+
   /**
    * @param {import('node-ssh').NodeSSH} ssh
    * @param {string} targetPath
+   * @returns {Promise<import('node-ssh').NodeSSH>} possibly replaced after postInstall reconnect
    */
   async function runBackendStartSequence(ssh, targetPath) {
     const framework = resolveFramework();
@@ -265,6 +284,7 @@ export function createSshProvider(config, envName, env = process.env) {
 
     if (NODE_FRAMEWORKS.has(framework)) {
       await exec(ssh, `cd ${dir} && npm install --production`);
+      ssh = await runPostInstallHooks(ssh);
       const start = startCommand || 'npm start';
       if (start === 'npm start') {
         await exec(
@@ -285,7 +305,7 @@ export function createSshProvider(config, envName, env = process.env) {
         );
       }
       await exec(ssh, 'pm2 save');
-      return;
+      return ssh;
     }
 
     if (PYTHON_FRAMEWORKS.has(framework)) {
@@ -293,6 +313,7 @@ export function createSshProvider(config, envName, env = process.env) {
       if (framework === 'django') {
         await exec(ssh, `cd ${dir} && python manage.py migrate`);
       }
+      ssh = await runPostInstallHooks(ssh);
       await stopScopedBackendProcess(ssh, targetPath);
       if (framework === 'fastapi') {
         await startScopedNohup(
@@ -318,7 +339,7 @@ export function createSshProvider(config, envName, env = process.env) {
         );
         await assertPidAliveAfterStart(ssh, targetPath, logFile);
       }
-      return;
+      return ssh;
     }
 
     if (PHP_FRAMEWORKS.has(framework)) {
@@ -338,14 +359,17 @@ export function createSshProvider(config, envName, env = process.env) {
         await exec(ssh, `cd ${dir} && php artisan config:cache`);
       }
 
+      ssh = await runPostInstallHooks(ssh);
+
       const fpmUnit = await resolveRemotePhpFpmUnit(ssh, phpVersion);
       log.info(`Restarting PHP-FPM service: ${fpmUnit}`);
       await exec(ssh, `sudo systemctl restart ${sh(fpmUnit)}`);
       await reloadNginx(ssh);
-      return;
+      return ssh;
     }
 
     if (framework === 'spring' || framework === 'java') {
+      ssh = await runPostInstallHooks(ssh);
       await stopScopedBackendProcess(ssh, targetPath);
       // -Ddeployhub.app= embeds the env-scoped identity in the JVM command line
       // so cmdline marker scans and the PID file both target only this env.
@@ -354,18 +378,20 @@ export function createSshProvider(config, envName, env = process.env) {
         targetPath,
         `java -Ddeployhub.app=${appName} -jar target/*.jar`
       );
-      return;
+      return ssh;
     }
 
     if (framework === 'go') {
+      ssh = await runPostInstallHooks(ssh);
       await stopScopedBackendProcess(ssh, targetPath);
       // Binary is always ./bin/app — must NOT pkill by appName alone (that never
       // matched the process) and must NOT pkill a bare "app" (cross-env collision).
       await startScopedNohup(ssh, targetPath, './bin/app');
-      return;
+      return ssh;
     }
 
     if (framework === 'dotnet') {
+      ssh = await runPostInstallHooks(ssh);
       await stopScopedBackendProcess(ssh, targetPath);
       // Discover the published DLL at runtime — csproj name is not always App.dll
       // (same class of bug as the Docker CMD ["dotnet","App.dll"] hardcode).
@@ -374,22 +400,25 @@ export function createSshProvider(config, envName, env = process.env) {
         targetPath,
         `sh -c 'dll=$(ls -1 *.dll 2>/dev/null | head -n1); test -n "$dll" || { echo "No .dll found in $(pwd) for .NET start" >&2; exit 1; }; exec dotnet "$dll"'`
       );
-      return;
+      return ssh;
     }
 
     if (framework === 'rails' || framework === 'ruby') {
       await exec(ssh, `cd ${dir} && bundle install --deployment`);
+      ssh = await runPostInstallHooks(ssh);
       await stopScopedBackendProcess(ssh, targetPath);
       await startScopedNohup(ssh, targetPath, `bundle exec puma -b tcp://0.0.0.0:${port}`);
-      return;
+      return ssh;
     }
 
     await exec(ssh, `cd ${dir} && npm install --production`);
+    ssh = await runPostInstallHooks(ssh);
     await exec(
       ssh,
       `cd ${dir} && pm2 restart ${sh(appName)} || pm2 start npm --name ${sh(appName)} -- start`
     );
     await exec(ssh, 'pm2 save');
+    return ssh;
   }
 
   /**
@@ -539,6 +568,33 @@ export function createSshProvider(config, envName, env = process.env) {
     await exec(ssh, `unzip -o ${sh(remoteZip)} -d ${sh(targetPath)}`);
   }
 
+  /**
+   * DeployHub-managed .env: SFTP the current GitHub Secret onto the target.
+   * Overwrites every deploy, including rollback — .env is the current secret,
+   * not versioned per buildId. Runs after unzip/rsync and before
+   * runBackendStartSequence (install → postInstall → start), so a postInstall
+   * hook can `cd {deployPath} && set -a && . ./.env && set +a && prisma generate`.
+   * No-op when envFileSecretName is unset (hand-placed .env then survives
+   * unzip -o, same as before).
+   *
+   * @param {import('node-ssh').NodeSSH} ssh
+   */
+  async function uploadManagedEnvIfConfigured(ssh) {
+    const content = readManagedEnvFileContent(env, settings);
+    if (content == null) return;
+    const paths = resolveSshManagedEnvRemotePaths(config, settings);
+    for (const remotePath of paths) {
+      await uploadManagedEnvFile({
+        ssh,
+        session,
+        content,
+        remotePath,
+        user,
+        log,
+      });
+    }
+  }
+
   /**
    * @param {string} artifactDir
    * @param {{ isRollback?: boolean }} [options]
@@ -546,6 +602,9 @@ export function createSshProvider(config, envName, env = process.env) {
   async function deploy(artifactDir, options = {}) {
     const isRollback = options.isRollback === true;
     const preStage = isRollback ? 'rollback' : 'preDeploy';
+    // Fail fast (before SSH): GitHub Actions injects "" when the secret was
+    // never added or the name is misspelled. Must not unzip then write empty .env.
+    readManagedEnvFileContent(env, settings);
     let ssh = await connect();
     const projectType = config.projectType || 'frontend';
 
@@ -577,11 +636,13 @@ export function createSshProvider(config, envName, env = process.env) {
             `rsync -a ${sh(remoteStaging)}/backend/ ${sh(backendDeployPath)}/ || cp -r ${sh(remoteStaging)}/backend/* ${sh(backendDeployPath)}/`
           );
 
+          await uploadManagedEnvIfConfigured(ssh);
+
           if (await remoteFileExists(ssh, `${frontendDeployPath}/nginx.conf`)) {
             await setupNginx(ssh, frontendDeployPath);
           }
 
-          await runBackendStartSequence(ssh, backendDeployPath);
+          ssh = await runBackendStartSequence(ssh, backendDeployPath);
         } finally {
           await exec(ssh, `rm -rf ${sh(remoteStaging)}`).catch(() => {});
         }
@@ -589,15 +650,17 @@ export function createSshProvider(config, envName, env = process.env) {
         log.info(`Backend deploy path: ${deployPath}`);
         ssh = await runDeployHooks({ session, ssh, settings, stage: preStage });
         await extractToPath(ssh, remoteZip, deployPath);
-        await runBackendStartSequence(ssh, deployPath);
+        await uploadManagedEnvIfConfigured(ssh);
+        ssh = await runBackendStartSequence(ssh, deployPath);
       } else {
         log.info(`Frontend deploy path: ${deployPath}`);
         ssh = await runDeployHooks({ session, ssh, settings, stage: preStage });
         await extractToPath(ssh, remoteZip, deployPath);
+        await uploadManagedEnvIfConfigured(ssh);
 
         const framework = config.framework || 'react';
         if (framework === 'nextjs') {
-          await runBackendStartSequence(ssh, deployPath);
+          ssh = await runBackendStartSequence(ssh, deployPath);
         } else if (await remoteFileExists(ssh, `${deployPath}/nginx.conf`)) {
           await setupNginx(ssh, deployPath);
         }

package/src/utils/docker-remote.js

@@ -178,7 +178,7 @@ export async function probeRemoteDockerPs(target) {
  * @param {string} imageRef
  * @param {string} containerName
  * @param {Record<string, string>} [runEnv]
- * @param {{ publishPort?: number|null }} [options]
+ * @param {{ publishPort?: number|null, envFile?: string }} [options]
  */
 export function buildRemoteDockerCommands(imageRef, containerName, runEnv = {}, options = {}) {
   const image = shellQuote(imageRef);
@@ -192,12 +192,17 @@ export function buildRemoteDockerCommands(imageRef, containerName, runEnv = {},
   const publishPort = options.publishPort;
   const pFlag =
     publishPort != null ? `-p ${shellQuote(`${publishPort}:${publishPort}`)} ` : '';
+  const envFile = options.envFile;
+  const envFileFlag =
+    envFile != null && String(envFile).trim()
+      ? `--env-file ${shellQuote(String(envFile).trim())} `
+      : '';
 
   return {
     stop: `docker stop ${name} 2>/dev/null || true`,
     rm: `docker rm -f ${name} 2>/dev/null || true`,
     pull: `docker pull ${image}`,
-    run: `docker run -d --rm --name ${name} ${pFlag}${envArg}${image}`,
+    run: `docker run -d --rm --name ${name} ${pFlag}${envFileFlag}${envArg}${image}`,
     ps: `docker ps --filter ${shellQuote(`name=^/${containerName}$`)} --format ${shellQuote('{{.Status}}')}`,
     info: 'docker info',
     /**