Task
A task is a piece of work with dependencies that reads input files and generates output files.
Tasks are the pieces of work needed to build or develop your project.
A minimal task contains just a list of commands.
tasks:
example:
cmds:
- echo "minimal example"Local vs. container — the one rule to remember. If a task declares an image,
its commands run inside that container. If it has no image, they run
directly on your host using the tools installed there. Everything else (sources,
outputs, caching, dependencies) works the same in both cases. Containers are the
recommended default: they remove the need to install build tools on every machine
and make a build behave identically on your laptop and in CI. See
run a task in a container.
Anatomy of a task
A task is built from a small, fixed set of fields:
| Field | Purpose |
|---|---|
cmds | The commands to run, in order. Arguments after -- are appended to the last one. |
image | Run the commands inside this container image. Omit to run on the host. |
src | Input files/folders. Used for caching — unchanged sources let the task be skipped. |
generates | Output files/folders the task produces. This is what gets cached, stored and restored. |
deps | Other tasks that must run first (see dependencies). |
needs | Services that must be running first (see needs). |
mounts | Extra paths to make available to a container task (see container). |
envs | Environment variables for the commands. |
labels | Group/filter tasks (see labels). |
cache | The caching method/backend for this task. |
timeout | Maximum execution time, e.g. 10m (see timeouts). |
resources | CPU and memory limits of the container (see resources). |
network | What the container reaches besides its needs (see network). |
runner | The server the task has to run on (see runner). |
Source files (src)
Tasks that depend on input files should declare them under src.
Hammerkit detects whether the src files have changed compared to previous runs and skips execution if they are unchanged.
tasks:
build:
description: "run typescript build"
src:
- tsconfig.json
- src
cmds:
- tscGenerated files (generates)
Tasks that produce output files should declare them under generates.
Hammerkit archives generated files, so build outputs can be cached, stored and restored.
tasks:
build:
description: "run typescript build"
src:
- tsconfig.json
- src
generates:
- dist
cmds:
- tscExporting generated files
By default generated files of a container task stay inside the container volume.
Mark a generate with export: true to copy it back into your workspace after the
task ran. This is useful when another tool outside hammerkit needs the produced
files, for example a build artifact you want to inspect or publish.
tasks:
build:
image: node:alpine
generates:
- path: dist
export: true
cmds:
- tsc -bAn exported output is copied back only when the task succeeds. Test reports,
screenshots and videos are most useful when a test fails: mark those
export: always and hammerkit copies them to the workspace even when the task
exits non-zero. A failed task is never cached, so nothing else changes.
tasks:
e2e:
image: cypress/included:13.15.0
generates:
- path: cypress/videos
export: always
cmds:
- cypress runOutputs start empty
When a task runs, its outputs start empty: hammerkit deletes what an earlier run left in them before the task's commands run. A file a deleted source used to produce, or a partial result of a failed run, would otherwise end up in the next result and in the cache.
An output that is also a source of the task, or contains one, is left alone: a
package-lock.json that npm install both reads and writes keeps its content.
Set resetOnChange: false on an output to keep its content between runs, for a
tool that builds incrementally on top of its previous output:
tasks:
build:
image: rust:1.90-slim
src: [Cargo.toml, Cargo.lock, src]
generates:
- path: target
resetOnChange: false # cargo reuses what it compiled before
cmds:
- cargo build --releaseWhatever such an output keeps becomes part of the next result, so prefer a mount for a tool's cache: a mount is never part of a task's result.
Timeouts
A task that hangs — a deadlocked test, a stuck network call — would otherwise block
the run until your CI provider kills the job. Set a timeout and hammerkit aborts
the task once it runs longer, fails it with timed out after <duration>, and stops
the run like any other failure.
tasks:
e2e:
image: cypress/included:13.15.0
timeout: 15m
cmds:
- cypress runDurations are written as a number plus a unit: ms, s, m, h or d, and can
be combined (1h30m). A timed-out task is cleaned up the same way as a cancelled
one — its container or Kubernetes job is removed — and never writes a cache entry.
The timeout does not affect the task's cache key.
To give every task a default, pass --timeout to run or
up; a task's own timeout takes precedence.
hammerkit run --timeout 30mCapping every task
--max-timeout limits every task, also one with a longer timeout of its own: each task
runs at most the shorter of the two, and a task without a timeout (and without
--timeout) runs at most --max-timeout. It never lets a task run longer than its own
timeout.
hammerkit run --max-timeout 2mOn a server it is the run option maxTimeout, also remote run --max-timeout. The
agent clients send the timeout an agent gives a command
this way, so a shell task with timeout: 10m stops a command after the 30 seconds the
agent asked for. The time counts from when a task starts, its container or pod start
included, not while the run waits in the queue or for the task's dependencies.
On Kubernetes the time a task's pod waits for room under the quota of its namespace does
not count either: the timeout stops while the quota refuses the pod and goes on once it is
created. The waits of a task add up, and may last as long as its timeout in all: a task with
timeout: 30m waits up to 30 minutes for room, then runs up to 30 minutes. Once it waited that
long it fails with gave up waiting for room under the quota of the namespace after 30m, its timeout, not with timed out. The quota's own rule applies besides: after 10 minutes a pod
waits on only while a pod that will end holds the room (see
the backend's namespaces). Only the wait of the
task's own pod is left out: the pods that copy its files into and out of its claim wait up to
10 minutes for room, and that wait counts against the timeout.
Resources
A heavy build step can take every core and all the memory of the machine it runs
on. Declare resources and hammerkit limits the task's container to them, and
plans the run by them.
tasks:
build:
image: node:22
resources:
cpus: 2
memory: 4Gi
cmds:
- npm run buildBoth fields are optional and use Kubernetes notation: cpus as cores (2, 0.5)
or millicores (500m), memory with a Ki/Mi/Gi/Ti suffix (at least 6Mi).
cpus and memory set the limit and request the same. To set them apart, use
requests and limits; a request must not exceed its limit, and a request without a
limit is not capped:
tasks:
build:
image: node:22
resources:
requests: { cpus: 500m, memory: 1Gi }
limits: { cpus: 2, memory: 4Gi }
cmds:
- npm run buildOn Docker the limits become the container's CPU and memory limits, and a memory
request below its limit a soft memory reservation. On Kubernetes the job container
gets the same requests and limits. A task that exceeds its memory limit is killed
by the runtime and fails. cpus above what the Docker host has runs the container
without a CPU limit, with a warning, as such a limit would limit nothing. On
Kubernetes a request beyond what any node offers leaves the pod Pending.
A local task can declare resources too, but nothing limits it;
validate and run --dry-run say so. Resources are not part
of the task's cache key: changing them does not rebuild the task.
Planning the run
The requests also plan the run on the machine hammerkit runs on, for local tasks and for containers on Docker (on Kubernetes the cluster places pods by their requests):
- Before anything starts, hammerkit checks that every task fits, together with the
services it needs. A task whose requests plus those of its services exceed the
host's CPUs or memory fails the run up front, naming the task, instead of hanging or
being killed halfway. With
up, all services must fit together.--skip-resource-checkstarts anyway. - While it runs, a task starts only when its requests fit next to everything
running, the services included. When every task and service on the host requests
both
cpusandmemory, the run is not capped at a worker count (--concurrency, default 4): as many tasks run in parallel as the requests allow. Otherwise--concurrencystill caps the run, and tasks with requests also wait for room. A task that alone exceeds the host runs once nothing else does.
The capacity is the Docker host's when containers run there, else this machine's.
HAMMERKIT_CPUS and HAMMERKIT_MEMORY (e.g. 8, 16Gi) set it, for a CI runner
that shares its machine, for example.
Runner
Experimental. A task can name its server already, but running on one arrives in a follow-up release. Until then a run that resolves to a server stops with an error instead of running locally.
runner names a server registered with hammerkit remote add,
for a task that has to run somewhere else, such as a Mac mini for an Xcode build.
Set it on a task or as a default for the whole build file; extend inherits it.
runner: linux-pool # default of the tasks of this file
tasks:
ios:
runner: mac-mini
cmds:
- xcodebuild -scheme appThe build file holds a name only. The URL and the OAuth issuer live in the host config, so a project can't send your source code to a server you never registered.
Where a run happens, highest first:
--on/--local(follow-up release)- the
HAMMERKIT_ONenvironment variable (local,autoor a server name) - the
runnerof the tasks in the run run.onof the host config, set withhammerkit remote use- the local machine
auto stands for the tasks' runner, else local. A run goes to a single server, so
tasks that name different servers fail the run, and a name that is not registered
is an error: hammerkit never quietly runs a task somewhere else than you asked.
local and auto can't be used as a runner.