Changelog

What changed in every release. The release notes explain the why.

A hammerkit server now runs work for coding agents and CI on your own machines: agents get sandboxes with the repository's files, a team gets service runs with sign-in endpoints for previews, and CI gets verified checks, all on a Docker host or a Kubernetes cluster with the credentials of service accounts. Tasks build container images with build, and a dashboard shows how a server stands. The release notes walk through it.

2.0.0 is a major release for one change: continuous is for services only.

Breaking change

  • A task with continuous is refused. Hammerkit names the task and the file. Move such a task to a container service with continuous: true: its cmds become one cmd, and it keeps its src and ports. up --watch starts it once and leaves it running, and on a service run that moves to a new commit it gets the changed files and reloads.

Upgrade notes

  • Every cache misses once. A task's cache key now covers its services and uses sha256, and its id covers which secrets it declares (by name and source, never the value). Tasks behind an aggregate task can now be cached at all.
  • A need on an included service is named after the service, with dashes for colons (services-postgres, not services:postgres), and agents see needs by their plan key (sub:db).
  • A build file that fails the schema exits with 1, and every problem of a refused publish is printed.
  • hammerkit down only stops services. 1.26 also ran every task it selected. down <service> stops that service alone, see down.
  • Field substitution reads a value once. $NAME in image, src, mounts and the other fields is replaced by its value as written, so to build one value from another, use ${NAME} in envs. pa$$word stays pa$$word.
  • Limits on what a build file can make hammerkit read: includes go at most 32 levels deep and 1,000 build files, inputs of an include at most 64 KiB, and one file parses to at most 16 MiB and 10,000 items, also for local runs.
  • Item paths: a src, output, mount, volume or secret file at /, or in a folder of / whose name starts with .hammerkit, is refused. A link that leads outside the files of a run is refused also when a task inherits the path from a dependency, and a path hammerkit can't look into is refused with the reason instead of being skipped.
  • Mount targets are no longer chowned.
  • A service without a healthcheck on Kubernetes counts as up only after it ran 10 s, and a container service that crashes more than restarts times (default 2) fails.
  • The Postgres examples read their password from EXAMPLE_DB_PASSWORD; run hammerkit clean once if they ran before.

For servers

  • Upgrade servers before clients. A 2.0 client sends maxTimeout with a run, which a 1.26 server refuses.
  • A run executes the build files of the published version, includes too, whatever the checkout holds, and plans every task before the first one starts. A git include inside a fetched git file must be pinned to a commit; a published version with such an include on a branch is refused when it runs, so publish it again with the include pinned.
  • capAdd is opt-in. A server adds Linux capabilities only where backend.capabilities allows them, in the sandboxed runtime it names. On a Docker host, a task that adds capabilities can't bind files of the run for now, and image builds are refused at publish.
  • Run variables: a run hands its tasks HAMMERKIT_RUN_REPO, HAMMERKIT_RUN_REF and HAMMERKIT_RUN_COMMIT, so runs.env may no longer set them. Plans, proposals and publishes show run variables by name (${NAME}); versions published before keep their stored plan until they are published again.
  • Several tasks named in one run (remote run a b) run as one plan side by side, longest remaining chain first, no longer in the given order. To keep an order, make one depend on the other.
  • Networks: each further service a limited task or service needs is on an internal Docker network of its own, so a host may need more address pools (default-address-pools of the Docker daemon).
  • A Kubernetes server needs delete on namespaces and the admission policy from the backend page; list on events, nodes and metrics is optional and only adds detail to failed runs and capacity.
  • Commands that take a server use the only registered server when none is named and no default is set; a remote use default that names a server no longer registered is an error.
  • If a server ran a 2.0.0-next prerelease: kept services of service runs roll their pods once, kept claims from before claims were per branch expire after keepVolumes (the first run of each branch restores from the cache), and Docker volumes of service runs from early prereleases are not swept, so remove them with docker volume rm once their runs ended.

Added

Sandboxes for coding agents

  • Sandboxes on a server: a copy of a repository an agent works in, with reading, searching and editing its files, running the build file's tasks on it, and pushing the changes to an allowed branch. On Kubernetes, commands run in a warm runner pod and each sandbox has its own egress proxy.
  • Agent clients: hammerkit remote mcp, a pi extension and an opencode plugin with tools to run tasks, read logs, check work, start service runs and open their endpoints. Guides: pi, opencode.
  • An approved run of a sandbox works on a copy of the approved tree, with a cache of its own.

Service runs

  • Service runs: hammerkit remote up starts services of a published build file on a server, with public endpoints behind the server's sign-in, a ttl and a sleepTtl. A run that sleeps keeps its volumes, and remote up with the name of a run moves it to a new commit in place.
  • Who may publish endpoints of a repository may also stop its service runs; who may only open them may extend them.

Runs on a server

  • A Kubernetes backend: tasks run as Jobs in a namespace per caller, with kept claims per branch, volumeSize, quotas that say why a pod waits, and network policies.
  • hammerkit remote run for CI jobs, with an optional source.commit pin, and verified checks: hammerkit remote verify in CI only checks that the checks for the commit's files passed on the server. Guide: verified checks.
  • Per-task arguments with runs.args, network ceilings with runs.network and runs.secretNetwork, and allowed hosts of a provider through the egress proxy.
  • --max-timeout caps every task of a run.
  • Retrying a run that is over: hammerkit remote retry, a button on the dashboard, or POST /v1/runs/<id>/retry.
  • Runs hand their tasks HAMMERKIT_RUN_REPO, HAMMERKIT_RUN_REF and HAMMERKIT_RUN_COMMIT, for previews that need their branch.
  • hammerkit remote logs, remote runs, and failed runs that name their causes, with the cluster's reason and warning events on Kubernetes.
  • remote publish --dry-run checks a build file against the server's policy without storing it, and remote up / remote run offer to publish a build file the server doesn't have.

Status and dashboard

  • hammerkit remote status, remote capacity and remote dashboard: places, the queue and why each run waits, approvals, service runs, your limits and past task timings. An observe entitlement sees every run and changes nothing.
  • A dashboard at https://hammerkit.<domain> on a server with endpoints.login: runs with their graph, timeline and logs, build files with their versions and proposals, sandboxes, and buttons to publish, reject, wake, stop and retry. endpoints.dashboard: false switches it off.

Tasks and build files

  • Image builds: a task with build builds a Dockerfile with BuildKit, with tags, push, a registry layer cache, registry logins from secrets, the digest of the pushed image as an output, and platforms. Guide: building container images.
  • capAdd on container tasks.
  • publish: false on tasks, services, includes and references keeps them out of a published version, so one build file serves local runs and a server.
  • secretProviders and secretAccounts in the host config, winning over a build file's of the same name.
  • A local include or reference can be { path, with, publish }.
  • hammerkit up [names...] and down [names...] start or stop the named services and the services of named tasks.
  • hammerkit run --no-restore only looks cache hits up and restores their outputs once a task that runs needs them.
  • Container services take restarts before they count as crashing.
  • hammerkit remote add --token-command keeps a token command per server in the host config, and remote login / remote logout take an optional server name.
  • Secret errors name the task or service, the secret and the account, and say what to add where.

Changed

  • Archives are packed one file at a time, and a hard link is packed as a link only when its file id is exact, so Windows no longer restores two files with each other's content.
  • Each output of a task gets its own folder in its Kubernetes claim, and an output with a file extension is a file there, as on Docker. A file output must be written in place (BusyBox cp onto it fails).
  • A src inside a folder of another src is part of that folder's upload and mount on Kubernetes, as on Docker.
  • A file a container task generates reaches the container tasks that depend on it.
  • Output is masked line by line across chunks, and registry credentials go only to the registry's own origin.
  • Sandbox commits by an account without a name are authored by the local part of its email.

Fixed

  • A service with more than one port on Kubernetes.
  • hammerkit server exited on SIGHUP; it now reloads its entitlements.
  • hammerkit github-app-token says why it failed, hammerkit --version prints the bare version, and log lines show the day of the month.
  • The init task of an included service reaches it by a host name instead of a link Docker refused.
  • A crash-looping service on Kubernetes fails in time instead of waiting out its timeout.
1.26.0

Features

  • pass arguments to a task or service after -- (#95)
1.25.0

Features

  • server: redesign remote compute around accounts, repositories and isolated runs (#90)
1.24.0

Features

  • remote compute server with OAuth, published build files and approvals (#84)
1.23.0

Features

  • secret providers read as service accounts, per-run secret masking (#85)
1.22.0

Features

  • add tsc, eslint, prettier, jest and helm to the catalog and remove best-practices (#88)
1.21.2

Bug Fixes

  • restore transitive dependencies when a dependent task re-runs (#79)
1.21.1

Bug Fixes

  • let fetch set content-length for registry blob uploads (#77)
1.19.1

Bug Fixes

  • mount the go and cargo caches from the home directory (#72)
1.19.0

Features

  • add pip, go and cargo to the catalog (#68)
1.18.0

Features

  • explain --definition shows a task's resolved definition and where it came from (#65)
1.17.0

Features

  • includes pull refreshes remote includes, clean --cache purges them (#64)
1.16.0

Features

  • add a catalog of tested tasks with npm, yarn and pnpm install (#63)
1.15.0

Features

  • extend carries the base file's envs and can reset inherited values (#62)
1.14.1

Bug Fixes

  • a task extending a chain of tasks inherits every base once (#61)
1.14.0

Features

  • include build files from a git repository, with inputs (#60), closes #26
1.13.0

Features

  • cli: explain --check exits 1 when a task would be a cache miss (#56)
1.12.0

Features

  • container resource requests and limits (#53), closes #18
1.11.3

Includes 1.11.2, which has no release of its own.

Fixed

  • A service's init never comes from the cache. A recreated service used to skip its init and lose the state the init sets up (roles, buckets, replica sets) while the run reported success. Neither the default cache method nor --cache re-enables the init's cache now.
  • A service's dependencies run only when the service starts. They always ran, even when every task needing the service was a cache hit, so a cached run still reset the service's data. They run once the service is starting and are skipped when it ends without starting, or when all their dependents are outside the run.
1.11.1

Fixed

  • Env references in service volume names. A volume such as ${DATA_PREFIX}-db:/data resolves $NAME and ${NAME} from the service's envs before it is split into name and path, so a volume can be named per CI job on a shared docker host, and a value containing a colon no longer breaks the split.
1.11.0

Upgrade notes

  • A service's init names a task. init is a task reference (name or prefix:name, as in deps) instead of an inline block. The init task has everything a task has (deps, envs, secrets, mounts, extend, local tasks) and shows in the run like any task.

Added

  • Service init: a one-shot task that runs once the service passed its healthcheck and before anything needing it starts. It reaches the service by name, fails the service when it fails or exceeds its timeout (init.timeout, HAMMERKIT_INIT_TIMEOUT, 5 minutes), and runs on every start.
  • secrets for tasks and services, sourced from env:NAME or file:path and injected as an environment variable or a read-only file. Values are read when the item starts, never planned, cached or logged, and every value hammerkit read is masked in its output. cache: true adds a salted, checkout-independent digest to the cache key.
  • A service's container is named after the service, so it resolves its own name.
  • Mounts and volumes take :ro (readOnly: true for object volumes).
  • export: always copies a failing task's outputs to the host too, so test reports and videos survive a failed run.
  • --set NAME=value on every command supplies $NAME and ${NAME} ahead of the shell and .env files.
  • up --daemon --wait start returns once the containers started, without waiting for the healthchecks of services nothing else in the run needs.

Changed

  • Host ports of a service are published on hammerkit up, and during run only when a local task needs the service, so two runs on one host don't collide on a port.
  • Service containers carry a hash of their definition: up and run recreate a running service whose definition changed instead of reusing it.
1.10.0

Environment values can be composed and given defaults, so one build file serves laptops, cloud workspaces and CI without wrapper scripts exporting placeholders.

Upgrade notes

  • ${NAME} inside an envs value is now replaced. A value that contained a literal ${…} used to be passed through unchanged; it is now interpolated, and fails as missing if NAME is set nowhere and has no :-default.
  • A variable set to an empty string counts as set. export NAME= used to fail with missing environment variable NAME; it now passes an empty value, and an empty process variable takes precedence over a .env file value.

Added

  • ${NAME} and ${NAME:-default} in envs values: from the shell or .env, else a literal of the same envs, else the default. Fields such as image also accept the ${NAME} form. See interpolation.
  • A warning when an image pinned by digest is present for another CPU architecture than the docker host's, which makes it run emulated; it names the command that removes the copy so the native one is pulled.
  • The CI migration guide covers targeted runs against services that stay up, and local development on the same services.

Fixed

  • Running one task of several that share a service never finished. A shared service (one database for two targets) waited for every task and service in the build file that needs it, including those outside the run, which never start or end; the task completed and hammerkit then kept the services up until stopped. Only what is part of the run counts now.
  • Registry caches couldn't delete entries on registries that scope tokens per action, such as GitLab's: cache prune and clean --cache failed with 401. The token request now includes the actions the registry's challenge names.
  • The migration guide said every $NAME had to be set, including those of tasks a job doesn't run; only the tasks in the run need theirs.
1.9.2

Fixed

  • Private images couldn't be pulled. hammerkit pulled task and service images without credentials, so an image from a private registry only worked when it was already present locally, and failed with access forbidden otherwise. Pulls now use the credentials docker login stored for the registry (credential helpers, auths and credsStore in the docker config, like the registry cache).
  • Images pinned by digest were pulled on every run. An image referenced as name:tag@sha256:… is now used when an image with that digest is present.
1.9.1

Fixed

  • A fully cached run with chained services never finished. When a service that another service needs (api needs db) wasn't started because every task needing it was a cache hit, it stayed pending, so the services it needs waited for it forever. hammerkit then stopped with hammerkit stopped before the run finished and exit code 1. A service that isn't started now ends right away, with the reason not-started in --summary-json state where it used to stay pending.
  • The Compose test stacks section of the CI migration guide explains that a service name resolves only for direct needs.
1.9.0

Services now behave like their Compose counterparts. They can run in the image's working directory and through a shell, their healthchecks run as the service's own user, and a service that never becomes ready fails the run instead of hanging it. A run also cleans up after itself: no paused task containers, and no services or local processes left behind when it's stopped.

Upgrade notes

  • A healthcheck that doesn't pass within 20 seconds fails the run. Before, the run waited until you cancelled it. Give slow starters a longer healthcheck.timeout (timeout: 90s), or raise the default for every service with HAMMERKIT_HEALTHCHECK_TIMEOUT. See timing and failure.
  • Healthchecks run as the user of the service's main process, starting one second after the container. A check that relied on root inside a container whose entrypoint drops privileges has to work as that user now.
  • Container tasks re-run once. Their cache state moved out of the paused container into ~/.hammerkit/state, so the first run after upgrading misses the local cache for each container task. Entries in remote caches are unaffected. The paused containers of earlier versions are removed when their task next runs, or by hammerkit clean.

Added

  • workdir on container services: the working directory inside the container, for images whose command relies on their own WORKDIR. It applies to Docker, Kubernetes and hammerkit package.
  • shell on container services: runs cmd and the healthcheck as <shell> -c "<cmd>", so pipes, && and variable expansion work as in a Compose CMD-SHELL.
  • healthcheck.timeout with a 20s default, and HAMMERKIT_HEALTHCHECK_TIMEOUT. On Kubernetes the clock starts once a pod runs, so image pulls don't count.
  • validate warns about build-file envs a task never references: they are part of every task's cache key, so changing one reruns every task in the file. See cache key.
  • HAMMERKIT_STOP_TIMEOUT_MS (default 10s): how long a local task's processes get to exit after a run is stopped before they are killed.
  • The CI migration guide covers what a GitLab pipeline with a Compose test stack needs: tasks running without root, one C library per dependency tree, outputs inside source folders, GitLab runners, and a Compose test stacks section.

Changed

  • A container task's container is removed when the task ends, so docker ps no longer lists one paused container per task. Its state is recorded in ~/.hammerkit/state (ADR 0007).
  • SIGTERM and SIGHUP stop a run the way Ctrl-C does. Before, hammerkit exited at once and left services and local processes running.
  • hammerkit clean also removes containers that runs killed outright on this machine left behind, in any project. Services started with up --daemon stay.

Fixed

  • Stopping a run left its services running. Ctrl-C during a run with a service crashed hammerkit with an unhandled AbortError before it removed the service container.
  • A local process ignoring SIGTERM outlived the run. The whole process group is now killed after HAMMERKIT_STOP_TIMEOUT_MS.
  • A healthcheck could lock a service out. Checks ran as root from the first second, so a CLI such as rabbitmq-diagnostics created files (the Erlang cookie) the server, running as its own user, could no longer read.
  • validate printed every finding again after each new one; each finding is printed once.
1.8.0

The documentation moved to hammerkit.dev and gained a tutorial for each of six languages, every one of them run by hammerkit's own tests. hammerkit itself no longer reports a failed or unfinished task as a success, and works with GitLab's Docker-in-Docker service.

Upgrade notes

  • Outputs start empty when a task runs. Before a task's commands run, hammerkit now deletes what an earlier run left in its outputs (resetOnChange defaults to true). Set resetOnChange: false on an output a tool builds on incrementally, such as Cargo's target. An output that is also a source of the task, or contains one, is left alone. See outputs start empty.
  • Kubernetes environments expose services through Gateway API HTTPRoutes only. The ingresses list is replaced by httpRoutes, whose entries need a gateway; a build file still declaring ingresses is rejected with a pointer to the new key. Install the Gateway API CRDs in the cluster, and delete Ingresses created by earlier versions yourself: kubectl delete ingress -n <namespace> -l hammerkit.dev/id. See HTTP routes.
  • Grouping tasks report cached. A task without cmds that only groups others (ci: { deps: [test, build] }) is reported as cached when every one of its dependencies was a cache hit, so a fully cached run shows a 100% cache hit. Scripts reading --summary-json see cached where they saw executed. Which tasks run is unchanged.
  • A task failing before its commands stops the run, as a failing command always did. That covers errors while checking the cache, such as an unreachable Docker daemon. Previously the other tasks carried on.
  • Documentation pages moved. If you saved the prompt for the CI migration guide, point it at https://hammerkit.dev/llms.mdx/docs/guides/migrate-ci/agent-guide/content.md.

Added

  • Tutorials for Node.js, Python, Go, Rust, Java and .NET. Each takes a small project from an empty build file to a cached ci task, starting with a task that only downloads dependencies (npm ci, pip install, cargo fetch, mvn dependency:go-offline, dotnet restore). The projects are in examples/, and the integration tests run each one and require its second run to come entirely from the cache.
  • hammerkit.dev replaces the GitBook documentation: search, a changelog, and every page as Markdown for coding agents (/llms.txt, /llms-full.txt).

Changed

  • A task's outputs start empty when it runs, so files a deleted source used to produce or a failed run left behind no longer end up in the next result and the cache. This applies to local and Docker tasks; tasks running on Kubernetes keep their previous behaviour.
  • Updated the Kubernetes client (@kubernetes/client-node 0.20 → 2.0). hammerkit no longer prints a punycode deprecation warning on every command.
  • Ingress support is removed: an environment's httpRoutes create Gateway API HTTPRoutes, the successor to Ingress, attached to the gateway they name.

Security

  • tar 7: hammerkit unpacks cache entries, including ones pulled from shared remote caches, with tar, and up to 7.5.20 a crafted archive could overwrite files through hardlinks or stall the extraction.
  • dockerode 4.0.12 (its tar-fs could extract outside the target directory), minimatch 6.2.3, yaml 2.9.1 and chokidar 3.6 with patched picomatch and brace-expansion: denial-of-service fixes.

Fixed

  • A task that failed could be reported as cached. A local task whose command failed was recorded as if it had succeeded: the next run reported it cached, and cache push uploaded it, so every machine pulling the entry skipped it, and a failing test passed. A container task that failed after an earlier successful run with the same inputs (for example with --cache none) kept that run's record, so the next run reported it cached with the failed run's files in its outputs.
  • resetOnChange: true didn't reset Docker outputs while any container still mounted the output's volume, such as the task's own or a dependent's paused container from an earlier run: Docker refuses to remove a volume in use, and hammerkit logged a warning and kept the old content. Outputs are now emptied in place.
  • A cache hit restores exactly the stored outputs. Restoring a task from a cache now replaces its output folders and volumes instead of unpacking into them, so files a failed or older run left behind don't survive a cache hit.
  • On Linux, container tasks had no writable home directory. They run as your user, which has no home in the image, and Docker sets HOME=/: npm, the .NET SDK, Go and Maven failed to create their caches. Such a task now gets HOME=/tmp unless its envs set HOME.
  • A DOCKER_HOST pointing at a TCP address was ignored, so hammerkit couldn't reach GitLab's docker:dind service or any remote daemon, and every container task failed with an empty error message. A docker.host in the build file still takes precedence.
  • A run could exit with code 0 without running anything. When a task failed before its commands, for example because the Docker daemon was unreachable, the tasks depending on it waited forever, and hammerkit stopped with no output and exit code 0, so CI reported success. The run now fails with that task's error, and a run that ever ends without finishing exits with code 1 and hammerkit stopped before the run finished.
  • A container task whose sources include a path inside another of its sources (often a dependency's app/app.csproj under the task's own app) mounted that path twice. On Docker Desktop the folder then couldn't be deleted while hammerkit kept the task's container. It is mounted once now.
  • The GitLab CI example in the installation guide works: it clears the image's entrypoint, which GitLab requires, and points DOCKER_HOST at the docker:dind service.
1.7.0Release notes →

A detailed summary about the release and the reasons behind the changes can be found in the release blog. For the recommended setup, see agents, workspaces and CI.

Upgrade notes

  • One full rebuild after upgrading. Cache keys are now computed from project-relative paths (see below) and include the CPU architecture and the definitions of a task's dependencies, so every existing cache entry misses once.
  • More files count as sources. Globs now match what they say (see Fixed), so a task may see source changes it previously missed, and run.
  • A src that matches no file makes a task always run, like a task without src, and hammerkit warns about each such entry.
  • A task needs src of its own to be cached. A task without src whose dependencies declare src (a test task depending on build) used to be cached on its dependencies' sources alone, so changing only its own files (the tests) left it cached. It now always runs; declare the files it reads.
  • Tasks without src always run. A task with no src — and every task depending on one — runs on every invocation, as documented. Earlier versions cached such a task after its first run.
  • Dependencies of cached tasks are skipped. A task pulled into a run only as a dependency no longer runs when every task depending on it is a cache hit, so its outputs (e.g. an exported dist) aren't produced. Request the task explicitly or pass --no-skip-deps to run the whole graph as before.
  • Explicit cache pull/push fail on backend errors. The s3 backend now distinguishes a missing entry from a transport or credential error. Builds are unaffected: they still treat a backend error as a cache miss with a warning.

Added

  • registry cache backend: store cache entries in any OCI registry (GHCR, Docker Hub, ECR, GAR, Artifactory, registry:2) using your existing docker login credentials, including credential helpers. See caches.
  • hammerkit cache pull / cache push --remote <name>: move the current commit's cache entries between the local cache and a remote cache without running tasks — warm a workspace before building, publish results after. See cache pull / push.
  • Read-only cache mode: --cache-read-only on run/up, or HAMMERKIT_CACHE_READ_ONLY=1, restores from cache backends but never writes to them; cache push refuses to run.
  • Cache retention: a retention block on caches (maxAge, maxSize, keepPerTask), hammerkit cache ls and hammerkit cache prune (with --dry-run). Local caches with a policy are pruned automatically after every successful run; remote caches only with --remote. See retention.
  • Skipping dependencies of cached tasks, with --no-skip-deps to opt out. See dependencies of cached tasks.
  • Task timeouts: timeout on a task and --timeout as a default on run/up. A timed-out task fails, is cleaned up and writes no cache entry. See timeouts.
  • hammerkit explain [task] (with --json) reports whether each task is a cache hit or miss and which input caused a miss; run --explain prints the cause inline. See explain.
  • run --dry-run prints the execution plan with predicted cache hits and misses.
  • End-of-run build summary with the cache hit ratio (--no-summary, --summary-json).
  • hammerkit graph [task] prints the build graph as mermaid or dot. See graph.
  • A guide for coding agents that rewrites an existing CI pipeline into a hammerkit build file. See migrate CI with an agent.
  • The caching docs list what the cache can't see and how to check a build. See caching limitations.

Changed

  • The npm package ships only the CLI (dist) and build.schema.json: about half the size of 1.6.0, without test files or source maps.
  • Cache keys no longer depend on where the project is checked out. Paths in a task's or service's cache identity are relative to the project root (the git root, or the main build file's directory), so a laptop, a CI runner and an agent sandbox share cache entries. Machine-local runtime state (Docker containers, staging directory) stays scoped per checkout, so worktrees on one machine never share running containers. See ADR-0006.
  • The built-in default cache is now actually shared between checkouts on the same machine, as documented.
  • A service is only started when a task that needs it actually runs; cache hits don't start their services.

Fixed

  • Cache hits after a change — several ways a task was reported as cached although an input it reads had changed:
    • Globs only looked at the top directory: src/**/*.ts ignored every file in a subdirectory, and **/*.ts matched nothing at all.
    • Globs using ?, [...], {a,b} or extglobs, a * inside a file name (src/app*.ts) and globs with environment variables ($DIR/*.ts) matched nothing.
    • Binary sources were compared as text, so two different images or fonts could look identical.
    • Changing a dependency's cmds, envs or image rebuilt the dependency but not the tasks depending on it; with skipped dependencies, not even the dependency.
    • Deleting a task's output (rm -rf dist) left the task cached without the output.
    • A src entry with a typo kept its task cached forever.
  • A cache hit of a container task now restores its exported directories and its file outputs on the host. Previously only its volumes were restored, and file outputs were not stored at all.
  • A task whose src includes what a dependency generates now has the same cache key before and after the dependency ran, so a clean checkout (CI) hits entries pushed from a built workspace (an agent).
  • Cache keys no longer depend on the order in which the filesystem lists files, which differs between machines.
  • Cache entries (description.json, pushed to remote caches) and the local explain records no longer contain env values in plain text — only a digest.
  • Tasks running on Kubernetes now wait for their job to finish and fail when it fails. Previously a task was reported as completed as soon as its job was created. Cancelling a run (or a timeout) now deletes the running job.
  • Restoring a container task from a cache backend or store/restore now writes the outputs into the task's volumes. Previously they were written into a throwaway container and lost, so the task reported a cache hit with empty outputs.
  • A task that needs a service no longer fails the run when it is a cache hit.
  • A needed service that fails to start (missing image, port already in use) now fails the run immediately instead of hanging forever; service errors and crashes count as run failures.
  • cache push uploads outputs that are current in the checkout even when they were never stored in the local cache.
  • Stopping a local task — on a timeout or Ctrl-C — now stops every process its commands started. Previously only the shell was stopped: on Linux (where sh is dash) and for compound commands everywhere, the command kept running and the task waited for it to finish on its own.
  • A local task printing more than 1 MB of output is no longer killed.
  • A Kubernetes task keeps the job of its last run, so an unchanged task is reused in place instead of being restored from the cache backend on every run.
  • Running several commands in one process (getCli, tests) no longer leaks log output of one run into the next command's output.
  • A container service's image substitutes environment variables (image: $POSTGRES_IMAGE) like a task's image does.
  • build.schema.json is regenerated and matches the build-file schema again (continuous, service ports, registry backend).

A detailed summary about the release and the reasons behind the changes can be found in the release blog.

Added

  • Pluggable cache backends with automatic pull/push. A new top-level caches: block declares a cache with a method and a backend (local or s3). Tasks reference a cache through the cache field.
  • Run tasks and services on a Kubernetes cluster through a new environments: block, selected with the --env argument. Tasks run as jobs, container services as deployments.
  • Store and restore now work against a Kubernetes environment via --env.
  • Service healthchecks are translated into Kubernetes readiness and liveness probes.
  • Exportable generated files via generates: [{ path, export: true }], copying outputs back into the workspace.
  • Services can declare deps and needs, support parallel usage and named references.
  • New up and down commands to start and stop services directly.
  • Local tasks receive connection details of needed services as environment variables (HAMMERKIT_<NAME>_HOST, HAMMERKIT_<NAME>_PORT, HAMMERKIT_<NAME>_PORT_<containerPort>).
  • Optional namespace for Kubernetes services.

Changed

  • The default cache method is now checksum in all environments (previously modify-date locally, checksum only in CI). This pairs with remote backends — only content checksums are stable across machines — and removes the local/CI cache mismatch. Behavior change: set cache: modify-date (or --cache modify-date) explicitly to keep the old local behavior.
  • Introduced a runtime abstraction so the same build file runs on the local docker daemon or on Kubernetes.
  • Kubernetes port-forwarding no longer requires the kubectl binary; ports are forwarded through the kubernetes client.
  • Internal rename of the "node" concept to "task".

Fixed

  • Build graphs that mix deps and needs in a cycle are now detected instead of deadlocking.
  • Local tasks use a pid file to prevent concurrent runs of the same task; stale pids are swept automatically.
  • A crashing docker service is reported as a crash instead of terminating silently.
  • Improved error handling when a configured cluster is missing.
  • Various stability fixes for environment file replacement and Windows test runs.
1.5.0Release notes →

A detailed summary about the release and the reasons behind the changes can be found in the release blog.

Added

  • Services: long-running dependencies a task can need. Hammerkit starts them, waits for an optional healthcheck, and stops them when no longer needed.
  • Container services, run in the same network as container tasks with automatic DNS by service name.
  • Kubernetes services, forwarding pods/services/deployments from a cluster into a task.
  • Labels on tasks and build files, with --filter/-f and --exclude/-e to scope a command to a group of tasks/services.
  • New ls command to list all tasks and services.

Changed

  • CLI start-up is faster: build files (including references/includes) are now parsed lazily, only when a task executes or ls runs, instead of on every invocation.
1.4.0Release notes →

A detailed summary about the release and reason behind the made changes can be found in the release blog.

Added

  • Added a missing license file to the repo (MIT)
  • Added a best-practices folder to the repo with examples how to use hammerkit
  • Added a port list for docker tasks to map container ports to the local machine
  • Added a Linux and macOS test runner to the CI

Changed

  • 3 new logging modes (interactive, live, grouped). Interactive is the default mode, except in CI environments, which use live.
  • The watch flag gets removed from the task definition in favor of the new --watch argument. This allows hammerkit to watch the entire dependency chain and restart dependent tasks.
  • Move the local cache dir .hammerkit into the user directory. Removing the need to exclude it from the source code or builds.
  • Docker tasks use volumes instead of mounts for generated files. Increasing stability and performance hugely. Reducing conflict with local development environment and the --no-container flag.
  • The source code got updated to node version 16, since it will be soon the next LTS. The upgrade was needed to take advantage of the new AbortController. Hammerkit requires at least node version 15.
  • Replaced all usage of the defer class with the AbortController, which caused issues with unhandled promises on newer node versions.
  • Store and restore format has changed for docker tasks, because of the changes to generated files and the usage of volumes.

Fixed

  • Docker tasks on windows sometimes got stuck, because the docker daemon did not close the stream. The status of the container gets now regularly polled, to handle this exception.