@olivervea/pipelines 2.0.0-beta.2 → 2.0.0-beta.6

package/src/library/checks.ts

@@ -0,0 +1,23 @@
+// Checks for deployed apps, used from custom test handlers.
+import type { Ctx } from "../ctx/types.ts";
+
+/** The in-cluster URL of a release's Service, assuming the chart names it after the release. */
+export function serviceUrl(release: { release: string; namespace: string }): string {
+  return `http://${release.release}.${release.namespace}.svc.cluster.local`;
+}
+
+/**
+ * Checks `url` serves a single-page app: `GET <url>/` references a `/assets/*.js` bundle (Vite's
+ * layout), and the bundle is served as JavaScript. Returns the page, for app-specific checks.
+ */
+export async function checkSpa(ctx: Pick<Ctx, "http" | "log">, url: string): Promise<{ html: string; bundle: string }> {
+  const base = url.replace(/\/$/, "");
+  const html = await (await ctx.http.expectOk(`${base}/`)).text();
+  const bundle = html.match(/src="(\/assets\/[^"]+\.js)"/)?.[1];
+  if (bundle === undefined) throw new Error(`${base}/ does not reference an /assets/*.js bundle`);
+  const js = await ctx.http.expectOk(`${base}${bundle}`);
+  await js.body?.cancel().catch(() => {});
+  if (!(js.headers.get("content-type")?.includes("javascript") ?? false)) throw new Error(`${base}${bundle} is not served as JavaScript`);
+  ctx.log("SPA served", { url: base, bundle });
+  return { html, bundle };
+}

package/src/library/compose-deploy.ts

@@ -0,0 +1,93 @@
+// steps.composeDeploy — ask a Docker Compose deployer to recreate a service with an image. The step is
+// thin on purpose: the deployer (pull, recreate, health, rollback) lives beside the compose project
+// and is fixed there, behind a versioned HTTP API, without editing pipelines.
+import type { Ctx } from "../ctx/types.ts";
+import type { Configurable } from "../core/config.ts";
+import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
+import type { Secret } from "../core/secrets.ts";
+import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
+import { httpHealthCheck } from "./http-health.ts";
+import { HelmRelease, PushedImage } from "./models.ts";
+
+/** The step's own image: the work is one HTTP call from the harness. */
+export const COMPOSE_DEPLOY_IMAGE = "alpine:3.22";
+
+/** A resolved `kind: compose` target. */
+export interface ComposeTargetValue {
+  kind: "compose";
+  deployerUrl: string;
+  service: string;
+  token: { secret: string };
+  healthUrl?: string | undefined;
+}
+
+/** What the deployer answers to `POST /v1/deploy`. */
+export interface ComposeDeployResult {
+  status: "deployed" | "rolled-back" | "failed";
+  service: string;
+  image: string;
+  previousImage?: string;
+  message?: string;
+  log?: string[];
+}
+
+export interface ComposeDeployDef<N extends string, K extends string> {
+  name: LiteralName<N>;
+  /** What the step does, shown in the UI. Required; may be empty. */
+  description: string;
+  /** A compose target, usually a `select` case's reference. */
+  target: Configurable<ComposeTargetValue>;
+  /** The secret the target's `token` names (declared by the step). */
+  token: Secret<K>;
+  timeoutSeconds?: number;
+}
+
+const input = { image: PushedImage };
+
+/**
+ * Deploys a registry image (by digest) to a compose service: `POST <deployerUrl>/v1/deploy
+ * { service, image: <repository>@<digest> }` with the target's bearer token. The deployer pulls the
+ * image, recreates the service, waits for its health and rolls back on failure; the step reports its
+ * answer, then (with the target's `healthUrl`) checks health itself. Output: a `HelmRelease` with the
+ * service as `release` and `compose` as `namespace`, so it can share a step name with the helm deploys.
+ */
+export function composeDeploy<const N extends string, const K extends string>(
+  def: ComposeDeployDef<N, K>,
+): Step<N, typeof input, typeof HelmRelease, K> & LibraryStep {
+  const configurable = { target: def.target };
+  return makeStep(
+    "composeDeploy",
+    { name: def.name, description: def.description, image: COMPOSE_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.token], timeoutSeconds: def.timeoutSeconds },
+    {
+      manifestConfig: () => ({ target: recordConfigRefs(def.target), token: def.token.name }),
+      async run({ image }: { image: { repository: string; digest: string } }, ctx: Ctx) {
+        const { target } = resolveConfigRefs(configurable, ctx.config ?? {}) as { target: ComposeTargetValue };
+        if (target?.kind !== "compose") throw new Error(`composeDeploy '${def.name}': the target is kind '${String(target?.kind)}', not 'compose'`);
+        if (target.token.secret !== def.token.name) throw new Error(`composeDeploy '${def.name}': the target's token names secret ${target.token.secret}, but the step declares ${def.token.name}`);
+        const token = (ctx.secrets as Record<string, string>)[def.token.name];
+        const ref = `${image.repository}@${image.digest}`;
+        const url = `${target.deployerUrl.replace(/\/+$/, "")}/v1/deploy`;
+        ctx.log("deploying", { service: target.service, image: ref, deployer: target.deployerUrl });
+        const res = await ctx.http.fetch(url, {
+          method: "POST",
+          headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+          body: JSON.stringify({ service: target.service, image: ref }),
+        });
+        const text = await res.text();
+        let result: ComposeDeployResult | undefined;
+        try {
+          result = JSON.parse(text) as ComposeDeployResult;
+        } catch {
+          // reported below
+        }
+        for (const line of result?.log ?? []) ctx.log(`deployer: ${line}`);
+        if (!res.ok || result?.status !== "deployed")
+          throw new Error(`the deployer answered HTTP ${res.status}: ${result ? `${result.status}${result.message ? `: ${result.message}` : ""}` : text.slice(0, 300)}`);
+        if (target.healthUrl) await httpHealthCheck(ctx, target.healthUrl, { attempts: 12, delaySeconds: 5 });
+        ctx.log("deployed", { service: target.service, image: ref, previous: result.previousImage ?? "-" });
+        return { release: target.service, namespace: "compose", image: ref };
+      },
+    },
+    configurable,
+  ) as never;
+}

package/src/library/github-source.ts

@@ -7,6 +7,8 @@ import { join } from "node:path";
 import { z } from "zod";
 import type { Ctx } from "../ctx/types.ts";
 import type { Secret } from "../core/secrets.ts";
+import type { Configurable } from "../core/config.ts";
+import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
 import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
 import { extractTar } from "../util/tar.ts";
 import { Source } from "./models.ts";
@@ -23,11 +25,25 @@ export interface GitHubSourceDef<N extends string, T extends string> {
   description: string;
   /** Token sent to the GitHub API (needed for private repositories; raises the rate limit). */
   token?: Secret<T>;
+  /** GitHub API base (default `https://api.github.com`; GitHub Enterprise: `https://<host>/api/v3`). */
+  apiUrl?: Configurable<string | undefined>;
   timeoutSeconds?: number;
 }
 
+export const GITHUB_API_URL = "https://api.github.com";
+
+/** A declared secret's value, or "" when it is not set. */
+function optionalSecret(ctx: Pick<Ctx, "secrets">, name: string): string {
+  try {
+    return ((ctx.secrets as Record<string, string>)[name] ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+
 /** Tarball URL of `repo` at `sha` (the API redirects to codeload.github.com). */
-export const gitHubTarballUrl = (repo: string, sha: string): string => `https://api.github.com/repos/${repo}/tarball/${encodeURIComponent(sha)}`;
+export const gitHubTarballUrl = (repo: string, sha: string, apiUrl = GITHUB_API_URL): string =>
+  `${apiUrl.replace(/\/+$/, "")}/repos/${repo}/tarball/${encodeURIComponent(sha)}`;
 
 /**
  * Downloads `repo` at `sha` from GitHub as a tarball and outputs it as a `Source` whose `tree` is the
@@ -41,11 +57,13 @@ export function gitHubSource<const N extends string, const T extends string = ne
     "gitHubSource",
     { name: def.name, description: def.description, image: GITHUB_SOURCE_IMAGE, input, output: Source, secrets: def.token ? [def.token] : [], timeoutSeconds: def.timeoutSeconds },
     {
-      manifestConfig: () => ({ ...(def.token ? { token: def.token.name } : {}) }),
+      manifestConfig: () => ({ ...(def.token ? { token: def.token.name } : {}), ...(def.apiUrl !== undefined ? { apiUrl: recordConfigRefs(def.apiUrl) } : {}) }),
       async run({ repo, sha }: { repo: string; sha: string }, ctx: Ctx) {
         const headers: Record<string, string> = { accept: "application/vnd.github+json", "user-agent": "olve-pipelines" };
-        if (def.token) headers.authorization = `Bearer ${ctx.secrets[def.token.name]}`;
-        const url = gitHubTarballUrl(repo, sha);
+        const token = def.token ? optionalSecret(ctx, def.token.name) : "";
+        if (token) headers.authorization = `Bearer ${token}`;
+        else if (def.token) ctx.log(`${def.token.name} is not set: fetching anonymously (public repositories only)`);
+        const url = gitHubTarballUrl(repo, sha, resolveConfigRefs(def.apiUrl, ctx.config ?? {}) ?? GITHUB_API_URL);
         mkdirSync(ctx.tmpDir, { recursive: true });
         const dir = mkdtempSync(join(ctx.tmpDir, "github-source-"));
         const archive = join(dir, "repo.tar.gz");
@@ -73,5 +91,6 @@ export function gitHubSource<const N extends string, const T extends string = ne
         return { repo, sha, tree };
       },
     },
+    { apiUrl: def.apiUrl },
   ) as never;
 }

package/src/library/helm-deploy-ssh.ts

@@ -1,16 +1,23 @@
-// steps.helmDeployOverSsh — import a built image into a k3s host's containerd and helm-upgrade a
-// release there, over SSH; optionally verify an HTTP health endpoint afterwards.
+// steps.helmDeployOverSsh — get built images onto a k3s host and helm-upgrade a release there, over
+// SSH; optionally verify an HTTP health endpoint afterwards.
 //
 // Ported from v1's olve-lib.sh (olve_ssh_host, olve_image_import, olve_helm_deploy) and
 // deploy-beta.sh (rollout wait + health loop); the footguns are kept as comments below.
-import { chmodSync, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { Ctx } from "../ctx/types.ts";
 import type { FileRef } from "../core/models.ts";
 import type { Secret } from "../core/secrets.ts";
+import type { Configurable } from "../core/config.ts";
+import { recordConfigRefs, resolveConfigRefs } from "../core/config-refs.ts";
 import { makeStep, type LibraryStep, type LiteralName, type Step } from "../core/steps.ts";
-import { httpHealthCheck } from "./http-health.ts";
-import { BuiltImage, HelmRelease, Source } from "./models.ts";
+import type { Simplify } from "../core/types.ts";
+import { httpHealthCheck, type HttpHealthCheckOptions } from "./http-health.ts";
+import { BuiltImage, HelmRelease, PushedImage, Source } from "./models.ts";
+import { shq, sshSession } from "./ssh.ts";
+import { helmDeployOverSshTarget, type HelmDeploySshTargetDef, type HelmTargetDeployInput } from "./helm-deploy.ts";
+
+export { shq } from "./ssh.ts";
 
 /** Alpine: `apk add openssh-client` at run time gives ssh/scp (the health check runs in the harness). */
 export const HELM_DEPLOY_IMAGE = "alpine:3.22";
@@ -20,63 +27,125 @@ export const HELM_DEPLOY_IMAGE = "alpine:3.22";
  * the k3s instance's `k8s.io` namespace (otherwise pods fail with ErrImageNeverPull).
  */
 export const K3S_IMAGE_IMPORT = "sudo nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load";
+/** Registry images are pulled the same way before the rollout, so the rollout doesn't wait on the pull. */
+export const K3S_IMAGE_PULL = "sudo nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io pull -q";
 
-const ROLLOUT_TIMEOUT = "120s";
+export const DEFAULT_ROLLOUT_TIMEOUT_SECONDS = 120;
 
-const input = { source: Source, image: BuiltImage };
-export type HelmDeployOverSshInput = typeof input;
+type DefaultImages = { readonly image: "image" };
+type ImageModel<R extends boolean> = R extends true ? typeof PushedImage : typeof BuiltImage;
+export type HelmDeployOverSshInput<
+  Im extends Record<string, string> = DefaultImages,
+  R extends boolean = false,
+  Rf extends Record<string, string> = {},
+> = Simplify<
+  { readonly source: typeof Source } & { readonly [K in keyof Im]: ImageModel<R> } & { readonly [K in keyof Rf]: typeof PushedImage }
+>;
 
-export interface HelmDeployOverSshDef<N extends string, K extends string> {
+export interface HelmDeployOverSshDef<
+  N extends string,
+  K extends string,
+  Im extends Record<string, string> = DefaultImages,
+  R extends boolean = false,
+  Rf extends Record<string, string> = {},
+> {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
   description: string;
   /** SSH target, `user@host`. The user needs passwordless sudo for nerdctl, and helm/kubectl with a kubeconfig. */
-  host: string;
+  host: Configurable<string>;
   /** Private key for `host`. */
   sshKey: Secret<K>;
-  /** Helm release name; the chart's Deployment is expected to be named the same (rollout wait). */
-  release: string;
-  namespace: string;
+  /** Helm release name. */
+  release: Configurable<string>;
+  namespace: Configurable<string>;
   /** Chart directory inside the source tree, e.g. `helm`. */
   chart: string;
   /** Values files, relative to the chart directory (`-f`, in order). */
-  values?: readonly string[];
+  values?: Configurable<readonly string[]>;
+  /**
+   * Chart-specific `--set` flags (e.g. `{ "ingress.enabled": "false" }`). The image flags are added by
+   * the step and always win: `<prefix>.repository`, `<prefix>.tag`, `<prefix>.pullPolicy`.
+   */
+  set?: Configurable<Readonly<Record<string, string>>>;
+  /**
+   * The images to deploy: step input key → the chart's values prefix for that image. Each input is a
+   * `BuiltImage` (or `PushedImage` with `fromRegistry`). Default `{ image: "image" }`; several images
+   * need a mapper, e.g. `{ server: "image", web: "web.image" }`.
+   */
+  images?: Im & { readonly source?: never };
   /**
-   * Chart-specific `--set` flags (e.g. `{ "slo.enabled": "false" }`). The image flags are added by
-   * the step and always win: `image.repository`, `image.tag`, `image.pullPolicy=Never`.
+   * The images are `PushedImage`s from a registry (`imageBuild` with `push`): pulled on the host
+   * first, then `pullPolicy=IfNotPresent`. Default: `BuiltImage` tarballs, imported on the host, then
+   * `pullPolicy=Never`.
    */
-  set?: Readonly<Record<string, string>>;
-  /** After the rollout, GET this URL until it returns 2xx, 5 × 5 s (`httpHealthCheck`), or fail the step. */
-  healthUrl?: string;
+  fromRegistry?: R & (boolean extends R ? "❌ fromRegistry must be a literal true or false (use `as const` on a shared config object)" : unknown);
+  /**
+   * Registry images the chart only references (not run by the release's own pods, e.g. an image the
+   * app starts Jobs with): step input key → values prefix. Each input is a `PushedImage`; the step sets
+   * `<prefix>.repository`, `<prefix>.tag` and `<prefix>.digest` and does not pull it on the host. Works
+   * next to tarball `images`.
+   */
+  imageRefs?: Rf & { readonly source?: never };
+  /** Rollouts to wait for, in order: `deploy/<name>` for a bare name. Default: the release name. */
+  deployments?: readonly string[];
+  /** Per rollout (`kubectl rollout status --timeout`). Default 120. */
+  rolloutTimeoutSeconds?: number;
+  /** After the rollouts, GET this URL until it returns 2xx (`httpHealthCheck`: 5 × 5 s unless given), or fail the step. */
+  healthUrl?: Configurable<string> | ({ url: Configurable<string> } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
   timeoutSeconds?: number;
 }
 
-const SAFE = /^[A-Za-z0-9_\/.:=@%+,-]+$/;
-/** POSIX shell quoting (safe words are left bare, so logs stay readable). */
-export function shq(s: string): string {
-  return SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+export interface HelmImageFlags {
+  prefix: string;
+  repository: string;
+  tag: string;
+  pullPolicy: "Never" | "IfNotPresent";
+  /** Pins the image: `<prefix>.digest` (the chart renders `repository:tag@digest`). */
+  digest?: string;
 }
 
-/** Remote `helm upgrade --install`, run from inside the copied chart directory. */
-export function helmUpgradeCommand(o: {
-  remoteChart: string;
-  release: string;
-  namespace: string;
-  values: readonly string[];
-  set: Readonly<Record<string, string>>;
+/** A registry image the chart only references (`imageRefs`). */
+export interface HelmImageRefFlags {
+  prefix: string;
   repository: string;
   tag: string;
-}): string {
+  digest: string;
+}
+
+export interface HelmFlagOptions {
+  values: readonly string[];
+  set: Readonly<Record<string, string>>;
+  images: readonly HelmImageFlags[];
+  imageRefs?: readonly HelmImageRefFlags[];
+}
+
+/** `helm upgrade` flags: values files, `--set`, then the image flags (which win). */
+export function helmFlags(o: HelmFlagOptions): string[] {
   // Chart-relative values paths (`-f values-beta.yaml`) resolve because helm runs from inside the
-  // copied chart dir. Extra flags come before the image flags, so the image overrides win. The image
-  // is local to the node (imported above), never pulled: pullPolicy=Never.
+  // copied chart dir. Extra flags come before the image flags, so the image overrides win.
+  // --set-string: a tag like `2026.10` or `1e5` would otherwise be parsed as a number.
   const flags = [
     ...o.values.flatMap((v) => ["-f", v]),
     ...Object.entries(o.set).flatMap(([k, v]) => ["--set", `${k}=${v}`]),
-    "--set", `image.repository=${o.repository}`,
-    "--set", `image.tag=${o.tag}`,
-    "--set", "image.pullPolicy=Never",
+    ...o.images.flatMap((i) => [
+      "--set", `${i.prefix}.repository=${i.repository}`,
+      "--set", `${i.prefix}.tag=${i.tag}`,
+      "--set", `${i.prefix}.pullPolicy=${i.pullPolicy}`,
+      ...(i.digest ? ["--set-string", `${i.prefix}.digest=${i.digest}`] : []),
+    ]),
+    ...(o.imageRefs ?? []).flatMap((i) => [
+      "--set-string", `${i.prefix}.repository=${i.repository}`,
+      "--set-string", `${i.prefix}.tag=${i.tag}`,
+      "--set-string", `${i.prefix}.digest=${i.digest}`,
+    ]),
   ];
+  return flags;
+}
+
+/** Remote `helm upgrade --install`, run from inside the copied chart directory. */
+export function helmUpgradeCommand(o: HelmFlagOptions & { remoteChart: string; release: string; namespace: string }): string {
+  const flags = helmFlags(o);
   return [
     `cd ${shq(o.remoteChart)}`,
     ["helm", "upgrade", "--install", o.release, ".", "-n", o.namespace, ...flags].map(shq).join(" "),
@@ -84,68 +153,152 @@ export function helmUpgradeCommand(o: {
   ].join(" && ");
 }
 
+/** One image to get onto the host before the upgrade. */
+export interface HostImage {
+  repository: string;
+  tag: string;
+  digest?: string;
+  /** An image tarball to stream in; without one the image is pulled from its registry. */
+  tar?: string;
+}
+
 /**
- * Deploys `image` with the Helm chart at `<source>/<chart>` on a k3s host over SSH:
- * stream the image tar into the host's k3s containerd, copy the chart, `helm upgrade --install`,
- * wait for `deploy/<release>` to roll out, then (with `healthUrl`) poll the health endpoint.
+ * Over SSH: get each image into the host's k3s containerd, copy the chart (with any generated values
+ * files in it), `helm upgrade --install`, then wait for each rollout.
  */
-export function helmDeployOverSsh<const N extends string, const K extends string>(
-  def: HelmDeployOverSshDef<N, K>,
-): Step<N, HelmDeployOverSshInput, typeof HelmRelease, K> & LibraryStep {
-  const values = def.values ?? [];
-  const set = def.set ?? {};
+export async function deployOverSsh(
+  ctx: Ctx,
+  o: {
+    host: string;
+    key: string;
+    chartDir: string;
+    release: string;
+    namespace: string;
+    hostImages: readonly HostImage[];
+    flags: HelmFlagOptions;
+    deployments: readonly string[];
+    rolloutTimeoutSeconds: number;
+  },
+): Promise<void> {
+  const ssh = await sshSession(ctx, { host: o.host, key: o.key });
+  for (const image of o.hostImages) {
+    if (image.tar) {
+      ctx.log("importing image", { image: `${image.repository}:${image.tag}`, host: o.host });
+      // Streamed over ssh's stdin (ctx.exec has none, hence the shell redirect).
+      await ctx.sh(`${ssh.shell(K3S_IMAGE_IMPORT)} < ${shq(image.tar)}`);
+    } else {
+      const ref = image.digest ? `${image.repository}@${image.digest}` : `${image.repository}:${image.tag}`;
+      ctx.log("pulling image", { image: ref, host: o.host });
+      await ssh.run(`${K3S_IMAGE_PULL} ${shq(ref)}`);
+    }
+  }
+  const remoteChart = `/tmp/${o.release}-helm-${o.namespace}`;
+  ctx.log("helm upgrade", { release: o.release, namespace: o.namespace, host: o.host });
+  await ssh.run(`rm -rf ${shq(remoteChart)}`);
+  await ssh.copy(o.chartDir, remoteChart);
+  await ssh.run(helmUpgradeCommand({ ...o.flags, remoteChart, release: o.release, namespace: o.namespace }));
+  for (const d of o.deployments) {
+    const target = d.includes("/") ? d : `deploy/${d}`;
+    ctx.log("waiting for rollout", { deployment: target });
+    await ssh.run(`kubectl -n ${shq(o.namespace)} rollout status ${shq(target)} --timeout=${o.rolloutTimeoutSeconds}s`);
+  }
+}
+
+/** The chart directory inside a fetched source tree, or an error naming it. */
+export function chartDirectory(tree: string, chart: string): string {
+  const dir = join(tree, chart);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new Error(`chart directory '${chart}' not found in the source tree`);
+  return dir;
+}
+
+/**
+ * Deploys images with the Helm chart at `<source>/<chart>` on a k3s host over SSH: get each image
+ * into the host's k3s containerd (stream a tarball in, or pull from the registry), copy the chart,
+ * `helm upgrade --install`, wait for each rollout, then (with `healthUrl`) poll the health endpoint.
+ */
+export function helmDeployOverSsh<
+  const N extends string,
+  const K extends string,
+  const Im extends Record<string, string> = DefaultImages,
+  const Rf extends Record<string, string> = {},
+>(def: HelmDeploySshTargetDef<N, K, Im, Rf>): Step<N, HelmTargetDeployInput<Im, Rf>, typeof HelmRelease, K> & LibraryStep;
+export function helmDeployOverSsh<
+  const N extends string,
+  const K extends string,
+  const Im extends Record<string, string> = DefaultImages,
+  const R extends boolean = false,
+  const Rf extends Record<string, string> = {},
+>(def: HelmDeployOverSshDef<N, K, Im, R, Rf>): Step<N, HelmDeployOverSshInput<Im, R, Rf>, typeof HelmRelease, K> & LibraryStep;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function helmDeployOverSsh(def: any): Step & LibraryStep {
+  return "target" in def ? helmDeployOverSshTarget(def) : helmDeployOverSshLiteral(def);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function helmDeployOverSshLiteral(def: HelmDeployOverSshDef<string, string, any, boolean, any>): Step & LibraryStep {
+  const images: Record<string, string> = def.images ?? { image: "image" };
+  const imageEntries = Object.entries(images);
+  const fromRegistry = def.fromRegistry === true;
+  const rolloutTimeout = def.rolloutTimeoutSeconds ?? DEFAULT_ROLLOUT_TIMEOUT_SECONDS;
+  if (imageEntries.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': images must not be empty`);
+  if ("source" in images) throw new Error(`helmDeployOverSsh '${def.name}': 'source' can't be an image input`);
+  if (def.deployments?.length === 0) throw new Error(`helmDeployOverSsh '${def.name}': deployments must not be empty`);
+  const imageRefs: Record<string, string> = def.imageRefs ?? {};
+  const refEntries = Object.entries(imageRefs);
+  if ("source" in imageRefs) throw new Error(`helmDeployOverSsh '${def.name}': 'source' can't be an image input`);
+  for (const [key] of refEntries) if (key in images) throw new Error(`helmDeployOverSsh '${def.name}': '${key}' is both in images and imageRefs`);
+  const imageModel = fromRegistry ? PushedImage : BuiltImage;
+  const input = {
+    source: Source,
+    ...Object.fromEntries(imageEntries.map(([key]) => [key, imageModel])),
+    ...Object.fromEntries(refEntries.map(([key]) => [key, PushedImage])),
+  };
+  const isDefaultImages = imageEntries.length === 1 && images.image === "image";
+  const configurable = { host: def.host, release: def.release, namespace: def.namespace, values: def.values ?? [], set: def.set ?? {}, healthUrl: def.healthUrl };
+
   return makeStep(
     "helmDeployOverSsh",
     { name: def.name, description: def.description, image: HELM_DEPLOY_IMAGE, input, output: HelmRelease, secrets: [def.sshKey], timeoutSeconds: def.timeoutSeconds },
     {
       manifestConfig: () => ({
-        host: def.host,
+        host: recordConfigRefs(def.host),
         sshKey: def.sshKey.name,
-        release: def.release,
-        namespace: def.namespace,
+        release: recordConfigRefs(def.release),
+        namespace: recordConfigRefs(def.namespace),
         chart: def.chart,
-        values: [...values],
-        set: { ...set },
-        ...(def.healthUrl ? { healthUrl: def.healthUrl } : {}),
+        values: recordConfigRefs(configurable.values),
+        set: recordConfigRefs(configurable.set),
+        ...(isDefaultImages ? {} : { images: { ...images } }),
+        ...(fromRegistry ? { fromRegistry: true } : {}),
+        ...(refEntries.length > 0 ? { imageRefs: { ...imageRefs } } : {}),
+        ...(def.deployments ? { deployments: [...def.deployments] } : {}),
+        ...(def.rolloutTimeoutSeconds !== undefined ? { rolloutTimeoutSeconds: def.rolloutTimeoutSeconds } : {}),
+        ...(def.healthUrl !== undefined ? { healthUrl: recordConfigRefs(def.healthUrl) } : {}),
       }),
-      async run(
-        { source, image }: { source: { tree: FileRef }; image: { repository: string; tag: string; tar: FileRef } },
-        ctx: Ctx,
-      ) {
-        const tree = await ctx.files.fetch(source.tree);
-        const chartDir = join(tree, def.chart);
-        if (!existsSync(chartDir) || !statSync(chartDir).isDirectory()) throw new Error(`chart directory '${def.chart}' not found in the source tree`);
-        const imageTar = await ctx.files.fetch(image.tar);
-
-        // SSH setup. The key file needs a trailing newline (OpenSSH rejects the key otherwise) and
-        // mode 600. The host key is not verified (as in v1): the host is reached over the tailnet.
-        await ctx.exec(["apk", "add", "--no-cache", "openssh-client"]);
-        const sshDir = join(ctx.tmpDir, "ssh");
-        mkdirSync(sshDir, { recursive: true, mode: 0o700 });
-        const keyFile = join(sshDir, "id");
-        const key = ctx.secrets[def.sshKey.name]!;
-        writeFileSync(keyFile, key.endsWith("\n") ? key : key + "\n", { mode: 0o600 });
-        chmodSync(keyFile, 0o600);
-        const opts = ["-i", keyFile, "-o", "StrictHostKeyChecking=no", "-o", "UserKnownHostsFile=/dev/null", "-o", "LogLevel=ERROR", "-o", "BatchMode=yes"];
-        const ssh = (remote: string) => ctx.exec(["ssh", ...opts, def.host, remote]);
-
-        const ref = `${image.repository}:${image.tag}`;
-        ctx.log("importing image", { image: ref, host: def.host });
-        // Streamed over ssh's stdin (ctx.exec has none, hence the shell redirect).
-        await ctx.sh(["ssh", ...opts, def.host, K3S_IMAGE_IMPORT].map(shq).join(" ") + ` < ${shq(imageTar)}`);
-
-        const remoteChart = `/tmp/${def.release}-helm-${def.namespace}`;
-        ctx.log("helm upgrade", { release: def.release, namespace: def.namespace, image: ref });
-        await ssh(`rm -rf ${shq(remoteChart)}`);
-        await ctx.exec(["scp", ...opts, "-r", chartDir, `${def.host}:${remoteChart}`]);
-        await ssh(helmUpgradeCommand({ remoteChart, release: def.release, namespace: def.namespace, values, set, repository: image.repository, tag: image.tag }));
-
-        ctx.log("waiting for rollout", { deployment: def.release });
-        await ssh(`kubectl -n ${shq(def.namespace)} rollout status ${shq(`deploy/${def.release}`)} --timeout=${ROLLOUT_TIMEOUT}`);
-
-        if (def.healthUrl) await httpHealthCheck(ctx, def.healthUrl);
-        return { release: def.release, namespace: def.namespace, image: ref };
+      async run(input: Record<string, { repository: string; tag: string; digest: string; tar?: FileRef }> & { source: { tree: FileRef } }, ctx: Ctx) {
+        const d = resolveConfigRefs(configurable, ctx.config ?? {}) as {
+          host: string; release: string; namespace: string; values: string[]; set: Record<string, string>;
+          healthUrl?: string | ({ url: string } & Pick<HttpHealthCheckOptions, "attempts" | "delaySeconds">);
+        };
+        const chartDir = chartDirectory(await ctx.files.fetch(input.source.tree), def.chart);
+        const hostImages: HostImage[] = [];
+        const flags: HelmImageFlags[] = [];
+        for (const [key, prefix] of imageEntries) {
+          const image = input[key]!;
+          hostImages.push({ repository: image.repository, tag: image.tag, ...(fromRegistry ? {} : { tar: await ctx.files.fetch(image.tar!) }) });
+          flags.push({ prefix, repository: image.repository, tag: image.tag, pullPolicy: fromRegistry ? "IfNotPresent" : "Never" });
+        }
+        const refs: HelmImageRefFlags[] = refEntries.map(([key, prefix]) => ({ prefix, repository: input[key]!.repository, tag: input[key]!.tag, digest: input[key]!.digest }));
+        await deployOverSsh(ctx, {
+          host: d.host, key: ctx.secrets[def.sshKey.name]!, chartDir, release: d.release, namespace: d.namespace, hostImages,
+          flags: { values: d.values, set: d.set, images: flags, imageRefs: refs },
+          deployments: def.deployments ?? [d.release], rolloutTimeoutSeconds: rolloutTimeout,
+        });
+        const health = typeof d.healthUrl === "string" ? { url: d.healthUrl } : d.healthUrl;
+        if (health) await httpHealthCheck(ctx, health.url, { attempts: health.attempts, delaySeconds: health.delaySeconds });
+        return { release: d.release, namespace: d.namespace, image: `${flags[0]!.repository}:${flags[0]!.tag}` };
       },
     },
+    configurable,
   ) as never;
 }