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

package/README.md

@@ -56,9 +56,9 @@ bunx olve-build . --out .olve/out
 ### Releases
 
 Versions are `2.0.0-beta.N` on the `beta` dist-tag (`publishConfig`) until v2 reaches prod, then
-`latest`. To release, bump `version` in `package.json` and push to `v2`: the self-deploy's
-`publish-sdk` step runs `bun run check` and `bun publish` when that version is not on npm yet. It
-skips when the version exists, or when the pipeline secret `NPM_TOKEN` is unset.
+`latest`. To release, bump `version` in `package.json`, push to `v2`: once the run reaches prod, the
+self-deploy's `publish-sdk` step runs `bun run check` and `bun publish` when that version is not on npm yet. It
+skips when the version exists, or when the pipeline secret `NPM_TOKEN` is unset. Published versions: `npm view @olivervea/pipelines versions`.
 
 ## Authoring
 
@@ -129,11 +129,12 @@ Library steps carry their own implementation and image; they take typed config a
 |---|---|---|---|
 | `steps.script` | yours | yours | `script` (embedded), `env` (see above) |
 | `steps.gitHubSource` | `alpine:3.22` (work happens in the harness) | `{ repo: "owner/name", sha }` (plain schemas: needs a mapper) → `Source` | `token?: Secret` (sent as `Authorization: Bearer`; becomes the step's secret) |
-| `steps.imageBuild` | `gcr.io/kaniko-project/executor:debug` | `{ source: Source }` → `BuiltImage { repository, tag, digest, tar }` | `repository` (image name; tag = run version, `-attempt<n>` on reruns), `cacheRepo?` (kaniko layer cache), `registryMap?` (kaniko `--registry-map`: registry → mirror prefix, falls back upstream), `stallTimeoutSeconds?` (default 300, 0 = off), `retries?` (default 2) |
+| `steps.imageBuild` | `gcr.io/kaniko-project/executor:debug` | `{ source: Source }` → `BuiltImage { repository, tag, digest, tar }` | `repository` (image name; tag = run version, `-attempt<n>` on reruns), `cacheRepo?` (kaniko layer cache), `registryMap?` (kaniko `--registry-map`: registry → mirror prefix; default: the homelab pull-through caches, `{}` = off), `stallTimeoutSeconds?` (default 300, 0 = off), `retries?` (default 2) |
 | `steps.helmDeployOverSsh` | `alpine:3.22` (+ `apk add openssh-client` at run time) | `{ source: Source, image: BuiltImage }` → `HelmRelease { release, namespace, image }` | `host` (`user@host`), `sshKey: Secret`, `release`, `namespace`, `chart` (dir in the source), `values?` (chart-relative `-f`), `set?`, `healthUrl?` |
 
 - `gitHubSource` downloads `https://api.github.com/repos/<repo>/tarball/<sha>` (retrying 5xx), strips the top-level directory and outputs it as `tree`.
 - `imageBuild` copies the tree to `/kaniko/build-context` (kaniko wipes other directories between multi-stage builds), builds `Dockerfile` at the tree root with `--no-push --tar-path --digest-file`, and outputs the tarball. `repository` in the output is fully qualified the way a runtime names a loaded image (`x` → `docker.io/library/x`). A **stall watchdog** kills kaniko when it prints nothing for `stallTimeoutSeconds` (a base-image pull can stall on an idle connection at "Unpacking rootfs", and kaniko has no read timeout), failing the attempt; `retries` then starts a fresh attempt. The retry is deliberately a new pod, never a second kaniko in the same container: kaniko unpacks the base image over the container root and does not clean up when killed.
+- **Caches never block a build.** `registryMap` defaults to the homelab pull-through caches (`DEFAULT_REGISTRY_MAP`: `mcr.microsoft.com` → `mcr-cache.ovea.pro`, `index.docker.io` → `hub-cache.ovea.pro`; kaniko under gVisor stalls pulling from mcr.microsoft.com directly). A map you pass replaces the default; `{}` turns mapping off. Before kaniko starts, every mirror host and the `cacheRepo` registry gets a 5 s `GET https://<host>/v2/` (200 or 401 = up); one that doesn't answer is dropped with a log line (`mcr-cache.ovea.pro unreachable; pulling from mcr.microsoft.com directly`, or no `--cache` for the layer cache). After that, kaniko itself copes: it falls back to the original registry when a mirror can't serve an image's manifest (`RetrieveRemoteImage`; `--skip-default-registry-fallback` is never set), a layer-cache lookup error is a cache miss, a cache push error is a warning, and `--skip-push-permission-check` stops its startup check of the cache repo from exiting. A cache that dies mid-download (after the manifest came from it) fails or stalls the attempt; `retries` starts a fresh one, which probes again.
 - `helmDeployOverSsh` streams the image tar into the host's **k3s** containerd (`nerdctl --address /run/k3s/containerd/containerd.sock --namespace k8s.io load`), copies the chart to `/tmp/<release>-helm-<namespace>`, runs `helm upgrade --install` from inside it (values, then `set`, then `image.repository`/`image.tag`/`image.pullPolicy=Never`, which always win), waits for `kubectl rollout status deploy/<release>`, and with `healthUrl` polls it (5 × 5 s) from the harness.
 
 **Helpers.** General functions the library steps are built on, exported for custom handlers:
@@ -197,7 +198,7 @@ export default pipeline({ name: "Olve.Pipelines", description: "…", input: M.D
 - **Stage forms.** `.stage(a)`, `.stage(a, b)`, `.stage([a, from => ({…})])` and `.stage([a, mapA], [b, mapB])` are accepted, and tuples can be mixed with plain steps. The old `.stage(step, mapper)` form is a type error and a describe error.
 - **The `from` argument.** It is keyed by step name, plus `input` for the pipeline input. It holds `Ref<T>` values, so only property access and literals compile. Use `from["deploy-beta"].url` for names that contain hyphens.
 - **Describe checks the mapper twice.** It records the mapper with proxies, and it statically analyses the mapper's source. The source must be an object literal of member chains, literals, constant arrays and nested object literals. Ternaries, `&&`, `||`, `??`, `!`, comparisons, arithmetic, template strings, calls, spread and optional chaining are all rejected. Free identifiers such as module constants are allowed; they are recorded as `{const}`.
-- **Triggers.** A pipeline may call `onPush` at most once. Each `onPoll` needs a distinct `name` (default `"poll"`).
+- **Triggers.** A pipeline may call `onPush` at most once. Each `onPoll` and `onWebhook` needs a distinct `name` (`onPoll` defaults to `"poll"`). `onWebhook({ name, verify }, ({ headers, body }) => input | null)` maps a delivery to `/api/hooks/<pipeline id>/<name>`; `verify` is `hmacSha256({ secret, header, prefix? })`, `githubSignature(secret)` or `bearer(secret)`, and `null` ignores the delivery.
 - **Failure handlers.** `.onFailure(handler, { steps? })` takes a step whose inputs are all `FailureContext`. When a run fails, the service runs each handler whose scope (default: any step) contains a failed step, once per failure: `run <handler>` in the handler's image with its declared secrets, from the run's pinned binary. It is untracked and best-effort — not an attempt of the run, never retried, and its own failure triggers nothing; its log is kept at `runs/<p>/<run>/_failure/<handler>/<id>/log`. `FailureContext` carries `pipeline {id, name}`, `run {id, number, address, versionStamp, trigger, url}`, `version {number, commit}`, the run's `input`, a one-line `reason`, and `failedSteps[]` (`step, attempt, address, reason, logUrl`) — only the steps in the handler's scope, never empty.
 
 ### Testing handlers
@@ -335,9 +336,10 @@ Exact format: [`manifest.schema.json`](manifest.schema.json) (JSON Schema 2020-1
 - **`stages`** is an array whose items are either `{steps: [Step…]}` (parallel, with a barrier) or `{when: {field: [values]}, stages: [...]}`.
 - **`triggers`**:
   - `{kind: "push", name: "push"}`;
-  - `{kind: "poll", name, url, headers, secrets, valuePath, intervalSeconds}`, where header values may contain `$SECRET:NAME`.
+  - `{kind: "poll", name, url, headers, secrets, valuePath, intervalSeconds}`, where header values may contain `$SECRET:NAME`;
+  - `{kind: "webhook", name, verify: {scheme: "hmac-sha256", secret, header, prefix} | {scheme: "bearer", secret}}`. The `map-trigger` event is `{headers, body}`; a `null` mapping yields a `skipped` envelope (the delivery is ignored).
 - **`failureHandlers`** is a list of `{step: Step, steps: [names] | null}`. Each handler's inputs are all FailureContext (`{"ref": "failure"}`).
-- **`secrets`** lists every secret used by steps and polls, sorted, as `{name, description}`.
+- **`secrets`** lists every secret used by steps, polls and webhooks, sorted, as `{name, description}`.
 
 Describe runs these checks; reconcile should re-run the manifest-level ones:
 

package/manifest.schema.json

@@ -483,6 +483,78 @@
             "intervalSeconds"
           ],
           "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Inbound HTTP delivery to /api/hooks/<pipeline id>/<name>. Event = {headers, body}; a null mapping ignores it.",
+          "properties": {
+            "kind": {
+              "const": "webhook",
+              "type": "string"
+            },
+            "name": {
+              "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
+              "type": "string"
+            },
+            "verify": {
+              "oneOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "header": {
+                      "minLength": 1,
+                      "type": "string"
+                    },
+                    "prefix": {
+                      "description": "Text before the hex digest in the header, e.g. 'sha256='.",
+                      "type": "string"
+                    },
+                    "scheme": {
+                      "const": "hmac-sha256",
+                      "type": "string"
+                    },
+                    "secret": {
+                      "description": "Secret name; also the env var name in the step container.",
+                      "pattern": "^[A-Z_][A-Z0-9_]*$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "scheme",
+                    "secret",
+                    "header",
+                    "prefix"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "scheme": {
+                      "const": "bearer",
+                      "type": "string"
+                    },
+                    "secret": {
+                      "description": "Secret name; also the env var name in the step container.",
+                      "pattern": "^[A-Z_][A-Z0-9_]*$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "scheme",
+                    "secret"
+                  ],
+                  "type": "object"
+                }
+              ]
+            }
+          },
+          "required": [
+            "kind",
+            "name",
+            "verify"
+          ],
+          "type": "object"
         }
       ]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olivervea/pipelines",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.2",
   "description": "Olve.Pipelines v2 SDK: typed pipeline authoring, the step harness, and the build tool.",
   "type": "module",
   "license": "MIT",

package/src/builder/pipeline.ts

@@ -3,6 +3,7 @@ import type { AnyModel, Infer, InferInput, Plain } from "../core/models.ts";
 import type { Secret } from "../core/secrets.ts";
 import type { AnyStep, OutputValue, Step } from "../core/steps.ts";
 import { isStep } from "../core/steps.ts";
+import type { WebhookEvent, WebhookVerify } from "../core/webhooks.ts";
 import type { IsUnion, OrError, Simplify } from "../core/types.ts";
 import type { Optional } from "../core/models.ts";
 import type { FailureContext } from "../library/models.ts";
@@ -70,7 +71,7 @@ type SiblingNames<E extends readonly unknown[], K> = {
 }[number];
 
 /**
- * Per-entry check. Inference constraints (see spikes/sdk-types):
+ * Per-entry check. Inference constraints:
  *  - the [step, mapper] branch must be exactly `readonly [S, (from) => …]` — wrapping S or the whole
  *    mapper type in a conditional/intersection breaks inference of E or contextual typing of `from`;
  *    so name errors of tuple entries are reported on the mapper's return type instead;
@@ -146,7 +147,8 @@ export type TriggerNode =
       readonly valuePath: string;
       readonly intervalSeconds: number;
       readonly map: (value: string) => unknown;
-    };
+    }
+  | { readonly kind: "webhook"; readonly name: string; readonly verify: WebhookVerify; readonly map: (event: WebhookEvent) => unknown };
 
 export interface FailureHandlerNode {
   readonly step: AnyStep;
@@ -236,6 +238,18 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     return this;
   }
 
+  /**
+   * Start a run from a delivery to `/api/hooks/<pipeline id>/<name>`, authenticated by `verify`. Map it to the
+   * pipeline input (`z.input` view), or return `null` to ignore it. Runs as code in a `map-trigger` Job per delivery.
+   */
+  onWebhook<R extends InferInput<In>>(
+    cfg: { name: string; verify: WebhookVerify },
+    map: (event: WebhookEvent) => Exact<R, InferInput<In>> | null,
+  ): this {
+    this[PIPELINE].triggers.push({ kind: "webhook", name: cfg.name, verify: cfg.verify, map: map as (event: WebhookEvent) => unknown });
+    return this;
+  }
+
   /**
    * Add a stage (its steps run in parallel). Entries: `step` (inputs matched by model) or
    * `[step, from => ({ … })]` (explicit mapping). Every entry sees only what was available

package/src/core/webhooks.ts

@@ -0,0 +1,30 @@
+import type { Secret } from "./secrets.ts";
+
+/** How a webhook trigger authenticates deliveries. Build one with `hmacSha256`, `githubSignature` or `bearer`. */
+export type WebhookVerify =
+  | { readonly scheme: "hmac-sha256"; readonly secret: Secret; readonly header: string; readonly prefix: string }
+  | { readonly scheme: "bearer"; readonly secret: Secret };
+
+/** HMAC-SHA256 of the raw body keyed by `secret`, hex, in `header` after `prefix`. */
+export function hmacSha256(o: { secret: Secret; header: string; prefix?: string }): WebhookVerify {
+  return Object.freeze({ scheme: "hmac-sha256", secret: o.secret, header: o.header, prefix: o.prefix ?? "" });
+}
+
+/** GitHub's delivery signature: `X-Hub-Signature-256: sha256=<hex>`. */
+export function githubSignature(secret: Secret): WebhookVerify {
+  return hmacSha256({ secret, header: "X-Hub-Signature-256", prefix: "sha256=" });
+}
+
+/** `Authorization: Bearer <secret>`. */
+export function bearer(secret: Secret): WebhookVerify {
+  return Object.freeze({ scheme: "bearer", secret });
+}
+
+/**
+ * What a webhook trigger mapper receives: the request headers (lower-case names, without `authorization`
+ * and the signature header) and the body (parsed JSON, or the raw text when it isn't JSON).
+ */
+export interface WebhookEvent {
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: unknown;
+}

package/src/describe/describe.ts

@@ -339,9 +339,16 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
   // ── triggers ──
   const triggerNames = new Set<string>();
   const triggers: TriggerT[] = data.triggers.map((t) => {
-    if (triggerNames.has(t.name)) problems.push(`duplicate trigger '${t.name}'${t.kind === "push" ? " (onPush may be used once)" : " (give each onPoll a distinct name)"}`);
+    if (triggerNames.has(t.name)) problems.push(`duplicate trigger '${t.name}'${t.kind === "push" ? " (onPush may be used once)" : " (give each onPoll and onWebhook a distinct name)"}`);
     triggerNames.add(t.name);
     if (t.kind === "push") return { kind: "push", name: "push" };
+    if (t.kind === "webhook") {
+      if (!STEP_NAME.test(t.name)) problems.push(`webhook trigger name '${t.name}' must be lower-case kebab`);
+      const secret = useSecret(t.verify.secret, `webhook '${t.name}'`);
+      if (t.verify.scheme === "bearer") return { kind: "webhook", name: t.name, verify: { scheme: "bearer", secret } };
+      if (!t.verify.header) problems.push(`webhook '${t.name}': the signature header must not be empty`);
+      return { kind: "webhook", name: t.name, verify: { scheme: "hmac-sha256", secret, header: t.verify.header, prefix: t.verify.prefix } };
+    }
     if (!STEP_NAME.test(t.name)) problems.push(`poll trigger name '${t.name}' must be lower-case kebab`);
     if (!(Number.isInteger(t.intervalSeconds) && t.intervalSeconds > 0)) problems.push(`poll '${t.name}': intervalSeconds must be a positive integer`);
     const declared = new Set(t.secrets.map((s) => useSecret(s, `poll '${t.name}'`)));

package/src/describe/manifest-schema.ts

@@ -90,6 +90,21 @@ export const Trigger = z
         intervalSeconds: z.number().int().positive(),
       })
       .describe("Background poller."),
+    z
+      .strictObject({
+        kind: z.literal("webhook"),
+        name: z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/),
+        verify: z.discriminatedUnion("scheme", [
+          z.strictObject({
+            scheme: z.literal("hmac-sha256"),
+            secret: secretName,
+            header: z.string().min(1),
+            prefix: z.string().describe("Text before the hex digest in the header, e.g. 'sha256='."),
+          }),
+          z.strictObject({ scheme: z.literal("bearer"), secret: secretName }),
+        ]),
+      })
+      .describe("Inbound HTTP delivery to /api/hooks/<pipeline id>/<name>. Event = {headers, body}; a null mapping ignores it."),
   ])
   .meta({ id: "Trigger" });
 

package/src/harness/main.ts

@@ -6,6 +6,7 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { isImplementation } from "../core/handlers.ts";
 import type { AnyStep } from "../core/steps.ts";
+import type { WebhookEvent } from "../core/webhooks.ts";
 import { pipelineData, type PipelineData, type StageNode } from "../builder/pipeline.ts";
 import { createCtx, formatLog } from "../ctx/index.ts";
 import { DescribeError, describePipeline, manifestText } from "../describe/describe.ts";
@@ -162,6 +163,12 @@ async function runMode(cfg: HarnessConfig, name: string | undefined, io: Harness
   }
 }
 
+function isWebhookEvent(v: unknown): boolean {
+  if (typeof v !== "object" || v === null || Array.isArray(v) || !("body" in v)) return false;
+  const headers = (v as { headers?: unknown }).headers;
+  return typeof headers === "object" && headers !== null && !Array.isArray(headers);
+}
+
 async function mapTriggerMode(cfg: HarnessConfig, name: string | undefined, io: HarnessIO): Promise<number> {
   if (!name) return io.stderr(USAGE), EXIT.usage;
   const data = pipelineData(cfg.pipeline);
@@ -181,15 +188,21 @@ async function mapTriggerMode(cfg: HarnessConfig, name: string | undefined, io:
     exec = fail("input", `poll trigger '${name}': the event must be {"value": "<string>"}`, EXIT.inputInvalid);
   else if (trigger.kind === "push" && (typeof raw.value !== "object" || raw.value === null || Array.isArray(raw.value)))
     exec = fail("input", `push trigger: the event must be the webhook payload object`, EXIT.inputInvalid);
+  else if (trigger.kind === "webhook" && !isWebhookEvent(raw.value))
+    exec = fail("input", `webhook trigger '${name}': the event must be {"headers": {...}, "body": ...}`, EXIT.inputInvalid);
   else {
     let mapped: unknown;
     let threw: unknown = undefined;
     try {
-      mapped = trigger.kind === "poll" ? await trigger.map((raw.value as { value: string }).value) : await trigger.map(raw.value);
+      mapped =
+        trigger.kind === "poll" ? await trigger.map((raw.value as { value: string }).value)
+        : trigger.kind === "webhook" ? await trigger.map(raw.value as WebhookEvent)
+        : await trigger.map(raw.value);
     } catch (e) {
       threw = e ?? new Error("undefined");
     }
     if (threw !== undefined) exec = fail("handler", `trigger '${name}' mapper threw: ${(threw as Error)?.message ?? String(threw)}`, EXIT.handlerFailed);
+    else if (mapped === null && trigger.kind === "webhook") exec = { envelope: { status: "skipped", reason: `trigger '${name}' ignored the delivery` }, exitCode: EXIT.ok };
     else {
       const r = parseStrict(data.input.schema, mapped, "input");
       exec = r.ok

package/src/index.ts

@@ -3,6 +3,7 @@
 export { z } from "zod";
 export { model, fileRef, optional, type Model, type AnyModel, type Infer, type InferInput, type Plain, type FileRef, type Optional } from "./core/models.ts";
 export { secret, type Secret, type DeclaredSecrets } from "./core/secrets.ts";
+export { hmacSha256, githubSignature, bearer, type WebhookVerify, type WebhookEvent } from "./core/webhooks.ts";
 export { step, type Step, type AnyStep, type StepDef, type StepInput, type StepKind, type InputEntry, type InputSpec, type LibraryStep, type OutputValue } from "./core/steps.ts";
 export { implement, type Implementation, type Handler, type HandlerResult, type Skipped } from "./core/handlers.ts";
 export type { Ctx, RunInfo, Sh, ShOptions, ExecOptions, Http, HttpInit, RetryOptions, OutputFileOptions } from "./ctx/types.ts";

package/src/library/image-build.ts

@@ -34,7 +34,11 @@ export interface ImageBuildDef<N extends string> {
    * A registry without GC grows with every changed layer — prune it when needed.
    */
   cacheRepo?: string;
-  /** kaniko `--registry-map` (registry → mirror prefix); kaniko falls back to the original registry if the mirror lacks the image. */
+  /**
+   * kaniko `--registry-map` (registry → mirror prefix); kaniko falls back to the original registry if
+   * the mirror lacks the image. Defaults to the homelab pull-through caches (`DEFAULT_REGISTRY_MAP`);
+   * a map replaces the default entirely, `{}` turns mapping off.
+   */
   registryMap?: Record<string, string>;
   timeoutSeconds?: number;
   /**
@@ -52,6 +56,57 @@ export interface ImageBuildDef<N extends string> {
   retries?: number;
 }
 
+/**
+ * Default `registryMap`: pull-through caches for mcr.microsoft.com and Docker Hub. kaniko under gVisor
+ * can stall forever pulling from mcr.microsoft.com directly.
+ */
+export const DEFAULT_REGISTRY_MAP: Readonly<Record<string, string>> = {
+  "mcr.microsoft.com": "mcr-cache.ovea.pro",
+  "index.docker.io": "hub-cache.ovea.pro",
+};
+
+/** How long a cache registry gets to answer `GET /v2/` before the build goes without it. */
+export const CACHE_PROBE_TIMEOUT_MS = 5000;
+
+/** The registry host of an image reference or mirror prefix (`registry.ovea.pro/a/b` → `registry.ovea.pro`). */
+export function registryHost(ref: string): string {
+  return ref.split("/")[0]!;
+}
+
+/** Whether a registry answers its API root: 200, or 401 (it wants a token). Never throws. */
+export async function registryUp(http: Ctx["http"], host: string, signal?: AbortSignal, timeoutMs = CACHE_PROBE_TIMEOUT_MS): Promise<boolean> {
+  try {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const res = await http.fetch(`https://${host}/v2/`, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+    await res.body?.cancel().catch(() => {});
+    return res.status === 200 || res.status === 401;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Drops the caches that don't answer, so a cache outage (GC, maintenance) never blocks a build: an
+ * unreachable mirror is left out of the registry map, an unreachable `cacheRepo` means no layer cache.
+ */
+export async function reachableCaches(
+  ctx: Pick<Ctx, "http" | "log" | "signal">,
+  caches: { registryMap: Record<string, string>; cacheRepo?: string },
+): Promise<{ registryMap: Record<string, string>; cacheRepo?: string }> {
+  const hosts = new Set([...Object.values(caches.registryMap), ...(caches.cacheRepo ? [caches.cacheRepo] : [])].map(registryHost));
+  const up = new Map(await Promise.all([...hosts].map(async (h) => [h, await registryUp(ctx.http, h, ctx.signal)] as const)));
+  const registryMap: Record<string, string> = {};
+  for (const [from, to] of Object.entries(caches.registryMap)) {
+    if (up.get(registryHost(to))) registryMap[from] = to;
+    else ctx.log(`${registryHost(to)} unreachable; pulling from ${from} directly`);
+  }
+  if (caches.cacheRepo && !up.get(registryHost(caches.cacheRepo))) {
+    ctx.log(`${registryHost(caches.cacheRepo)} unreachable; building without the layer cache`);
+    return { registryMap };
+  }
+  return { registryMap, ...(caches.cacheRepo ? { cacheRepo: caches.cacheRepo } : {}) };
+}
+
 /** Default `retries`: a stalled or flaky build gets two fresh attempts before the run fails. */
 export const DEFAULT_RETRIES = 2;
 
@@ -82,6 +137,8 @@ export function qualifyRepository(repository: string): string {
  * Output: `BuiltImage { repository, tag, digest, tar }`.
  */
 export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<N, ImageBuildInput, typeof BuiltImage, never> & LibraryStep {
+  const registryMap = def.registryMap ?? DEFAULT_REGISTRY_MAP;
+  const mapped = Object.keys(registryMap).length > 0;
   return makeStep(
     "imageBuild",
     { name: def.name, description: def.description, image: KANIKO_IMAGE, input, output: BuiltImage, secrets: [], timeoutSeconds: def.timeoutSeconds, retries: def.retries ?? DEFAULT_RETRIES },
@@ -89,10 +146,11 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
       manifestConfig: () => ({
         repository: def.repository,
         ...(def.cacheRepo ? { cacheRepo: def.cacheRepo } : {}),
-        ...(def.registryMap ? { registryMap: def.registryMap } : {}),
+        ...(mapped ? { registryMap: { ...registryMap } } : {}),
       }),
       async run({ source }: { source: { tree: FileRef } }, ctx: Ctx) {
         const tag = imageTag(ctx.run);
+        const caches = await reachableCaches(ctx, { registryMap, cacheRepo: def.cacheRepo });
         const tree = await ctx.files.fetch(source.tree);
         await ctx.exec(["mkdir", "-p", KANIKO_CONTEXT]);
         await ctx.exec(["cp", "-r", `${tree}/.`, KANIKO_CONTEXT]);
@@ -104,7 +162,9 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
         const tarPath = join(out, "image.tar");
         const digestPath = join(out, "digest");
         // No --single-snapshot: it is incompatible with multi-stage Dockerfiles whose later stages need
-        // the build context intact.
+        // the build context intact. --skip-push-permission-check: with --no-push kaniko otherwise checks
+        // the cache repo at startup and exits if it is down; later cache lookup and push errors are
+        // only warnings.
         await ctx.exec([
           "/kaniko/executor",
           `--context=${KANIKO_CONTEXT}`,
@@ -113,8 +173,8 @@ export function imageBuild<const N extends string>(def: ImageBuildDef<N>): Step<
           `--tar-path=${tarPath}`,
           `--digest-file=${digestPath}`,
           `--destination=${def.repository}:${tag}`,
-          ...(def.cacheRepo ? ["--cache=true", `--cache-repo=${def.cacheRepo}`] : []),
-          ...Object.entries(def.registryMap ?? {}).map(([from, to]) => `--registry-map=${from}=${to}`),
+          ...(caches.cacheRepo ? ["--cache=true", `--cache-repo=${caches.cacheRepo}`, "--skip-push-permission-check"] : []),
+          ...Object.entries(caches.registryMap).map(([from, to]) => `--registry-map=${from}=${to}`),
         ], { idleTimeoutSeconds: def.stallTimeoutSeconds ?? DEFAULT_STALL_TIMEOUT_SECONDS });
 
         let digest: string;