hammerkit

Image builds

Build a Dockerfile in a task with `build`, as docker build does: on a dev machine, in CI and on a hammerkit server, and push the image with a login whose password is a secret.

A task with build builds a Dockerfile, like docker build. Hammerkit runs the build with BuildKit, the builder behind docker build, in a container of its own. The same task builds on your dev machine, in CI and on a hammerkit server, where no task gets a Docker daemon.

.hammerkit.yaml
tasks:
  image:
    description: build the app image and push it
    build:
      context: app                      # docker build app
      tags: ghcr.io/acme/app:latest     # --tag
      push: true                        # --push

That is the whole task: hammerkit writes its image and its command. A task with build has no image, cmds or shell of its own.

The fields

FieldDefaultWhat it does
context.The folder sent to the build, relative to the build file.
dockerfileDockerfile in the contextThe Dockerfile, relative to the build file. It may be outside the context.
tagsnoneThe names of the image with their tags, one or a list, as --tag. Without tags the build only checks that the Dockerfile builds.
pushfalsePushes the image to the registry of each tag. Needs tags.
cachenoneAn image in a registry, such as ghcr.io/acme/app:buildcache, that the build reads its layers from first and writes them to after. A build in a new place (a CI runner, a pod) then starts from the layers of the last one.
digestnoneA file the task writes <image>@sha256:… to: the image it pushed, by its digest. Needs tags.
loginnoneSign-ins to registries, see Signing in.
insecurefalseThe registries of the tags and the cache speak plain HTTP, as a registry:2 on a network of your own does.
platformsthe machine'sThe platforms of the image, one or a list such as linux/amd64 and linux/arm64, as docker build --platform. See Several platforms.

$NAME and ${NAME} take the value of an environment variable in every field but login.registry and platforms, as in image of a container task:

envs:
  REGISTRY: europe-west4-docker.pkg.dev/acme/apps
tasks:
  api:
    build:
      dockerfile: api/Dockerfile
      tags: $REGISTRY/api:main
      cache: $REGISTRY/api:buildcache

The task takes the other fields of every task: deps, needs, src, generates, envs, secrets, account, network, resources, timeout, cache, labels, runner, publish, and volumeSize of a container task. Its envs and secrets can't set PATH, LD_*, BUILDKIT*, BUILDCTL* or HAMMERKIT_REGISTRY_*: hammerkit runs BuildKit's programs, not ones a variable names. It doesn't take extend, and no task can extend it. It takes no arguments after --.

Sources and caching

Like docker build, the task reads its context. When the task has no src, its src is the context, and the Dockerfile where that is outside of it. A context of . is the whole folder, so any change in it builds the image again. List src to name what the Dockerfile copies instead, and the task builds again only when one of them changes:

tasks:
  api:
    build:
      dockerfile: api/Dockerfile        # the context is ., the repository
      tags: ghcr.io/acme/api:main
      push: true
    src:                                 # what api/Dockerfile copies
      - api/Dockerfile
      - .dockerignore
      - package.json
      - package-lock.json
      - api/src

With src, only those paths are in the task's container, so list the Dockerfile and .dockerignore too. A COPY of a path that isn't in src fails the build with not found.

A context, or a folder in it, that a task in deps generates is read from that task's output: the build gets what the dependency made there, such as a dist it compiled or a Dockerfile it wrote, as any task that depends on it does.

tasks:
  dist:
    image: node:24-alpine
    src: [src, package.json, package-lock.json]
    generates: [dist]
    cmds: [npm ci, npm run build]
  image:
    deps: [dist]
    build:
      tags: ghcr.io/acme/app:main      # the Dockerfile copies dist/
      push: true
    src: [Dockerfile, .dockerignore]

A task whose sources didn't change is a cache hit and doesn't run: the image of those sources is in the registry already. Set cache: none on the task to build on every run.

Deploying the image by its digest

digest writes the name of the image with the digest the registry has for it, for a task that deploys exactly that image. The file is an output of the build, so a task that depends on it reads it, in its container too, and a cache hit brings it back:

tasks:
  image:
    build:
      tags: europe-west4-docker.pkg.dev/acme/apps/api:main
      push: true
      digest: .images/api                # europe-west4-docker.pkg.dev/acme/apps/api@sha256:…

  deploy:
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
    deps: [image]
    cache: none
    cmds:
      - gcloud run services update api --region europe-west4 --image "$(cat .images/api)"

The digest names the image even after main moves on to a newer one. Without push it is the digest of the image BuildKit built, which no registry has.

A build with cache: none pushes a new image on every run, and a new image has a new digest. A task that reads the file of such a task therefore always runs too, as if its cache were off: a cache hit would bring back what it made from an older digest.

Signing in to a registry

A push, and a cache in a private registry, need a sign-in. Each entry of login names the registry, the user and the password, which is a secret: from and account as there, never the password itself.

tasks:
  image:
    build:
      tags: ghcr.io/acme/app:latest
      push: true
      login:
        - registry: ghcr.io
          user: acme-ci
          password: { from: 'env:GITHUB_TOKEN' }   # the workflow's, with packages: write

The password is a variable of the task's container, masked in its logs, and the build reads it from a Docker config the task writes for itself: neither your own docker login nor the one of the machine is used. What the user is depends on the registry:

Registryregistryuserpassword
GitHub (GHCR)ghcr.ioany namethe GITHUB_TOKEN of a workflow with packages: write, or an installation token of a GitHub App, never a personal token
Google Artifact Registry<region>-docker.pkg.devoauth2accesstokenan access token of a service account (gcloud auth print-access-token)
Amazon ECR<account>.dkr.ecr.<region>.amazonaws.comAWSaws ecr get-login-password
Azure Container Registry<name>.azurecr.io00000000-0000-0000-0000-000000000000az acr login --name <name> --expose-token --query accessToken -o tsv
Docker Hubdocker.ioyour organization's namean organization access token, never one of your own Docker ID

The tokens of Google, AWS and Azure expire within hours: print them with a secret provider, read as a service account, so no key is in a file. On a server that is the account of the operator, as in Building container images.

The network

A build reaches what its task reaches. With a network allow list the build goes through the task's egress proxy: hammerkit hands the proxy to the RUN steps of the Dockerfile too, as the HTTP_PROXY, HTTPS_PROXY and NO_PROXY build arguments. These don't change the image or its layers. List what the build reaches: the registry it pushes to, the one of each FROM, and what the RUN steps download.

tasks:
  image:
    build:
      tags: ghcr.io/acme/app:latest
      push: true
    network:
      allow:
        - ghcr.io
        - pkg-containers.githubusercontent.com   # where ghcr.io keeps the layers
        - registry-1.docker.io                   # FROM node:24-alpine
        - auth.docker.io
        - production.cloudflare.docker.com       # Docker Hub's layers, from its CDNs or S3
        - production.cloudfront.docker.com
        - docker-images-prod.s3.dualstack.us-east-1.amazonaws.com
        - dl-cdn.alpinelinux.org                 # RUN apk add
        - registry.npmjs.org                     # RUN npm ci

A registry the task needs as a service, such as a registry:2, it reaches by the service's name, as any task does.

Several platforms

With platforms, one build makes an image for each platform and pushes them under the same tags, as a list that docker pull picks the platform of the machine from:

tasks:
  image:
    build:
      tags: ghcr.io/acme/app:main
      push: true
      platforms:
        - linux/amd64
        - linux/arm64

A RUN step for a platform other than the machine's runs in the QEMU emulator that comes with BuildKit's image, so neither your dev machine nor a server needs an emulator of its own. An emulated RUN step is several times slower than a native one. Where the steps compile, let the compiler of the machine's platform build for the other one instead: FROM --platform=$BUILDPLATFORM for the build stage, and $TARGETOS and $TARGETARCH for the compiler, as in GOOS=$TARGETOS GOARCH=$TARGETARCH go build. Only the stage the image ends up with then runs for each platform.

digest gets the digest of the list, which a deployment pulls the right platform from. cache keeps the layers of every platform.

Where it runs

BuildKit mounts the layers it builds, which a container can only do with the capability SYS_ADMIN.

  • On a dev machine and in CI, hammerkit runs BuildKit's container privileged, as docker buildx runs its own BuildKit. That has the rights of the Docker daemon, which you have already. Its layers stay in a volume of the task, so the next build of the task starts from them; hammerkit clean removes it. The image is pushed, not loaded into your Docker: build with tags and push, then docker pull it to run it.
  • On a server with a Kubernetes backend, the task adds SYS_ADMIN, which the server grants only in a sandboxed runtime such as gVisor, where the capability reaches the sandbox's kernel and not the machine's. Its operator allows it once in backend.capabilities. The layers are in memory: give the task resources with enough memory for them, and cache so a build starts from the layers of the last one. Building container images sets a server up for it. A server on a docker host (backend: { type: host }) doesn't build images yet: it refuses a task with build at publish, see the guide.
  • In a Kubernetes environment of your build file, without a server, the pod of the task gets SYS_ADMIN and nothing more, which BuildKit's RUN steps don't run with outside a sandbox. Build images there on a server, or with Docker.

The BuildKit image is pinned (moby/buildkit:v0.25.1), so a build file builds with the same BuildKit everywhere.

When it fails

What you seeWhat it means
push needs tags or digest needs tagspush and digest need the names of the image.
build tag "…" is no image nameA tag, after the variables are in it, has a space, a comma or a quote.
PATH, … can't be set on a task with buildenvs and secrets of a build task don't name PATH, LD_*, BUILDKIT*, BUILDCTL* or HAMMERKIT_REGISTRY_*, which would change the programs BuildKit runs or the passwords of its logins.
failed to compute cache key: … not foundThe Dockerfile copies a path that isn't in the task's src.
401 Unauthorized or 403 Forbidden on the pushThe login is missing, names another registry than the tag, or its password can't push there.
RUN steps can't download (temporary error from apk, ECONNREFUSED from npm)The host isn't in the task's network (and, on a server, its runs.secretNetwork).
builds an image, which a server builds only with a kubernetes backend for nowThe server runs tasks on a docker host, which doesn't build images yet. Build on a server on Kubernetes, or in CI.
adds the capability SYS_ADMIN, and this server allows noneThe server has no backend.capabilities, see the guide.

On this page