catladder build config reference

Full options for components.<name>.build (and top-level builds). Fix build problems in catladder.ts and regenerate — never edit the generated pipeline files.

Shared base options (all standalone build types)

Option	Type	Purpose / default
buildCommand	string | string[] | null | false	build step; false/null skips it
startCommand	string	runtime start command
postInstall	string | string[]	runs after the package-manager install (node family)
lint / test / audit	false | TestJobCustom	customize or disable the job
postBuildTests	Record<string, PostBuildTestConfig | false>	named tests against the build output in the post-build stage; block the deploy
artifactsPaths	string[]	extra artifacts (dist, .next always included)
artifactsExcludePaths	string[]	artifact excludes
artifactsReports	{ junit?: string[] }	CI test report paths
cache	CacheConfig | CacheConfig[]	build caching (jobCache is deprecated)
jobVars	EnvVars	env vars only in build jobs
runnerVariables	Record<string,string>	extra runner vars (also for services:)
jobTags	string[]	runner tags
jobImage	JobImageConfig	CI image for the build: a concrete image or { image: "<name>" } referencing a project image
reuseMainBranchImage	boolean | { releaseFiles?: string[] }	release envs (stage/prod) copy the main branch (dev) image of the released commit instead of rebuilding; falls back to a build. Only for env-independent images; not for google-cloudrun. true = { releaseFiles: ["CHANGELOG.md"] }
docker	see below	the deployable image strategy

TestJobCustom (for lint/test/audit): command, jobImage, artifactsReports, artifacts, runnerVariables, allowFailure (allowFailure defaults to true for audit).

PostBuildTestConfig (for postBuildTests entries): TestJobCustom with a required command, plus services?: Services (gitlab shape, reachable by alias) and vars?: Record<string,string>. The job gets the build artifacts, the build vars and vars (not the deployed env's runtime vars), installs dependencies for node builds, and uploads artifacts also on failure.

audit additionally takes level: "info" | "low" | "moderate" | "high" | "critical" (default "critical") — the lowest severity that fails the job, translated to the package manager's own flag (pnpm audit --audit-level, yarn npm audit --severity, classic yarn audit --level). Ignored when command spells out its own command:

audit: { level: "high" },   // fail on high and critical advisories

Per-type options & defaults

node

• Works with yarn and pnpm — the package manager is autodetected (packageManager field / lockfile), overridable via top-level packageManager: "pnpm" | "yarn" in catladder.ts.
• docker? — built-in node image { type: "node", yarnRebuildEnabled?: boolean (default true, yarn berry only), additionsBegin?: string[], additionsEnd?: string[] }, or a custom docker config.
• Defaults: buildCommand: "<pm> build", startCommand: "<pm> start" (yarn/pnpm per detection), artifacts ["dist", ".next"], excludes [".next/cache/**/*"].

rails

• test?.databaseImage? — test DB container image (Postgres only; default docker.io/postgres:latest).
• cnbBuilder? — Cloud Native Buildpacks config, used only when there is no Dockerfile:
  • image? — builder image. Actual runtime default heroku/builder:24 (the type's JSDoc saying heroku/buildpacks:20 is stale).
  • packVersion? — pack CLI version. Actual runtime default 0.36.4 (JSDoc 0.28.0 is stale).
  • packExtraArgs?: string[] — extra args passed to pack.
  • buildVars?: Record<string, string | undefined> — Bundler / Rails asset-precompile vars (undefined inherits from the component's env vars).

meteor

• Yarn-only (meteor's bundler is yarn-based) — a pnpm project cannot use this build type.
• installScripts?: boolean — run yarn install inside the source folder in the image (only needed with custom image scripts).
• docker? — meteor built-in or custom. Default startCommand: "node main.js".

custom

• type: "custom" — required.
• jobImage: JobImageConfig — required CI image (concrete image or { image: "<name>" } project-image ref).
• docker: BuildConfigDocker — required image build config.
• jobServices?: Services — services for lint/test/audit/build jobs.
• lint? / test? / audit?: TestJobCustom — disabled unless set.

node-static / storybook — deprecated

Use type: "node" with docker: { type: "nginx" } (and startCommand: "" for a purely static app). storybook previously defaulted buildCommand: "yarn build-storybook --quiet -o ./dist".

docker sub-config

BuildConfigDocker is either:

• built-in: { type: "nginx" | "node" | "meteor", additionsBegin?: string[], additionsEnd?: string[] } — additionsBegin/additionsEnd inject Dockerfile lines before/after the standard steps.
• custom: { type: "custom", buildContextLocation?: "root" | "component" (default "root"), dockerfileContent?: string[] } — expects a Dockerfile. dockerfileContent is experimental and supports the $DOCKER_COPY_WORKSPACE_FILES / $DOCKER_COPY_AND_INSTALL_APP placeholders.

Workspace builds (builds)

Top-level builds: Record<string, WorkspaceBuildConfig>. Only type: "node" is supported.

• Node workspace build: dir?, buildCommand? (default <pm> build), dockerDefaults?: { yarnRebuildEnabled }, plus shared lint? (default { command: "<pm> lint" }), test? (default { command: "<pm> test" }), audit?, postBuildTests? (block the deploys of all its components), runnerVariables?, artifactsReports?, jobImage?, jobTags?, cache? (<pm> = yarn/pnpm per detection).
• A component references it via build: { from: "<name>", docker?, startCommand?, artifactsPaths?, artifactsExcludePaths?, cache?, postBuildTests? } — the per-component overrides layer on top of the shared build.