From 7fba2d69190639a4d8ef80f386d27b929f94f1f0 Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 3 Aug 2026 00:04:58 +0200 Subject: [PATCH] docs(ci): add a For operators section ci.md mixes a genuinely short operator bootstrap step with deep auto-registration/container-design internals and a full security writeup an operator does need to read once, but not first. Adds a short synthesis at the top: enabling is one nix option, the unsandboxed-build trust tradeoff (fine for a trusted team, gate it if you take fork PRs), and the disk-maintenance recipe (CI shares the host nix store with no auto-GC of its own). Every claim checked against the existing detail further down in this same file. Part of hyperhive#1898. --- docs/ci.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/ci.md b/docs/ci.md index 95160b90..150c1e40 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -3,6 +3,32 @@ The `hive-ci` module runs a Forgejo Actions runner in a `hive-ci` nixos-container, executing CI jobs from `.forgejo/workflows/ci.yml` on every PR. +## For operators + +**Enabling it is one line**: `services.hyperhive.forge.ci.enable = true` +in the host NixOS config. No manual token provisioning — hive-c0re +registers the runner with the forge automatically. + +Two things worth knowing before you rely on it: + +- **Only run CI for contributors you trust.** Builds run **unsandboxed** + (an nspawn limitation, not a choice) — a malicious build script in a + PR could make network requests or write to the container filesystem + during the build. Fine for a small trusted-team hive where everyone + already has forge access; if you take outside/fork contributions, + gate CI behind Forgejo's fork-PR-approval setting or restrict the + workflow to push-only triggers (forks can't push to your branches). + See *Security* below for the full threat model. +- **Watch your disk.** CI builds through the host's nix store with no + automatic garbage collection of its own — a busy CI day can fill + `/nix/store` until every job fails with `ENOSPC`. Add the daily + + disk-pressure GC config from *Host store maintenance* below to your + host's NixOS config (not optional if you plan to actually use this). + +Everything below this point is implementation detail: exact +auto-registration internals, container design, and the full security +writeup. + ## CI checks Three jobs run on every PR (and on `workflow_dispatch` for manual re-triggers):