@akash-chowdhury-24/deployhub 2.0.41 → 2.0.44

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,7 +932,7 @@ 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. Keep secrets out of the zip. Docker-SSH is container-based and does not use this directory extract.
+**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:
 
@@ -855,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
@@ -906,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?**
 
@@ -922,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)
@@ -1177,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 |
@@ -1225,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
 
@@ -1280,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.41",
+  "version": "2.0.44",
   "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;
 }