1# Images and kernel
2
3A job runs in the image named by `ERMITE_RUNNER_IMAGE`.
4
5| Mode | Value | Contents |
6| --- | --- | --- |
7| `container` | OCI reference | Default `ermite-runner-ubuntu-26.04:latest` |
8| `vm` | Directory | `vmlinux` (`Image` on arm64) and `base.ext4`. Default `<state dir>/image` |
9
10Both come from `images/ubuntu-26.04/Dockerfile` (Ubuntu 26.04 LTS). The runner executable and action runtime Node.js are attached by the host. The image also includes system Node.js and the cached toolchains listed below.
11
12## Build
13
14```sh
15scripts/build-kernel.sh tmp/image   # vm only: builds the guest kernel
16scripts/build-image.sh tmp/image    # builds the OCI image and tmp/image/base.ext4
17```
18
19- `build-kernel.sh` downloads Linux 6.18 LTS from kernel.org and checks the tarball against the published sha256 sums. It needs `bc`, `flex`, `bison`, `pahole`, libelf and openssl headers.
20- `build-image.sh` needs Docker or Podman (rootless is fine) and e2fsprogs 1.47.1 or newer. No root is needed.
21- The OCI image is tagged `ermite-runner-ubuntu-26.04:latest`. Set `IMAGE_TAG` to change it.
22- The kernel config is `images/kernel/config-6.18` plus per-architecture fragments. The build fails if a listed option does not survive `olddefconfig`.
23- arm64 builds with `ARCH_NAME=arm64`.
24- `CONFIG_BINFMT_MISC` is built in and mounted by the guest init, so `docker/setup-qemu-action` can run foreign-architecture containers.
25
26## What the image must contain
27
28- User `runner`, uid and gid 1001, home `/home/runner`. Steps run as this user. Without it, steps run as root (test images only).
29- `/home/runner/work` and `/opt/hostedtoolcache`, owned by `runner`. The tool cache holds the toolchains listed in `images/ubuntu-26.04/toolcache.lock` for the image architecture.
30- `bash` and `sh`. `python3` and a `python` command for `shell: python`.
31- `dockerd` and passwordless `sudo` for `runner`, for jobs that use Docker.
32- No `registry-mirrors` in `/etc/docker/daemon.json`. The runner starts dockerd with `--registry-mirror` (its Docker Hub mirror), and dockerd refuses to start when an option is set both as a flag and in that file.
33- Common tools: git, curl, jq, build-essential, ca-certificates, tzdata, zip and unzip.
34
35`pwsh` is not in the image. A step that asks for it fails with `pwsh: command not found`.
36
37## Toolchains
38
39`images/ubuntu-26.04/toolcache.lock` pins Go and Node.js archives by version,
40action architecture (`x64` or `arm64`), official SHA-256 and download URL.
41To add a version, add a line for each supported architecture with the checksum
42from go.dev's download JSON or nodejs.org's `SHASUMS256.txt`, then rebuild with
43`scripts/build-image.sh tmp/image`. A checksum mismatch fails the build.
44
45The installer uses the `@actions/tool-cache` layout, including the sibling
46`<arch>.complete` marker. `actions/setup-go` with an exact version, including
47one read from `go.mod`, uses the cache only for an exact match. A range such as
48`1.27` selects the highest matching cached version. Versions not in the cache
49still download normally (and `check-latest: true` may check upstream).