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. |
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). |
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 -bResetting generated files on change
By default a generated directory keeps its contents between runs, so a re-run can
reuse previous output. Mark a generate with resetOnChange: true to wipe it
before the task runs again, guaranteeing the task starts from an empty output
directory and no stale files from a previous run remain.
tasks:
bundle:
image: node:alpine
generates:
- path: dist
resetOnChange: true
cmds:
- node bundle.jsTimeouts
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 30m