hammerkit

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:

FieldPurpose
cmdsThe commands to run, in order. Arguments after -- are appended to the last one.
imageRun the commands inside this container image. Omit to run on the host.
srcInput files/folders. Used for caching — unchanged sources let the task be skipped.
generatesOutput files/folders the task produces. This is what gets cached, stored and restored.
depsOther tasks that must run first (see dependencies).
needsServices that must be running first (see needs).
mountsExtra paths to make available to a container task (see container).
envsEnvironment variables for the commands.
labelsGroup/filter tasks (see labels).
cacheThe caching method/backend for this task.
timeoutMaximum execution time, e.g. 10m (see timeouts).
resourcesCPU and memory limits of the container (see resources).
networkWhat the container reaches besides its needs (see network).
runnerThe 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:
      - tsc

Generated 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:
      - tsc

Exporting 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 -b

An 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 run

Outputs 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 --release

Whatever 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 run

Durations 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 30m

Capping 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 2m

On 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 build

Both 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 build

On 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-check starts 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 cpus and memory, the run is not capped at a worker count (--concurrency, default 4): as many tasks run in parallel as the requests allow. Otherwise --concurrency still 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 app

The 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:

  1. --on / --local (follow-up release)
  2. the HAMMERKIT_ON environment variable (local, auto or a server name)
  3. the runner of the tasks in the run
  4. run.on of the host config, set with hammerkit remote use
  5. 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.

On this page