vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(ci): fix required-check contradiction, dedupe bootstrap, trim history

Browse source
This commit is contained in:
iris 2026-08-15 11:45:04 +02:00 • committed by mara
commit 8a2ffbbef7
1 changed files with 28 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

51
docs/ci.md
View file

@ -31,17 +31,19 @@ writeup.
## CI checks ## 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 | | Job | What it runs |
| --- | --- | --- | | --- | --- |
| **nix flake check** | treefmt + rustfmt formatting, `cargo clippy -D warnings`, `cargo test`, module evaluation | yes | | **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`) | no (red, non-blocking) | | **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`) | no (red, non-blocking) | | **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 `hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger
check but does not prevent merge) while the legacy backlog is cleaned up. They are without an empty commit.
expected to become required checks once the tree is clean.
### Running checks locally ### 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 Note that the hook does **not** run `cargo clippy` or `cargo test` (those are
slow); run those manually before pushing Rust changes. 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:** Optional tuning: `services.hyperhive.forge.ci.name` (runner name in forge
admin panel), `concurrency` (parallel job capacity), `labels` (workflow
- The internal forge is always present (mandatory), so the runner always has a hive-forge instance to register against — nothing extra to enable. targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration
- 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). 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 ## Container design
@ -86,7 +91,14 @@ Set `services.hyperhive.forge.ci.enable = true` in the host NixOS config. That's
## Auto-registration flow ## 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) ### 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/`) hive-c0re-managed namespaces (`config/`, `shared/`, `agents/`, `core/`)
to avoid provisioning collisions. 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 ## Security: unsandboxed builds and trusted contributors
**hive-ci should only run CI for trusted contributors.** The security boundary is weaker than it looks: **hive-ci should only run CI for trusted contributors.** The security boundary is weaker than it looks: