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
| Key | Type | Description |
|---|---|---|
envs | map of string→string/number | Build-file-wide environment variables. |
tasks | map of name→task | The tasks in this file. |
services | map of name→service | The services in this file. |
references | map of prefix→path, {path, with, publish} or git source | Reference other build files (keep their own directory). |
includes | map of prefix→path, {path, with, publish} or git source | Include other build files (use this file's directory), with inputs. publish: false leaves the file out of a published version. |
environments | map of name→environment | Run targets (Kubernetes or remote Docker). |
caches | map of name→cache | Named cache declarations (method + backend). |
labels | map of string→string/number | Labels applied to every task/service in the file. |
runner | string | Default 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):
| Field | Type | Description |
|---|---|---|
cmds | array of string | {cmd, path} | Commands to run, in order. path sets the working directory for that command. |
description | string | Shown by ls; a missing one is a validate warning. |
src | array of string | Input files/folders/globs used for caching. |
generates | array 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). |
deps | array of string | Tasks (name or prefix:name) that run first. |
needs | array of string | {service, name} | Services that must be ready first. |
envs | map of string→string/number | Task-level environment variables (override build-file envs). |
labels | map of string→string/number | Labels for filtering. |
cache | string | {name, method} | Cache method shorthand or a named cache reference. |
extend | string | Base task to inherit from (prefix:name). |
shell | string | Shell used to run cmds (default /bin/sh). |
timeout | duration (30s, 10m, 1h30m) | Maximum execution time; the task fails when exceeded. |
secrets | array 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. |
network | open | 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. |
args | boolean | Whether the last command takes arguments after --: false refuses them, true says it is meant to, which a server with runs.args: declared requires. |
runner | string | Name of the server the task has to run on (experimental, see runner). |
publish | boolean | false: a server leaves the task out of a published version. Locally it changes nothing. |
Container task adds:
| Field | Type | Description |
|---|---|---|
image | string (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. |
mounts | array of string | Extra host[:container][:ro] mounts. |
volumeSize | size (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. |
capAdd | array of string | Linux capabilities added to the container, such as SYS_ADMIN. |
Image build adds:
| Field | Type | Description |
|---|---|---|
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. |
volumeSize | size (5Gi) | As for a container task. |
Local task adds:
| Field | Type | Description |
|---|---|---|
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:
| Field | Type | Description |
|---|---|---|
image | string (required) | The service image. |
cmd | string | Override the container command. |
workdir | string | Working directory inside the container; see working directory. Defaults to the build file's directory. |
shell | string | Run cmd and the healthcheck as <shell> -c "<cmd>"; see shell. Without it both run in exec form. |
ports | array of string/number | containerPort 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. |
restarts | integer 0 to 10 | On 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. |
init | string | A task (name or prefix:name) run once the healthcheck passed; the service is ready for dependents only after it succeeded; see init. |
envs | map of string→string/number | Service environment variables. |
secrets | array 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. |
network | open | none | {allow: [hosts]} | What the service reaches besides the services it needs, as for a task; what needs the service always reaches it. |
args | boolean | false refuses arguments after -- of up for its cmd. |
volumeSize | size (20Gi) | On Kubernetes, the size of the claim that holds the service's sources, mounts and volumes, as for a task. |
volumes | array of string | name:containerPath[:ro] volumes that persist across restarts. |
mounts | array of string | host:container[:ro] config mounts. |
deps | array of string | Tasks that must run before the service starts. |
needs | array of string | {service, name} | Other services this one depends on. |
src | array of string | Sources, used for caching the service image build. |
labels | map of string→string/number | Labels for filtering. |
description | string | Description shown by ls. |
continuous | boolean | The 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. |
publish | boolean | false: a server leaves the service out of a published version. |
Kubernetes service (forwards an existing cluster resource — see Kubernetes service):
| Field | Type | Description |
|---|---|---|
selector | {type, name} (required) | Resource type (deployment/service/pod) and name to forward. |
ports | array of string/number (required) | hostPort:containerPort mappings to forward to localhost. |
context | string | Override the environment's kube context. |
namespace | string | Override the environment's namespace. |
kubeconfig | string | Override the environment's kubeconfig path. |
deps | array of string | Tasks that run before forwarding. |
labels / description | – | As above. |
Cache (caches)
Each named cache has a method and a backend (see caches):
| Field | Type | Description |
|---|---|---|
method | checksum | modify-date | none | How changes are detected. |
backend.type | local | s3 | registry | Where results are stored. |
backend.path | string (local) | Directory; defaults to ~/.hammerkit/remote-cache. |
backend.bucket | string (s3, required) | Target bucket. |
backend.region / endpoint / prefix / forcePathStyle | – (s3) | S3 connection options. |
backend.repository | string (registry, required) | OCI repository without a tag, e.g. ghcr.io/org/cache. |
backend.insecure | boolean (registry) | Use plain HTTP; defaults to true only for localhost. |
retention.maxAge / maxSize / keepPerTask | duration / size / integer | Retention 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:
| Key | Fields | Description |
|---|---|---|
kubernetes | context (required), namespace, kubeconfig, httpRoutes[], networkPolicy | Run tasks as jobs and services as deployments on a cluster. networkPolicy: enforced states that the cluster enforces NetworkPolicy, which network limits need. |
docker | host | Run against a remote Docker daemon. |
An httpRoutes entry has host, service and gateway (all required),
servicePort, path and gatewayNamespace — see
HTTP routes.