hammerkit

Build file reference

Every key the build-file schema accepts.

This is the complete reference for the hammerkit build file, derived from the schema hammerkit validates against (build.schema.json). Unknown keys are rejected, so this list is exhaustive. For prose and examples, follow the links to the dedicated pages.

Top-level keys

KeyTypeDescription
envsmap of string→string/numberBuild-file-wide environment variables.
tasksmap of name→taskThe tasks in this file.
servicesmap of name→serviceThe services in this file.
referencesmap of prefix→path, {path, with, publish} or git sourceReference other build files (keep their own directory).
includesmap of prefix→path, {path, with, publish} or git sourceInclude other build files (use this file's directory), with inputs. publish: false leaves the file out of a published version.
environmentsmap of name→environmentRun targets (Kubernetes or remote Docker).
cachesmap of name→cacheNamed cache declarations (method + backend).
labelsmap of string→string/numberLabels applied to every task/service in the file.
runnerstringDefault runner of the tasks in this file.

Task

A task is either a container task (it has an image, its own or the one of the task it extends), an image build (it has build) or a local task (neither). They share these fields (an image build has no cmds, shell, extend or args):

FieldTypeDescription
cmdsarray of string | {cmd, path}Commands to run, in order. path sets the working directory for that command.
descriptionstringShown by ls; a missing one is a validate warning.
srcarray of stringInput files/folders/globs used for caching.
generatesarray of string | {path, export, resetOnChange, name}Output paths. export: true copies back to the workspace when the task succeeds, export: always also when it fails; outputs start empty when the task runs, resetOnChange: false keeps their content (see outputs start empty).
depsarray of stringTasks (name or prefix:name) that run first.
needsarray of string | {service, name}Services that must be ready first.
envsmap of string→string/numberTask-level environment variables (override build-file envs).
labelsmap of string→string/numberLabels for filtering.
cachestring | {name, method}Cache method shorthand or a named cache reference.
extendstringBase task to inherit from (prefix:name).
shellstringShell used to run cmds (default /bin/sh).
timeoutduration (30s, 10m, 1h30m)Maximum execution time; the task fails when exceeded.
secretsarray of {from, env | path, cache}Credentials from env:NAME or file:path, injected as an env variable or a read-only file; kept out of the cache key and logs.
resources{cpus, memory} | {requests, limits}CPU and memory limits and requests (2, 500m; 512Mi, 2Gi); the run is planned by the requests. Not enforced for a local task, not part of the cache key.
networkopen | none | {allow: [hosts]}What the container reaches besides the services in needs (default open); allow goes through an egress proxy, and a host:port entry forwards raw TCP. An error on a local task, except on a server's cluster; not part of the cache key.
argsbooleanWhether the last command takes arguments after --: false refuses them, true says it is meant to, which a server with runs.args: declared requires.
runnerstringName of the server the task has to run on (experimental, see runner).
publishbooleanfalse: a server leaves the task out of a published version. Locally it changes nothing.

Container task adds:

FieldTypeDescription
imagestring (required, unless the task extends a container task, whose image it takes)The container image to run in. Its presence is what makes the task containerized.
mountsarray of stringExtra host[:container][:ro] mounts.
volumeSizesize (5Gi)On Kubernetes, the size of the claim that holds the sources, mounts and outputs of the task (the environment's volumeSize when left out, else 1Gi). Ignored elsewhere, not part of the cache key.
capAddarray of stringLinux capabilities added to the container, such as SYS_ADMIN.

Image build adds:

FieldTypeDescription
build{context, dockerfile, tags, push, cache, digest, login, insecure} (required)The Dockerfile to build with BuildKit, as docker build does: its context, tags, whether to push, a registry cache for its layers, a file for the digest of the pushed image, and logins of {registry, user, password: {from, account}}. Without src, the task reads the context.
volumeSizesize (5Gi)As for a container task.

Local task adds:

FieldTypeDescription
platform{os, arch}Restrict to os (win/macos/linux) and/or arch (arm64/arm).

Service

A service is either a container service (it has an image) or a Kubernetes service (it has a selector).

Container service:

FieldTypeDescription
imagestring (required)The service image.
cmdstringOverride the container command.
workdirstringWorking directory inside the container; see working directory. Defaults to the build file's directory.
shellstringRun cmd and the healthcheck as <shell> -c "<cmd>"; see shell. Without it both run in exec form.
portsarray of string/numbercontainerPort or hostPort:containerPort to publish to the host.
healthcheck{cmd, timeout}Readiness command, and how long the service may take to pass it once running (duration, default 20s, HAMMERKIT_HEALTHCHECK_TIMEOUT changes the default); see healthcheck.
restartsinteger 0 to 10On Kubernetes, how often the container may crash and be restarted while the service starts before it fails (default 2); see restarts. On Docker a crash fails it at once.
initstringA task (name or prefix:name) run once the healthcheck passed; the service is ready for dependents only after it succeeded; see init.
envsmap of string→string/numberService environment variables.
secretsarray of {from, env | path}Credentials injected as an env variable or a read-only file.
resources{cpus, memory} | {requests, limits}CPU and memory limits and requests of the container, as for a task.
networkopen | none | {allow: [hosts]}What the service reaches besides the services it needs, as for a task; what needs the service always reaches it.
argsbooleanfalse refuses arguments after -- of up for its cmd.
volumeSizesize (20Gi)On Kubernetes, the size of the claim that holds the service's sources, mounts and volumes, as for a task.
volumesarray of stringname:containerPath[:ro] volumes that persist across restarts.
mountsarray of stringhost:container[:ro] config mounts.
depsarray of stringTasks that must run before the service starts.
needsarray of string | {service, name}Other services this one depends on.
srcarray of stringSources, used for caching the service image build.
labelsmap of string→string/numberLabels for filtering.
descriptionstringDescription shown by ls.
continuousbooleanThe service watches its own files, such as a dev server: up --watch leaves it running, and a move of a service run on Kubernetes writes the changed files into its pod.
publishbooleanfalse: a server leaves the service out of a published version.

Kubernetes service (forwards an existing cluster resource — see Kubernetes service):

FieldTypeDescription
selector{type, name} (required)Resource type (deployment/service/pod) and name to forward.
portsarray of string/number (required)hostPort:containerPort mappings to forward to localhost.
contextstringOverride the environment's kube context.
namespacestringOverride the environment's namespace.
kubeconfigstringOverride the environment's kubeconfig path.
depsarray of stringTasks that run before forwarding.
labels / description–As above.

Cache (caches)

Each named cache has a method and a backend (see caches):

FieldTypeDescription
methodchecksum | modify-date | noneHow changes are detected.
backend.typelocal | s3 | registryWhere results are stored.
backend.pathstring (local)Directory; defaults to ~/.hammerkit/remote-cache.
backend.bucketstring (s3, required)Target bucket.
backend.region / endpoint / prefix / forcePathStyle– (s3)S3 connection options.
backend.repositorystring (registry, required)OCI repository without a tag, e.g. ghcr.io/org/cache.
backend.insecureboolean (registry)Use plain HTTP; defaults to true only for localhost.
retention.maxAge / maxSize / keepPerTaskduration / size / integerRetention policy for cache prune and automatic pruning.

A task's cache field is either the method shorthand (cache: checksum) or a reference {name, method} to a declared cache.

Environment (environments)

Each environment is a run target — exactly one of:

KeyFieldsDescription
kubernetescontext (required), namespace, kubeconfig, httpRoutes[], networkPolicyRun tasks as jobs and services as deployments on a cluster. networkPolicy: enforced states that the cluster enforces NetworkPolicy, which network limits need.
dockerhostRun against a remote Docker daemon.

An httpRoutes entry has host, service and gateway (all required), servicePort, path and gatewayNamespace — see HTTP routes.

On this page