docs(ci): recommend host-level nix store GC + min-free for CI disk pressure

Store GC is a host-level concern (the CI runner builds through the host
nix-daemon; the container shares the host store with no daemon of its own).
A service module should not change the host's global nix-daemon options, so
document the daily GC + disk-pressure min-free/max-free as a recommendation
for the operator's own host config instead. Notes the remote-builder caveat:
GC must be applied wherever the builder's store lives.
This commit is contained in:
atlas 2026-06-08 19:32:14 +02:00
commit b7eb0f3930

View file

@ -82,6 +82,42 @@ For repos with external contributors or fork PRs:
The current design is appropriate for a trusted-team hive where all contributors have implicit forge access.
## Host store maintenance (recommended)
The CI runner builds derivations through the **host** nix-daemon — the
hive-ci container shares the host store and has no daemon of its own. Build
outputs accumulate in `/nix/store` with no automatic collection, and a busy
CI day can fill the disk until every job fails fast with `ENOSPC`.
Store GC is a **host-level** concern, so it belongs in the host's own NixOS
configuration, not in the hyperhive service modules — a single service should
not reach out and change the host's global nix-daemon options. Add the
following to your host config:
```nix
{
# Daily GC: delete store paths not referenced by a live root and older
# than a day. Keeps the store bounded between builds.
nix.gc = {
automatic = true;
dates = "daily";
options = "--delete-older-than 1d";
};
# Disk-pressure GC: when free space drops below min-free mid-build, the
# daemon collects garbage up to max-free before continuing. This is the
# real-time net the daily timer can't provide — a same-day build burst is
# what fills the disk. Tune to your disk size.
nix.settings.min-free = 20 * 1024 * 1024 * 1024; # 20 GiB
nix.settings.max-free = 50 * 1024 * 1024 * 1024; # 50 GiB
}
```
**Remote builders:** if CI dispatches builds to a remote builder (e.g. via
`nix.buildMachines` / `ssh-ng://`), the build outputs land in *that host's*
store, so the same GC config should be applied wherever the builder runs —
GC on the coordinator host won't reclaim space on the builder.
## References
- `nix/modules/hive-ci.nix`: runner configuration, auto-registration script, container setup.