@akash-chowdhury-24/deployhub 2.0.41 → 2.0.44

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,12 +202,40 @@ 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, {
         timeoutMs: Math.max(session.defaultExecTimeoutMs, 300_000),
       });
-      await session.exec(ssh, cmds.run);
+      // `docker rm -f` can return before the name is fully released on a
+      // contended dockerd (`--rm` + stop). Re-rm immediately before run and
+      // retry name conflicts instead of failing a good deploy.
+      let lastRunErr;
+      for (let attempt = 1; attempt <= 3; attempt++) {
+        await session.exec(ssh, cmds.rm);
+        try {
+          await session.exec(ssh, cmds.run);
+          lastRunErr = null;
+          break;
+        } catch (err) {
+          lastRunErr = err;
+          const msg = err instanceof Error ? err.message : String(err);
+          if (!/already in use|Conflict/i.test(msg) || attempt === 3) throw err;
+          await new Promise((r) => setTimeout(r, 1000 * attempt));
+        }
+      }
+      if (lastRunErr) throw lastRunErr;
       const inspected = await session.execUnchecked(
         ssh,
         buildDockerInspectPortsCommand(containerName)