@akash-chowdhury-24/deployhub 2.0.6 → 2.0.8

package/package.json

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

package/src/commands/doctor.js

@@ -19,6 +19,7 @@ import {
   formatDeployPathWriteFailure,
 } from '../utils/shell-quote.js';
 import { formatPasswordlessSudoGuidance } from '../utils/nginx.js';
+import { checkImagePullability } from '../utils/docker-image-deploy.js';
 
 /**
  * @typedef {{ name: string, pass: boolean, message: string }} CheckResult
@@ -410,6 +411,30 @@ async function runDeploymentChecks(config, envName, envConfig) {
         }
       })
     );
+
+    checks.push(
+      await runCheck('Container image pullable', async () => {
+        const result = await checkImagePullability(config, process.env);
+        return {
+          name: 'Container image pullable',
+          pass: result.ok,
+          message: result.message,
+        };
+      })
+    );
+  }
+
+  if (deployType === 'docker' && process.env.DOCKER_REGISTRY_USERNAME && process.env.DOCKER_REGISTRY_TOKEN) {
+    checks.push(
+      await runCheck('Container image pullable', async () => {
+        const result = await checkImagePullability(config, process.env);
+        return {
+          name: 'Container image pullable',
+          pass: result.ok,
+          message: result.message,
+        };
+      })
+    );
   }
 
   if (deployType === 'ec2' && process.env.EC2_INSTANCE_ID) {

package/src/commands/init.js

@@ -13,7 +13,7 @@ import {
 import { getProjectVersion } from '../utils/version.js';
 import {
   writeWorkflowFile,
-  getRequiredSecrets,
+  getGithubSecretsChecklist,
   generateEnvExampleContent,
   addDeployhubToPackageJson,
   DEFAULT_NPM_CLI_SOURCE,
@@ -30,7 +30,10 @@ import {
   getDockerEnvSecrets,
   SSH_BASED,
 } from '../deployment/init-prompts.js';
-import { printDeploymentNextSteps } from '../deployment/deployment-env.js';
+import {
+  printDeploymentNextSteps,
+  formatSecretChecklistLine,
+} from '../deployment/deployment-env.js';
 import { confirmValueIfContainsSpaces } from '../deployment/init-helpers.js';
 
 const FRONTEND_CHOICES = [
@@ -498,23 +501,34 @@ export function registerInitCommand(program) {
       );
       await fs.writeFile(envExampleDest, envExampleContent);
 
-      const secrets = getRequiredSecrets(config.storage, deploy, environments, config);
+      const secretsChecklist = getGithubSecretsChecklist(
+        config.storage,
+        deploy,
+        environments,
+        config
+      );
 
       console.log('');
       if (primaryDeployType) {
         console.log(chalk.green.bold(`✔ Config generated for ${primaryDeployType} deployment.`));
-        printDeploymentNextSteps(primaryDeployType, secrets);
+        printDeploymentNextSteps(primaryDeployType, secretsChecklist);
       } else {
         console.log(chalk.green.bold('✓ DeployHub initialized successfully!'));
         console.log('');
         console.log(chalk.bold('Next steps:'));
         console.log('  1. Copy .env.example to .env and fill in credentials');
-        if (secrets.length > 0) {
+        if (secretsChecklist.length > 0) {
           console.log('  2. Add these secrets to GitHub (Settings → Secrets):');
-          secrets.forEach((s) => console.log(`     • ${s}`));
+          secretsChecklist.forEach((item) =>
+            console.log(`     ${formatSecretChecklistLine(item)}`)
+          );
         }
-        console.log(`  ${secrets.length > 0 ? '3' : '2'}. Run ${chalk.cyan('deployhub doctor')} to verify your setup`);
-        console.log(`  ${secrets.length > 0 ? '4' : '3'}. Push to main — GitHub Actions will run ${chalk.cyan('deployhub build')} automatically`);
+        console.log(
+          `  ${secretsChecklist.length > 0 ? '3' : '2'}. Run ${chalk.cyan('deployhub doctor')} to verify your setup`
+        );
+        console.log(
+          `  ${secretsChecklist.length > 0 ? '4' : '3'}. Push to main — GitHub Actions will run ${chalk.cyan('deployhub build')} automatically`
+        );
       }
 
       console.log('');

package/src/deployment/deployment-env.js

@@ -316,12 +316,11 @@ export const DEPLOYMENT_ENV_DEFS = {
     },
     {
       key: 'DOCKER_IMAGE_NAME',
-      optionalReason: 'only required if your manifests need an image override at deploy time',
       comment: [
-        'Container image to deploy (must match manifests or be overridden).',
+        'Container image to build, push, and deploy.',
+        'Kubernetes clusters pull from a registry — local-only Docker images will not work.',
       ],
       example: 'ghcr.io/myorg/myapp',
-      when: 'optional',
     },
     {
       key: 'DOCKER_IMAGE_TAG',
@@ -332,6 +331,30 @@ export const DEPLOYMENT_ENV_DEFS = {
       example: 'latest',
       when: 'optional',
     },
+    {
+      key: 'DOCKER_REGISTRY_URL',
+      optionalReason: 'leave empty for Docker Hub',
+      comment: [
+        'Container registry URL. Leave empty for Docker Hub.',
+        'Examples: https://index.docker.io/v1/ | https://ghcr.io',
+      ],
+      when: 'optional',
+    },
+    {
+      key: 'DOCKER_REGISTRY_USERNAME',
+      comment: [
+        'Registry username — required to push so the cluster can pull your image.',
+        'Even public Docker Hub repos require authentication to push.',
+      ],
+      example: 'myuser',
+    },
+    {
+      key: 'DOCKER_REGISTRY_TOKEN',
+      comment: [
+        'Registry password or personal access token — required to push so the cluster can pull.',
+        'Docker Hub: access token. GHCR: GitHub PAT with write:packages.',
+      ],
+    },
     {
       key: 'KUBE_IMAGE_PULL_SECRET',
       optionalReason: 'only required when pulling from a private container registry',
@@ -353,6 +376,8 @@ export const DEPLOYMENT_ENV_KEYS = Object.fromEntries(
 );
 
 /**
+ * Locally required env keys for doctor method-specific checks.
+ * Excludes optional and CI-only vars.
  * @param {string} deployType
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {string[]}
@@ -373,7 +398,16 @@ export function getDeploymentEnvKeys(deployType, config = null) {
 }
 
 /**
- * Required secrets for GitHub Actions (includes CI-only vars like SSH_KEY).
+ * Map a def key to the GitHub Actions secret name (SSH_KEY_PATH → SSH_KEY).
+ * @param {string} key
+ */
+function toGithubSecretKey(key) {
+  return key === 'SSH_KEY_PATH' ? 'SSH_KEY' : key;
+}
+
+/**
+ * Genuinely required secrets for doctor "Secrets" check and required checklist items.
+ * Includes CI-only vars (e.g. SSH_KEY) but NOT optional vars.
  * @param {string} deployType
  * @param {import('../core/config.js').DeployHubConfig} [config]
  * @returns {string[]}
@@ -388,22 +422,93 @@ export function getDeploymentSecretKeys(deployType, config = null) {
 
   for (const d of defs) {
     if (d.when === 'backend' && !isBackend) continue;
-    // Docker optional vars must still appear in CI workflow/secrets checklist —
-    // empty secrets are fine when unused; missing DOCKER_IMAGE_NAME is not.
-    if (d.when === 'optional') {
-      if (deployType === 'docker' && d.key.startsWith('DOCKER_')) {
-        keys.push(d.key);
+    if (d.when === 'optional') continue;
+    keys.push(toGithubSecretKey(d.key));
+  }
+
+  return [...new Set(keys)];
+}
+
+/**
+ * Broad CI-wiring list for the GitHub Actions workflow generator.
+ * Includes required, CI-only, and optional keys so `${{ secrets.X }}` is
+ * available when the user sets optional secrets — empty secrets are fine.
+ * @param {string} deployType
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @returns {string[]}
+ */
+export function getDeploymentWorkflowSecretKeys(deployType, config = null) {
+  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+  const projectType = config?.projectType || 'frontend';
+  const isBackend = projectType === 'backend' || projectType === 'both';
+
+  /** @type {string[]} */
+  const keys = [];
+
+  for (const d of defs) {
+    if (d.when === 'backend' && !isBackend) continue;
+    keys.push(toGithubSecretKey(d.key));
+  }
+
+  return [...new Set(keys)];
+}
+
+/**
+ * @typedef {{ key: string, required: boolean, note?: string }} SecretChecklistItem
+ */
+
+/**
+ * Labeled GitHub Secrets checklist entries for a single deploy method.
+ * @param {string} deployType
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @returns {SecretChecklistItem[]}
+ */
+export function getDeploymentSecretChecklistItems(deployType, config = null) {
+  const defs = DEPLOYMENT_ENV_DEFS[deployType] || [];
+  const projectType = config?.projectType || 'frontend';
+  const isBackend = projectType === 'backend' || projectType === 'both';
+
+  /** @type {Map<string, SecretChecklistItem>} */
+  const byKey = new Map();
+
+  for (const d of defs) {
+    if (d.when === 'backend' && !isBackend) continue;
+
+    const key = toGithubSecretKey(d.key);
+    const required = d.when !== 'optional';
+    const note =
+      d.when === 'optional'
+        ? d.optionalReason
+        : d.when === 'ci'
+          ? d.optionalReason || 'required for GitHub Actions CI (paste private key contents)'
+          : undefined;
+
+    const existing = byKey.get(key);
+    if (existing) {
+      // Prefer required if any def for this key is required
+      if (required && !existing.required) {
+        byKey.set(key, { key, required: true, note });
       }
       continue;
     }
-    if (d.key === 'SSH_KEY_PATH') {
-      keys.push('SSH_KEY');
-      continue;
-    }
-    keys.push(d.key);
+
+    byKey.set(key, { key, required, note });
   }
 
-  return keys;
+  return Array.from(byKey.values());
+}
+
+/**
+ * Format a checklist item for console output.
+ * @param {SecretChecklistItem} item
+ */
+export function formatSecretChecklistLine(item) {
+  if (item.required) {
+    const note = item.note ? ` — ${item.note}` : '';
+    return `• ${item.key} (required${note})`;
+  }
+  const note = item.note ? ` — ${item.note}` : '';
+  return `• ${item.key} (optional${note})`;
 }
 
 /**
@@ -449,6 +554,7 @@ export function generateDeploymentEnvSection(
   return lines.join('\n').trimEnd();
 }
 
+
 /**
  * @param {string} key
  * @param {import('../core/config.js').DeployHubConfig} [config]
@@ -527,8 +633,7 @@ export const DEPLOYMENT_GUIDE = {
       'Copy .env.example to .env and set DOCKER_IMAGE_NAME (required — e.g. myuser/myapp).',
       'Optional in .env: DOCKER_IMAGE_TAG, DOCKER_REGISTRY_URL, DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH.',
       'If using a private registry: also set DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN.',
-      'Add GitHub Secrets (Settings → Secrets and variables → Actions): DOCKER_IMAGE_NAME (required). Local .env is NOT used by GitHub Actions — doctor only checks your machine.',
-      'Also add as GitHub Secrets if set locally: DOCKER_IMAGE_TAG, DOCKER_REGISTRY_URL, DOCKER_REGISTRY_USERNAME, DOCKER_REGISTRY_TOKEN, DOCKER_HOST, DOCKER_TLS_VERIFY, DOCKER_CERT_PATH.',
+      'Add the GitHub Secrets listed below (Settings → Secrets and variables → Actions). Local .env is NOT used by GitHub Actions — doctor only checks your machine.',
       'Run deployhub doctor to verify Docker is reachable.',
       'git push origin main to trigger your first deployment.',
     ],
@@ -601,30 +706,36 @@ export const DEPLOYMENT_GUIDE = {
     before: [
       'An existing Kubernetes cluster (DeployHub does not provision clusters).',
       'kubectl installed and configured (kubectl cluster-info works).',
+      'A container registry account — clusters pull images from a registry, not your local Docker daemon.',
+      'Registry credentials (username + token) to push your image so the cluster can pull it.',
       'Kubernetes manifests (Deployment, Service, etc.) in your repo or artifact.',
       'Cluster access from CI: kubeconfig or cloud-specific auth for GitHub Actions.',
     ],
     automates: [
       'Lists available kubectl contexts during init so you pick from a menu.',
       'Auto-detects ~/.kube/config if present.',
-      'Generates complete .env.example for kubeconfig, context, and namespace.',
+      'Generates complete .env.example for kubeconfig, context, namespace, and registry settings.',
       'Tests cluster connectivity during init.',
+      'Builds and pushes your container image during deployhub build/deploy (pipeline docker stage).',
     ],
     after: [
       'Ensure your kubeconfig context points to the correct cluster.',
       'Create namespace if needed: kubectl create namespace YOUR_NAMESPACE',
-      'For private registries: kubectl create secret docker-registry ... and set KUBE_IMAGE_PULL_SECRET.',
-      'Copy .env.example to .env; add KUBECONFIG contents or auth secrets to GitHub Actions.',
-      'Run deployhub doctor, then git push origin main.',
+      'Copy .env.example to .env and set DOCKER_IMAGE_NAME, DOCKER_REGISTRY_USERNAME, and DOCKER_REGISTRY_TOKEN.',
+      'Skipping registry credentials will very likely cause ImagePullBackOff — the cluster cannot see local Docker images.',
+      'For private registries: also create kubectl create secret docker-registry ... and set KUBE_IMAGE_PULL_SECRET.',
+      'Add the GitHub Secrets listed below (Settings → Secrets and variables → Actions).',
+      'Run deployhub doctor to verify cluster access and that your image is pullable.',
+      'git push origin main to trigger your first deployment.',
     ],
   },
 };
 
 /**
  * @param {string} deployType
- * @param {string[]} [extraSecrets]
+ * @param {SecretChecklistItem[]} [checklist]
  */
-export function printDeploymentNextSteps(deployType, extraSecrets = []) {
+export function printDeploymentNextSteps(deployType, checklist = []) {
   const guide = DEPLOYMENT_GUIDE[deployType];
   if (!guide) return;
 
@@ -635,10 +746,10 @@ export function printDeploymentNextSteps(deployType, extraSecrets = []) {
     console.log(`    ${i + 1}. ${step}`);
   });
 
-  if (extraSecrets.length > 0) {
+  if (checklist.length > 0) {
     console.log('\n  GitHub Secrets to add (Settings → Secrets and variables → Actions):');
-    for (const s of extraSecrets) {
-      console.log(`    • ${s}`);
+    for (const item of checklist) {
+      console.log(`    ${formatSecretChecklistLine(item)}`);
     }
   }
 }

package/src/deployment/init-prompts.js

@@ -94,6 +94,23 @@ async function promptKubernetesDeployment(base, projectName, projectType) {
       message: 'Container image name (e.g. ghcr.io/myorg/myapp):',
       default: projectName,
     },
+    {
+      type: 'input',
+      name: 'dockerRegistryUrl',
+      message: 'Registry URL (leave empty for Docker Hub):',
+    },
+    {
+      type: 'input',
+      name: 'dockerRegistryUsername',
+      message:
+        'Registry username (required — needed to push your image so the cluster can pull it):',
+    },
+    {
+      type: 'password',
+      name: 'dockerRegistryToken',
+      message:
+        'Registry token/password (required — needed to push your image so the cluster can pull it):',
+    },
     {
       type: 'input',
       name: 'healthUrl',
@@ -115,6 +132,9 @@ async function promptKubernetesDeployment(base, projectName, projectType) {
     kubeContext: kubeAnswers.kubeContext,
     kubeNamespace: kubeAnswers.kubeNamespace,
     dockerImageName: kubeAnswers.dockerImageName,
+    dockerRegistryUrl: kubeAnswers.dockerRegistryUrl,
+    dockerRegistryUsername: kubeAnswers.dockerRegistryUsername,
+    dockerRegistryToken: kubeAnswers.dockerRegistryToken,
     healthUrl: kubeAnswers.healthUrl,
   };
 }
@@ -366,6 +386,7 @@ export function buildServerEnvEntry(
     envEntry.kubeContext = deployAnswers.kubeContext;
     envEntry.kubeNamespace = deployAnswers.kubeNamespace || projectName;
     envEntry.dockerImageName = deployAnswers.dockerImageName || projectName;
+    envEntry.dockerRegistryUrl = deployAnswers.dockerRegistryUrl || '';
     return envEntry;
   }
 
@@ -418,7 +439,7 @@ export function buildServerEnvEntry(
  * @returns {Record<string, string>|null}
  */
 export function getDockerEnvSecrets(deployAnswers) {
-  if (deployAnswers.deployType !== 'docker') return null;
+  if (!['docker', 'kubernetes'].includes(deployAnswers.deployType)) return null;
 
   /** @type {Record<string, string>} */
   const vars = {};

package/src/deployment/providers/docker.js

@@ -1,18 +1,6 @@
 import { execa } from 'execa';
-import fs from 'fs-extra';
-import path from 'path';
 import { createLogger } from '../../logger/index.js';
-import { extractArtifact } from '../../artifact/engine.js';
-import {
-  describeInterpretedBackendGap,
-  generateDotnetRuntimeDockerfile,
-  generateFrontendRuntimeDockerfile,
-  generateGoRuntimeDockerfile,
-  generateSpringRuntimeDockerfile,
-  isFrontendStaticFramework,
-  isInterpretedBackendFramework,
-  resolveDockerImageRef,
-} from '../../utils/docker-image.js';
+import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.js';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -21,277 +9,8 @@ import {
  */
 export function createDockerProvider(config, envName, env = process.env) {
   const log = createLogger('docker');
-
-  const { fullImage, latestImage, legacyLatestImage, imageTag } =
-    resolveDockerImageRef(config, env);
-  const registryUrl = env.DOCKER_REGISTRY_URL || '';
-  const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
-  const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
-  const dockerHost = env.DOCKER_HOST || '';
-
-  function getDockerEnv() {
-    /** @type {Record<string, string>} */
-    const dockerEnv = { ...process.env };
-    if (dockerHost) dockerEnv.DOCKER_HOST = dockerHost;
-    if (env.DOCKER_TLS_VERIFY) dockerEnv.DOCKER_TLS_VERIFY = env.DOCKER_TLS_VERIFY;
-    if (env.DOCKER_CERT_PATH) dockerEnv.DOCKER_CERT_PATH = env.DOCKER_CERT_PATH;
-    return dockerEnv;
-  }
-
-  function hasRegistryCredentials() {
-    return Boolean(registryUser && registryToken);
-  }
-
-  async function dockerLogin() {
-    if (!hasRegistryCredentials()) return;
-    const registry = registryUrl || 'https://index.docker.io/v1/';
-    log.info('Logging in to container registry...');
-    await execa(
-      'docker',
-      ['login', registry, '-u', registryUser, '--password-stdin'],
-      {
-        input: registryToken,
-        stdio: ['pipe', 'inherit', 'inherit'],
-        env: getDockerEnv(),
-      }
-    );
-  }
-
-  /**
-   * Push only when registry credentials are configured. Avoids a noisy failed
-   * push to Docker Hub for local-only image names.
-   */
-  async function maybePushImage() {
-    if (!hasRegistryCredentials()) {
-      log.info(
-        'docker push skipped (DOCKER_REGISTRY_USERNAME/TOKEN not set — local image only)'
-      );
-      return;
-    }
-
-    log.info(`Pushing ${fullImage} to registry...`);
-    await execa('docker', ['push', fullImage], {
-      stdio: 'inherit',
-      env: getDockerEnv(),
-    });
-    log.success(`Pushed ${fullImage}`);
-  }
-
-  /**
-   * @param {string} ref
-   */
-  async function imageExists(ref) {
-    try {
-      await execa('docker', ['image', 'inspect', ref], {
-        stdio: 'pipe',
-        env: getDockerEnv(),
-      });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Prefer the image already built during the pipeline `docker` stage.
-   * Retag when the pipeline used `:latest` and deploy needs a version tag.
-   */
-  async function ensureImageFromPipeline() {
-    if (await imageExists(fullImage)) {
-      log.info(`Reusing existing image ${fullImage}`);
-      return true;
-    }
-
-    const candidates = [...new Set([latestImage, legacyLatestImage])].filter(
-      (ref) => ref !== fullImage
-    );
-
-    for (const candidate of candidates) {
-      if (!(await imageExists(candidate))) continue;
-      log.info(`Re-tagging pipeline image ${candidate} → ${fullImage}`);
-      await execa('docker', ['tag', candidate, fullImage], {
-        stdio: 'inherit',
-        env: getDockerEnv(),
-      });
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * Backend artifacts omit lockfiles/node_modules. Prefer a pre-built binary
-   * runtime image when present; otherwise fail with an actionable error.
-   * @param {string} buildContext
-   * @param {Record<string, unknown>} metadata
-   * @param {string} framework
-   * @param {number} port
-   */
-  async function prepareBackendBuildContext(buildContext, metadata, framework, port) {
-    if (framework === 'spring') {
-      const targetDir = path.join(buildContext, 'target');
-      if (await fs.pathExists(targetDir)) {
-        const jars = (await fs.readdir(targetDir)).filter((f) => f.endsWith('.jar'));
-        if (jars.length > 0) {
-          const jarRel = `target/${jars[0]}`;
-          log.info(`Building runtime image from pre-built JAR (${jarRel})...`);
-          await fs.writeFile(
-            path.join(buildContext, 'Dockerfile'),
-            generateSpringRuntimeDockerfile(jarRel, port)
-          );
-          return;
-        }
-      }
-    }
-
-    if (framework === 'go') {
-      const binDir = path.join(buildContext, 'bin');
-      if (await fs.pathExists(binDir)) {
-        const bins = await fs.readdir(binDir);
-        if (bins.length > 0) {
-          const binRel = `bin/${bins[0]}`;
-          log.info(`Building runtime image from pre-built Go binary (${binRel})...`);
-          await fs.writeFile(
-            path.join(buildContext, 'Dockerfile'),
-            generateGoRuntimeDockerfile(binRel, port)
-          );
-          return;
-        }
-      }
-    }
-
-    if (framework === 'dotnet') {
-      const publishDir =
-        /** @type {string} */ (metadata.buildOutput) ||
-        config.buildOutput ||
-        'publish';
-      const publishPath = path.join(buildContext, publishDir);
-      if (await fs.pathExists(publishPath)) {
-        log.info(`Building runtime image from pre-built .NET output (${publishDir}/)...`);
-        await fs.writeFile(
-          path.join(buildContext, 'Dockerfile'),
-          generateDotnetRuntimeDockerfile(publishDir, port)
-        );
-        return;
-      }
-    }
-
-    const dockerfilePath = path.join(buildContext, 'Dockerfile');
-    if (!(await fs.pathExists(dockerfilePath))) {
-      throw new Error(
-        'No Dockerfile found in artifact and no pipeline image to reuse. ' +
-          'Add a Dockerfile and enable pipeline.docker so the image is built from project source.'
-      );
-    }
-
-    // Interpreted backends (Node/Python/PHP/Ruby): never rebuild from artifact.
-    // Artifacts ship source + manifest files, not installed dependency trees.
-    if (isInterpretedBackendFramework(framework)) {
-      const gap = describeInterpretedBackendGap(framework);
-      throw new Error(
-        `Cannot rebuild ${gap.ecosystem} backend image "${fullImage}" from the packaged artifact.\n` +
-          `Backend artifacts include source/manifests but not ${gap.missing}, ` +
-          `so Dockerfiles that run \`${gap.installCmd}\` cannot reliably succeed from the artifact alone.\n\n` +
-          'What to do instead:\n' +
-          '  1. Enable pipeline.docker in deployhub.config.json (default when Docker deploy is selected).\n' +
-          '  2. Run a full `deployhub build` so the image is built from the project root (with full deps).\n' +
-          '  3. Deploy will reuse that local image (retag/push/run) — it will not rebuild from the artifact.\n\n' +
-          `Standalone \`deployhub deploy\` without a pre-built local image is not supported for ${gap.ecosystem} backends.`
-      );
-    }
-
-    // Remaining backends (unknown frameworks): try the packaged Dockerfile, but warn.
-    log.warn(
-      'Building backend image from extracted artifact. Prefer pipeline.docker so the image ' +
-        'is built once from full project source, then reused on deploy.'
-    );
-  }
-
-  /**
-   * Standalone deploy fallback: extract the packaged artifact and build a
-   * runtime image from pre-built output (frontend) or compiled backend artifacts.
-   * Never builds from artifactDir root — that only has zip/metadata + a source Dockerfile.
-   * @param {string} artifactDir
-   */
-  async function buildFromArtifactContents(artifactDir) {
-    const zipPath = path.join(artifactDir, 'artifact.zip');
-    if (!(await fs.pathExists(zipPath))) {
-      throw new Error(
-        `No local image found for ${fullImage} and no artifact.zip to build from. ` +
-          'Enable pipeline.docker so the image is built from project source, or run deployhub build first.'
-      );
-    }
-
-    const buildContext = path.join(artifactDir, '_docker_build');
-    await fs.remove(buildContext);
-    await extractArtifact(artifactDir, buildContext);
-
-    try {
-      const metadataPath = path.join(buildContext, 'metadata.json');
-      const metadata = (await fs.pathExists(metadataPath))
-        ? await fs.readJson(metadataPath)
-        : {};
-
-      const projectType = metadata.projectType || config.projectType || 'frontend';
-      const framework =
-        metadata.framework ||
-        config.framework ||
-        config.frontend?.framework ||
-        '';
-      const buildOutput =
-        metadata.buildOutput ||
-        config.buildOutput ||
-        config.frontend?.buildOutput ||
-        'dist';
-      const port =
-        Number(metadata.port) ||
-        config.port ||
-        config.backend?.port ||
-        3000;
-
-      const composePath = path.join(buildContext, 'docker-compose.yml');
-      if (await fs.pathExists(composePath)) {
-        log.info('Building via docker compose from extracted artifact...');
-        await execa('docker', ['compose', 'up', '-d', '--build'], {
-          cwd: buildContext,
-          stdio: 'inherit',
-          env: getDockerEnv(),
-        });
-        return { ranCompose: true };
-      }
-
-      const isStaticFrontend =
-        projectType === 'frontend' || isFrontendStaticFramework(framework);
-
-      if (isStaticFrontend) {
-        const outputDir = path.join(buildContext, buildOutput);
-        if (!(await fs.pathExists(outputDir))) {
-          throw new Error(
-            `Frontend artifact is missing build output "${buildOutput}". ` +
-              'Cannot build a runtime image from this artifact.'
-          );
-        }
-        log.info(
-          `Building runtime image from pre-built ${buildOutput}/ (no source rebuild)...`
-        );
-        await fs.writeFile(
-          path.join(buildContext, 'Dockerfile'),
-          generateFrontendRuntimeDockerfile(buildOutput)
-        );
-      } else {
-        await prepareBackendBuildContext(buildContext, metadata, framework, port);
-      }
-
-      await execa('docker', ['build', '-t', fullImage, '.'], {
-        cwd: buildContext,
-        stdio: 'inherit',
-        env: getDockerEnv(),
-      });
-      return { ranCompose: false };
-    } finally {
-      await fs.remove(buildContext).catch(() => {});
-    }
-  }
+  const imageOps = createDockerImageDeployContext(config, env, log);
+  const { fullImage, getDockerEnv, ensureImageReadyForDeploy } = imageOps;
 
   /**
    * @param {string} artifactDir
@@ -300,31 +19,12 @@ export function createDockerProvider(config, envName, env = process.env) {
     log.info(`Deploying via Docker (image: ${fullImage})...`);
     const dockerEnv = getDockerEnv();
 
-    await dockerLogin();
-
-    const reused = await ensureImageFromPipeline();
-    let ranCompose = false;
-
-    if (!reused) {
-      const result = await buildFromArtifactContents(artifactDir);
-      ranCompose = Boolean(result?.ranCompose);
-    }
-
-    if (ranCompose) {
+    const result = await ensureImageReadyForDeploy(artifactDir);
+    if (result.ranCompose) {
       log.success('Docker deployment complete');
       return;
     }
 
-    await maybePushImage();
-
-    // Keep :latest in sync when deploy uses a version tag
-    if (imageTag !== 'latest' && fullImage !== latestImage) {
-      await execa('docker', ['tag', fullImage, latestImage], {
-        stdio: 'pipe',
-        env: dockerEnv,
-      }).catch(() => {});
-    }
-
     await execa(
       'docker',
       ['rm', '-f', config.project],

package/src/deployment/providers/kubernetes.js

@@ -4,6 +4,7 @@ import path from 'path';
 import os from 'os';
 import { createLogger } from '../../logger/index.js';
 import { sanitizeK8sName } from '../../utils/kubernetes-manifests.js';
+import { createDockerImageDeployContext } from '../../utils/docker-image-deploy.js';
 
 /**
  * @param {import('../../core/config.js').DeployHubConfig} config
@@ -12,6 +13,7 @@ import { sanitizeK8sName } from '../../utils/kubernetes-manifests.js';
  */
 export function createKubernetesProvider(config, envName, env = process.env) {
   const log = createLogger('kubernetes');
+  const imageOps = createDockerImageDeployContext(config, env, log);
 
   const kubeconfig = env.KUBECONFIG || path.join(os.homedir(), '.kube', 'config');
   const context = env.KUBE_CONTEXT || '';
@@ -51,6 +53,14 @@ export function createKubernetesProvider(config, envName, env = process.env) {
       );
     }
 
+    log.info(`Ensuring container image ${imageOps.fullImage} is built and pushed before apply...`);
+    const imageResult = await imageOps.ensureImageReadyForDeploy(artifactDir);
+    if (imageResult.ranCompose) {
+      log.warn(
+        'docker compose was used — ensure the cluster can pull the resulting image from your registry.'
+      );
+    }
+
     const applyTarget = (await fs.pathExists(path.join(manifestDir, 'k8s')))
       ? path.join(manifestDir, 'k8s')
       : manifestDir;

package/src/utils/docker-image-deploy.js

@@ -0,0 +1,420 @@
+import { execa } from 'execa';
+import fs from 'fs-extra';
+import path from 'path';
+import { extractArtifact } from '../artifact/engine.js';
+import {
+  describeInterpretedBackendGap,
+  generateDotnetRuntimeDockerfile,
+  generateFrontendRuntimeDockerfile,
+  generateGoRuntimeDockerfile,
+  generateSpringRuntimeDockerfile,
+  isFrontendStaticFramework,
+  isInterpretedBackendFramework,
+  resolveDockerImageRef,
+} from './docker-image.js';
+
+/**
+ * Shared Docker image build, reuse, push, and pullability logic used by
+ * docker and kubernetes deploy providers.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {Record<string, string>} [env]
+ * @param {{ info: Function, warn: Function, success: Function }} log
+ */
+export function createDockerImageDeployContext(config, env = process.env, log) {
+  const { fullImage, latestImage, legacyLatestImage, imageTag } =
+    resolveDockerImageRef(config, env);
+  const registryUrl = env.DOCKER_REGISTRY_URL || '';
+  const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
+  const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
+  const dockerHost = env.DOCKER_HOST || '';
+
+  function getDockerEnv() {
+    /** @type {Record<string, string>} */
+    const dockerEnv = { ...process.env };
+    if (dockerHost) dockerEnv.DOCKER_HOST = dockerHost;
+    if (env.DOCKER_TLS_VERIFY) dockerEnv.DOCKER_TLS_VERIFY = env.DOCKER_TLS_VERIFY;
+    if (env.DOCKER_CERT_PATH) dockerEnv.DOCKER_CERT_PATH = env.DOCKER_CERT_PATH;
+    return dockerEnv;
+  }
+
+  function hasRegistryCredentials() {
+    return Boolean(registryUser && registryToken);
+  }
+
+  async function dockerLogin() {
+    if (!hasRegistryCredentials()) return;
+    const registry = registryUrl || 'https://index.docker.io/v1/';
+    log.info('Logging in to container registry...');
+    await execa(
+      'docker',
+      ['login', registry, '-u', registryUser, '--password-stdin'],
+      {
+        input: registryToken,
+        stdio: ['pipe', 'inherit', 'inherit'],
+        env: getDockerEnv(),
+      }
+    );
+  }
+
+  /**
+   * Push only when registry credentials are configured. Avoids a noisy failed
+   * push to Docker Hub for local-only image names.
+   */
+  async function maybePushImage() {
+    if (!hasRegistryCredentials()) {
+      log.info(
+        'docker push skipped (DOCKER_REGISTRY_USERNAME/TOKEN not set — local image only)'
+      );
+      return;
+    }
+
+    log.info(`Pushing ${fullImage} to registry...`);
+    await execa('docker', ['push', fullImage], {
+      stdio: 'inherit',
+      env: getDockerEnv(),
+    });
+    log.success(`Pushed ${fullImage}`);
+  }
+
+  /**
+   * @param {string} ref
+   */
+  async function imageExistsLocally(ref) {
+    try {
+      await execa('docker', ['image', 'inspect', ref], {
+        stdio: 'pipe',
+        env: getDockerEnv(),
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Prefer the image already built during the pipeline `docker` stage.
+   * Retag when the pipeline used `:latest` and deploy needs a version tag.
+   */
+  async function ensureImageFromPipeline() {
+    if (await imageExistsLocally(fullImage)) {
+      log.info(`Reusing existing image ${fullImage}`);
+      return true;
+    }
+
+    const candidates = [...new Set([latestImage, legacyLatestImage])].filter(
+      (ref) => ref !== fullImage
+    );
+
+    for (const candidate of candidates) {
+      if (!(await imageExistsLocally(candidate))) continue;
+      log.info(`Re-tagging pipeline image ${candidate} → ${fullImage}`);
+      await execa('docker', ['tag', candidate, fullImage], {
+        stdio: 'inherit',
+        env: getDockerEnv(),
+      });
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * @param {string} buildContext
+   * @param {Record<string, unknown>} metadata
+   * @param {string} framework
+   * @param {number} port
+   */
+  async function prepareBackendBuildContext(buildContext, metadata, framework, port) {
+    if (framework === 'spring') {
+      const targetDir = path.join(buildContext, 'target');
+      if (await fs.pathExists(targetDir)) {
+        const jars = (await fs.readdir(targetDir)).filter((f) => f.endsWith('.jar'));
+        if (jars.length > 0) {
+          const jarRel = `target/${jars[0]}`;
+          log.info(`Building runtime image from pre-built JAR (${jarRel})...`);
+          await fs.writeFile(
+            path.join(buildContext, 'Dockerfile'),
+            generateSpringRuntimeDockerfile(jarRel, port)
+          );
+          return;
+        }
+      }
+    }
+
+    if (framework === 'go') {
+      const binDir = path.join(buildContext, 'bin');
+      if (await fs.pathExists(binDir)) {
+        const bins = await fs.readdir(binDir);
+        if (bins.length > 0) {
+          const binRel = `bin/${bins[0]}`;
+          log.info(`Building runtime image from pre-built Go binary (${binRel})...`);
+          await fs.writeFile(
+            path.join(buildContext, 'Dockerfile'),
+            generateGoRuntimeDockerfile(binRel, port)
+          );
+          return;
+        }
+      }
+    }
+
+    if (framework === 'dotnet') {
+      const publishDir =
+        /** @type {string} */ (metadata.buildOutput) ||
+        config.buildOutput ||
+        'publish';
+      const publishPath = path.join(buildContext, publishDir);
+      if (await fs.pathExists(publishPath)) {
+        log.info(`Building runtime image from pre-built .NET output (${publishDir}/)...`);
+        await fs.writeFile(
+          path.join(buildContext, 'Dockerfile'),
+          generateDotnetRuntimeDockerfile(publishDir, port)
+        );
+        return;
+      }
+    }
+
+    const dockerfilePath = path.join(buildContext, 'Dockerfile');
+    if (!(await fs.pathExists(dockerfilePath))) {
+      throw new Error(
+        'No Dockerfile found in artifact and no pipeline image to reuse. ' +
+          'Add a Dockerfile and enable pipeline.docker so the image is built from project source.'
+      );
+    }
+
+    if (isInterpretedBackendFramework(framework)) {
+      const gap = describeInterpretedBackendGap(framework);
+      throw new Error(
+        `Cannot rebuild ${gap.ecosystem} backend image "${fullImage}" from the packaged artifact.\n` +
+          `Backend artifacts include source/manifests but not ${gap.missing}, ` +
+          `so Dockerfiles that run \`${gap.installCmd}\` cannot reliably succeed from the artifact alone.\n\n` +
+          'What to do instead:\n' +
+          '  1. Enable pipeline.docker in deployhub.config.json (default when Docker deploy is selected).\n' +
+          '  2. Run a full `deployhub build` so the image is built from the project root (with full deps).\n' +
+          '  3. Deploy will reuse that local image (retag/push/run) — it will not rebuild from the artifact.\n\n' +
+          `Standalone \`deployhub deploy\` without a pre-built local image is not supported for ${gap.ecosystem} backends.`
+      );
+    }
+
+    log.warn(
+      'Building backend image from extracted artifact. Prefer pipeline.docker so the image ' +
+        'is built once from full project source, then reused on deploy.'
+    );
+  }
+
+  /**
+   * @param {string} artifactDir
+   */
+  async function buildFromArtifactContents(artifactDir) {
+    const zipPath = path.join(artifactDir, 'artifact.zip');
+    if (!(await fs.pathExists(zipPath))) {
+      throw new Error(
+        `No local image found for ${fullImage} and no artifact.zip to build from. ` +
+          'Enable pipeline.docker so the image is built from project source, or run deployhub build first.'
+      );
+    }
+
+    const buildContext = path.join(artifactDir, '_docker_build');
+    await fs.remove(buildContext);
+    await extractArtifact(artifactDir, buildContext);
+
+    try {
+      const metadataPath = path.join(buildContext, 'metadata.json');
+      const metadata = (await fs.pathExists(metadataPath))
+        ? await fs.readJson(metadataPath)
+        : {};
+
+      const projectType = metadata.projectType || config.projectType || 'frontend';
+      const framework =
+        metadata.framework ||
+        config.framework ||
+        config.frontend?.framework ||
+        '';
+      const buildOutput =
+        metadata.buildOutput ||
+        config.buildOutput ||
+        config.frontend?.buildOutput ||
+        'dist';
+      const port =
+        Number(metadata.port) ||
+        config.port ||
+        config.backend?.port ||
+        3000;
+
+      const composePath = path.join(buildContext, 'docker-compose.yml');
+      if (await fs.pathExists(composePath)) {
+        log.info('Building via docker compose from extracted artifact...');
+        await execa('docker', ['compose', 'up', '-d', '--build'], {
+          cwd: buildContext,
+          stdio: 'inherit',
+          env: getDockerEnv(),
+        });
+        return { ranCompose: true };
+      }
+
+      const isStaticFrontend =
+        projectType === 'frontend' || isFrontendStaticFramework(framework);
+
+      if (isStaticFrontend) {
+        const outputDir = path.join(buildContext, buildOutput);
+        if (!(await fs.pathExists(outputDir))) {
+          throw new Error(
+            `Frontend artifact is missing build output "${buildOutput}". ` +
+              'Cannot build a runtime image from this artifact.'
+          );
+        }
+        log.info(
+          `Building runtime image from pre-built ${buildOutput}/ (no source rebuild)...`
+        );
+        await fs.writeFile(
+          path.join(buildContext, 'Dockerfile'),
+          generateFrontendRuntimeDockerfile(buildOutput)
+        );
+      } else {
+        await prepareBackendBuildContext(buildContext, metadata, framework, port);
+      }
+
+      await execa('docker', ['build', '-t', fullImage, '.'], {
+        cwd: buildContext,
+        stdio: 'inherit',
+        env: getDockerEnv(),
+      });
+      return { ranCompose: false };
+    } finally {
+      await fs.remove(buildContext).catch(() => {});
+    }
+  }
+
+  /**
+   * Ensure a deployable image exists locally, then push when credentials are set.
+   * @param {string} artifactDir
+   * @param {{ skipPush?: boolean }} [options]
+   */
+  async function ensureImageReadyForDeploy(artifactDir, options = {}) {
+    await dockerLogin();
+
+    const reused = await ensureImageFromPipeline();
+    let ranCompose = false;
+
+    if (!reused) {
+      const result = await buildFromArtifactContents(artifactDir);
+      ranCompose = Boolean(result?.ranCompose);
+    }
+
+    if (ranCompose) {
+      return { ranCompose: true };
+    }
+
+    if (!options.skipPush) {
+      await maybePushImage();
+    }
+
+    const dockerEnv = getDockerEnv();
+    if (imageTag !== 'latest' && fullImage !== latestImage) {
+      await execa('docker', ['tag', fullImage, latestImage], {
+        stdio: 'pipe',
+        env: dockerEnv,
+      }).catch(() => {});
+    }
+
+    return { ranCompose: false };
+  }
+
+  return {
+    fullImage,
+    latestImage,
+    imageTag,
+    getDockerEnv,
+    hasRegistryCredentials,
+    dockerLogin,
+    maybePushImage,
+    ensureImageFromPipeline,
+    buildFromArtifactContents,
+    ensureImageReadyForDeploy,
+  };
+}
+
+/**
+ * Verify that an image:tag exists in a registry and is accessible with current credentials.
+ *
+ * @param {import('../core/config.js').DeployHubConfig} config
+ * @param {Record<string, string>} [env]
+ * @returns {Promise<{ ok: boolean, message: string }>}
+ */
+export async function checkImagePullability(config, env = process.env) {
+  const { fullImage } = resolveDockerImageRef(config, env);
+  const registryUser = env.DOCKER_REGISTRY_USERNAME || '';
+  const registryToken = env.DOCKER_REGISTRY_TOKEN || '';
+  const registryUrl = env.DOCKER_REGISTRY_URL || '';
+  const dockerHost = env.DOCKER_HOST || '';
+
+  /** @type {Record<string, string>} */
+  const dockerEnv = { ...process.env };
+  if (dockerHost) dockerEnv.DOCKER_HOST = dockerHost;
+  if (env.DOCKER_TLS_VERIFY) dockerEnv.DOCKER_TLS_VERIFY = env.DOCKER_TLS_VERIFY;
+  if (env.DOCKER_CERT_PATH) dockerEnv.DOCKER_CERT_PATH = env.DOCKER_CERT_PATH;
+
+  if (registryUser && registryToken) {
+    const registry = registryUrl || 'https://index.docker.io/v1/';
+    try {
+      await execa(
+        'docker',
+        ['login', registry, '-u', registryUser, '--password-stdin'],
+        {
+          input: registryToken,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          env: dockerEnv,
+        }
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        ok: false,
+        message:
+          `Image ${fullImage} is not pullable — registry login failed (${msg}). ` +
+          'Check DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN.',
+      };
+    }
+  }
+
+  try {
+    await execa('docker', ['manifest', 'inspect', fullImage], {
+      stdio: 'pipe',
+      env: dockerEnv,
+    });
+    return { ok: true, message: `Image ${fullImage} is pullable` };
+  } catch (err) {
+    const stderr =
+      err instanceof Error && 'stderr' in err
+        ? String(/** @type {{ stderr?: string }} */ (err).stderr || '')
+        : '';
+    const combined = `${err instanceof Error ? err.message : String(err)} ${stderr}`.toLowerCase();
+
+    let hint = '';
+    if (combined.includes('unauthorized') || combined.includes('authentication required')) {
+      hint =
+        'The image may exist but is private and inaccessible with your current credentials. ' +
+        'Set DOCKER_REGISTRY_USERNAME and DOCKER_REGISTRY_TOKEN, or configure KUBE_IMAGE_PULL_SECRET for the cluster.';
+    } else if (combined.includes('not found') || combined.includes('manifest unknown')) {
+      hint =
+        'The image does not exist in the registry yet.';
+    } else if (combined.includes('denied')) {
+      hint = 'Access denied — check registry credentials and repository permissions.';
+    } else {
+      hint = 'Verify the image name/tag and registry connectivity.';
+    }
+
+    const hasCreds = Boolean(registryUser && registryToken);
+
+    return {
+      ok: false,
+      message:
+        `Image ${fullImage} is not pullable. ${hint}\n` +
+        (hasCreds
+          ? '  DeployHub will build and push this image automatically during your next `deployhub build`.\n'
+          : '  If you have DOCKER_REGISTRY_USERNAME/DOCKER_REGISTRY_TOKEN configured, DeployHub will build and push this image automatically during your next `deployhub build`.\n' +
+            '  If not, either configure those variables, or push the image manually before deploying:\n') +
+        `    docker push ${fullImage}`,
+    };
+  }
+}

package/src/utils/github-actions.js

@@ -3,7 +3,8 @@ import path from 'path';
 import { getWorkflowHeaderComment } from './author.js';
 import {
   generateDeploymentEnvSection,
-  getDeploymentSecretKeys,
+  getDeploymentWorkflowSecretKeys,
+  getDeploymentSecretChecklistItems,
   DEPLOYMENT_ENV_KEYS,
 } from '../deployment/deployment-env.js';
 
@@ -287,7 +288,7 @@ export function generateWorkflowYaml(
     const env = environments[envName];
     if (!env) continue;
 
-    const keys = getDeploymentSecretKeys(env.type, config);
+    const keys = getDeploymentWorkflowSecretKeys(env.type, config);
     for (const key of keys) {
       envVars.add(`${key}: \${{ secrets.${key} }}`);
     }
@@ -438,10 +439,12 @@ export async function guessCliGithubRepo(cwd = process.cwd()) {
 }
 
 /**
+ * Flat list of required secret key names (for callers that only need keys).
  * @param {string[]} storageProviders
  * @param {string[]} deployEnvironments
  * @param {Record<string, { type: string }>} environments
  * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @param {string|null} [cliSource]
  * @returns {string[]}
  */
 export function getRequiredSecrets(
@@ -451,28 +454,69 @@ export function getRequiredSecrets(
   config = null,
   cliSource = null
 ) {
-  /** @type {Set<string>} */
-  const secrets = new Set();
+  return getGithubSecretsChecklist(
+    storageProviders,
+    deployEnvironments,
+    environments,
+    config,
+    cliSource
+  )
+    .filter((item) => item.required)
+    .map((item) => item.key);
+}
+
+/**
+ * Labeled GitHub Secrets checklist (required + optional) for post-init output.
+ * @param {string[]} storageProviders
+ * @param {string[]} deployEnvironments
+ * @param {Record<string, { type: string }>} environments
+ * @param {import('../core/config.js').DeployHubConfig} [config]
+ * @param {string|null} [cliSource]
+ * @returns {import('../deployment/deployment-env.js').SecretChecklistItem[]}
+ */
+export function getGithubSecretsChecklist(
+  storageProviders,
+  deployEnvironments,
+  environments,
+  config = null,
+  cliSource = null
+) {
+  /** @type {Map<string, import('../deployment/deployment-env.js').SecretChecklistItem>} */
+  const byKey = new Map();
 
   const resolvedCliSource = cliSource || config?.cli?.source;
   if (isGithubCliSource(resolvedCliSource)) {
-    secrets.add(GITHUB_CLI_TOKEN_SECRET);
+    byKey.set(GITHUB_CLI_TOKEN_SECRET, {
+      key: GITHUB_CLI_TOKEN_SECRET,
+      required: true,
+      note: 'required when installing DeployHub CLI from a private GitHub repo',
+    });
   }
 
   for (const provider of storageProviders) {
     const keys = PROVIDER_ENV_MAP[provider] || [];
-    keys.forEach((k) => secrets.add(k));
+    for (const key of keys) {
+      byKey.set(key, { key, required: true });
+    }
   }
 
   for (const envName of deployEnvironments) {
     const env = environments[envName];
-    if (!env) continue;
+    if (!env?.type) continue;
 
-    const keys = getDeploymentSecretKeys(env.type, config);
-    keys.forEach((k) => secrets.add(k));
+    for (const item of getDeploymentSecretChecklistItems(env.type, config)) {
+      const existing = byKey.get(item.key);
+      if (existing) {
+        if (item.required && !existing.required) {
+          byKey.set(item.key, item);
+        }
+        continue;
+      }
+      byKey.set(item.key, item);
+    }
   }
 
-  return Array.from(secrets);
+  return Array.from(byKey.values());
 }
 
 /**