diff --git a/docs/ci.md b/docs/ci.md index 66292879..ed8ac10d 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -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.