Dependencies
A task can depend on other tasks, which run first (unless they are cached).
Every task can have a list of dependencies. They run before the task, and if any of them fails, all pending tasks are aborted. Dependencies can be chained as deep as needed, as long as there is no cycle.
tasks:
install:
cmds:
- npm install
build:
deps: [install]
cmds:
- tsc -b
publish:
deps: [build]
cmds:
- npm publishDependencies run in parallel
Dependencies that don't depend on each other run concurrently, up to the
--concurrency worker count (default 4). In the example above install must
finish before build, but if two branches of the graph are independent they
execute at the same time. A dependency that fails stops the whole run; see
parallelism and exit codes in the CLI reference.
Which ready task runs first
When more tasks are ready than there are free workers (or, with
resource requests, than there is room), hammerkit starts the
one on the longest remaining chain first. A task's chain is its own expected
duration plus that of the longest line of tasks that wait for it, through the services
that need it too. The tasks at the start of a long chain, such as the install and
build before a slow e2e, go before a short task nothing waits for, such as lint,
which still fits in later.
The expected duration of a task is the median of the last 5 times it ran on this
machine, kept in durations/ of hammerkit's directory (~/.hammerkit on Linux,
~/Library/Application Support/hammerkit on macOS, HAMMERKIT_DIR when set). On a server, it is the median of its
last 9 successful runs in the same repository. A task that never ran counts as the
median of the others, and with no history at all every task counts the same, so the
chain is counted in tasks. A task that only groups others, and one already taken from
the cache, count nothing. Tasks that are equally urgent start in the order they became
ready.
Dependencies of cached tasks
A dependency only runs when a task that needs it has to run. If every task
depending on it is a cache hit, it is skipped: when e2e is cached,
hammerkit run e2e doesn't rebuild the app e2e was tested against. Skipped tasks
show up as skipped in the build summary.
Tasks you ask for — by name, or selected with a label filter
— always run (or restore from the cache); only tasks pulled in purely as
dependencies are skipped. A service's dependency runs once the service starts,
so when every task needing the service is a cache hit, neither the service nor
its dependencies run. Under up and in watch mode everything runs.
A task that has to run restores its whole dependency chain, not only its direct
dependencies. With install ← build ← test, a changed test runs against a
cached build, and install is still restored from the cache (shown as cached)
because test may need its outputs, for example node_modules, at run time.
A skipped dependency leaves no outputs in the workspace. If you need them — for
example an exported dist — request that task too, or pass --no-skip-deps to run
the whole dependency graph as in earlier versions.
Aggregate tasks
A task with deps and nothing else to do groups other tasks under one name: no
image, no cmds, no src, no generates, no secrets and no needs.
tasks:
build:all:
deps: [build:api, build:web]
test:unit:
image: node:24-alpine
deps: [build:all]
src: [test]
cmds:
- npm testAn aggregate runs nothing, so it needs no runtime and no image, and writes nothing to its directory:
- a task that depends on it gets what its dependencies generate (
node_modules,dist), as if it depended on them directly; - it is up to date when all its dependencies are, so a task that depends on it can be a
cache hit, and it has a check key when they do.
Asked for by name, it still checks its dependencies and restores their outputs, and is
reported
cachedwhen all of them were; - a server runs it whatever
runtimesallows, and--networkdoes not need to limit it.
A task with deps and its own cmds or src but no image is a local task as before.
Referenced and included tasks are addressed with the prefix:task syntax in
deps, for example deps: [npm:install]. See
references and includes.
Make sure to set up correct caching to speed up your execution and prevent unnecessary work.