From 8a2ffbbef7e87a37fcd72c7e794e82363d7ef339 Mon Sep 17 00:00:00 2001 From: iris Date: Sat, 15 Aug 2026 11:45:04 +0200 Subject: [PATCH] docs(ci): fix required-check contradiction, dedupe bootstrap, trim history --- docs/ci.md | 51 ++++++++++++++++++++++++++++----------------------- 1 file changed, 28 insertions(+), 23 deletions(-) diff --git a/docs/ci.md b/docs/ci.md index 150c1e40..7b414467 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -31,17 +31,19 @@ writeup. ## CI checks -Three jobs run on every PR (and on `workflow_dispatch` for manual re-triggers): +Three jobs run on every PR (and on `workflow_dispatch` for manual re-triggers), +defined in [`.forgejo/workflows/ci.yml`](../.forgejo/workflows/ci.yml). All +three are required checks (forge branch protection) — a hit on any of them +blocks merge. -| Job | What it runs | Currently required | -| --- | --- | --- | -| **nix flake check** | treefmt + rustfmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation | yes | -| **tracker-tag lint** | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`) | no (red, non-blocking) | -| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) | no (red, non-blocking) | +| Job | What it runs | +| --- | --- | +| **nix flake check** | treefmt + rustfmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation | +| **tracker-tag lint** | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`) | +| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) | -The tracker-tag and comment-block checks are non-blocking today (a hit fails the -check but does not prevent merge) while the legacy backlog is cleaned up. They are -expected to become required checks once the tree is clean. +`hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger +without an empty commit. ### Running checks locally @@ -68,14 +70,17 @@ diagnostic if either fails — catching the issue locally before CI sees it. Note that the hook does **not** run `cargo clippy` or `cargo test` (those are slow); run those manually before pushing Rust changes. -## Operator bootstrap +## Configuration reference -Set `services.hyperhive.forge.ci.enable = true` in the host NixOS config. That's it — no manual token provisioning. +The internal forge is always present (mandatory), so the runner always has a +hive-forge instance to register against — nothing extra to enable beyond +`services.hyperhive.forge.ci.enable = true` (see *For operators* above). -**Requirements:** - -- The internal forge is always present (mandatory), so the runner always has a hive-forge instance to register against — nothing extra to enable. -- Optional: tune `services.hyperhive.forge.ci.name` (runner name in forge admin panel), `concurrency` (parallel job capacity), `labels` (workflow targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration string e.g. `"3h"` — a job that exceeds it is killed so a hung or runaway build can't hold the runner's single slot indefinitely). +Optional tuning: `services.hyperhive.forge.ci.name` (runner name in forge +admin panel), `concurrency` (parallel job capacity), `labels` (workflow +targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration +string e.g. `"3h"` — a job that exceeds it is killed so a hung or runaway +build can't hold the runner's single slot indefinitely). ## Container design @@ -86,7 +91,14 @@ Set `services.hyperhive.forge.ci.enable = true` in the host NixOS config. That's ## Auto-registration flow -Registration is **off the container's boot-critical path** — hive-c0re owns it and runs it out of band, so a slow forge or core-token never delays the container's start. (The earlier design ran a host-side `hive-ci-prefetch.service` that gated `container@hive-ci` start on a forge round-trip, which could exceed the nspawn start timeout and trip a restart loop; moving registration into hive-c0re removed that.) The core admin token is held only by hive-c0re on the host; only the runner registration token reaches the container. +Registration is **off the container's boot-critical path** — hive-c0re owns +it and runs it out of band, so a slow forge or core-token never delays the +container's start. Gotcha: don't gate the container's own start on a forge +round-trip (a host-side unit that did this could exceed the nspawn start +timeout and trip a restart loop) — registration must stay something +hive-c0re drives after the container is already up. The core admin token is +held only by hive-c0re on the host; only the runner registration token +reaches the container. ### hive-c0re side (`forge/ci_runner.rs`, run during the startup sweep) @@ -139,13 +151,6 @@ runner as a hard `git clone` failure. The hive-c0re-managed namespaces (`config/`, `shared/`, `agents/`, `core/`) to avoid provisioning collisions. -## CI workflow - -Three jobs are defined in [`.forgejo/workflows/ci.yml`](../.forgejo/workflows/ci.yml): -`nix flake check`, `tracker-tag lint`, and `comment-block lint`. All three are -required — a lint failure blocks merge. `hive-forge ci-rerun --pr N` dispatches -a `workflow_dispatch` retrigger without an empty commit. - ## Security: unsandboxed builds and trusted contributors **hive-ci should only run CI for trusted contributors.** The security boundary is weaker than it looks: