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.
This commit is contained in:
parent
7892304827
commit
7fba2d6919
1 changed files with 26 additions and 0 deletions
26
docs/ci.md
26
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):
|
||||
|
|
|
|||
Loading…
Reference in a new issue