Watch
0
0
Fork
You've already forked hyperhive
0

docs: the repo's own CI checks move from the CI runner page to the project process docs

docs/4-implementation/scheduler/ci.md described both the swarm-ci-runner product (hosting, registration, security, store maintenance) and this repo's own pipeline (which jobs run on a PR, the local equivalents, the nightly VM tests). The second part is project process: it moves, whole and in order, to docs/5-project/process/ci-checks.md, with a pointer left behind, an entry in the docs index and the one doc comment in hive-forge that named the old section updated.
This commit is contained in:
iris 2026-11-20 00:37:51 +01:00 • committed by mara
commit a19745d30d
4 changed files with 124 additions and 109 deletions

View file

@ -36,113 +36,12 @@ Two things worth knowing before you rely on it:
Everything below this point is implementation detail: registration Everything below this point is implementation detail: registration
internals, container design, and the full security writeup. internals, container design, and the full security writeup.
## CI checks ## This repo's own checks
<!-- vale write-good.Passive = NO --> Which jobs run on this repo's pull requests, how to run them locally and how the
nightly VM tests work are project process, in
The jobs run on every PR (and on `workflow_dispatch` for manual [the repo's CI checks](../../5-project/process/ci-checks.md). This page covers the
re-triggers), defined in runner itself.
[`.forgejo/workflows/ci.yml`](../../../.forgejo/workflows/ci.yml). The first four
below are required checks (forge branch protection) — a hit on any of them
blocks merge. The two vale jobs split what used to be a single check: the
error-only one exists so it _can_ become a required check without also
gating on the full job's standing warning/suggestion backlog, but flipping
that switch on the forge is a separate operator action, not something this
table can assert ahead of it happening.
<!-- vale write-good.Passive = YES -->
| Job | What it runs | Required? |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| **nix flake check** | `scripts/ci-flake-check.sh`: nix-eval-jobs, then builds each check (treefmt, clippy, tests, module eval); no VM tests | yes |
| **tracker-tag lint** | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`) | yes |
| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) | yes |
| **doc-pointer lint** | flags `docs/…md` paths and relative markdown links that no longer resolve (`scripts/check-doc-refs.sh`) | yes |
| **attribution-trailer lint** | flags `Co-Authored-By` trailers with Claude/Anthropic attribution in PR commits (`scripts/check-attribution-trailers.sh`) | not yet — intended to be |
| **prose lint (vale, errors)** | vale, `docs/` tree, error-severity rule hits only | not yet — intended to be |
| **prose lint (vale)** | vale, `docs/` tree, full severity range (warnings + suggestions too) | no — advisory, standing backlog |
`hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger
without an empty commit.
<!-- vale write-good.Passive = NO -->
**`ci-rerun --pr` verifies the code but doesn't reliably move the PR's own
status checks.** Measured directly (raw `GET /repos/.../actions/tasks`
JSON): a genuine PR-triggered run carries `event: pull_request` with the
`#<n>` pseudo-ref as its `head_branch`; a `ci-rerun --pr`-dispatched run
carries `event: workflow_dispatch` with the real branch name instead.
Forgejo's PR commit-status tracking appears scoped to `pull_request`-event
runs specifically, so a dispatched run — even a genuinely successful one —
never writes to that status slot. Reproduced with three dispatches on one
PR over 20+ minutes, all genuinely green, the PR's own status unmoved
throughout. **Always re-check `pr status` after a dispatch and believe
what it says — don't push a commit just to unwedge it, that's the
empty-commit anti-pattern this verb exists to avoid.** If `hive-forge
ci-log --run <n> --job 0` shows the code green (verdict is the
last line) but the status is stuck, ask the operator to select "rerun" in
the forge web UI — it's CSRF-gated, so only they can do it.
<!-- vale write-good.Passive = YES -->
### Running checks locally
Don't run `nix flake check` directly — it dispatches to the shared build farm and
wastes a remote-builder slot. Use the devshell equivalents instead:
```sh
nix develop -c cargo clippy --all-targets -- -D warnings
nix develop -c cargo test
nix fmt # authoritative; the formatter set is nix/treefmt.nix
sh scripts/check-issue-refs.sh # tracker-tag lint
sh scripts/check-comment-blocks.sh # comment-block lint
```
`scripts/pre-push` provides a git pre-push hook that automates the two
lint checks. Install it once per clone:
```sh
ln -sf ../../scripts/pre-push .git/hooks/pre-push
```
After that, any `git push` automatically runs both lints and aborts with a
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.
### VM tests
Tests that boot NixOS VMs are the `vmTests.<system>.<name>` flake output
(`nix/vm-tests.nix`), not `checks`, so the per-PR **nix flake check** job never
builds them. It does build the `vm-test-typecheck-<name>` checks
(`nix/vm-test-typecheck.nix`): the type check and lint the test driver runs over
a test script, on the script text alone. They evaluate no node configuration
and build no VM. They cover all seven tests. `semi-spread` and `swarm-builder-offline`
read node config or an agent toplevel into their script, so each builds the script
with stand-in values (`passthru.typecheckScript`), from the same function as the real
one.
`vm-test-typecheck-control` passes only when the checker rejects a known type error, which shows the
checker resolves `test_driver`. [`.forgejo/workflows/vm-nightly.yml`](../../../.forgejo/workflows/vm-nightly.yml)
builds them nightly at 02:30, one job per test, so the runner's one-hour job
limit applies to each test alone and a stuck test no longer hides the others'
results. The matrix in `vm-nightly.yml` is the list of tests;
`scripts/check-vm-test-list.sh` fails CI when it differs from `nix/vm-tests.nix`,
so a new test goes into both.
Each test sets `globalTimeout` below that hour. With the default job capacity of
1 the jobs run one after another. To run one by hand, start the workflow from
the forge UI (Actions, vm-nightly, Run workflow, then name one test in the
`test` field; the other jobs skip their steps), or run
`nix build .#vmTests.x86_64-linux.<name>` on a host with KVM.
The `full-setup` script is plain Python in `nix/vm-tests/full-setup.py`, with no
Nix interpolation. Commands the script runs in the VM find their binaries on the
node's `environment.systemPackages`. Build-time values (socket path, forge
domain, store paths) arrive as `FULL_SETUP_*` environment variables, set in
`nix/vm-tests/full-setup.nix` through `overrideTestDerivation`. To add a value,
set one there and read it with `os.environ` in the script. `nix fmt` formats and lints the Python (treefmt's
`ruff-format` and `ruff-check`, which fixes what it can), and the `formatting`
flake check fails on a file `nix fmt` would change. `nix/vm-tests/ruff.toml`
names the globals the test driver provides.
## Configuration reference ## Configuration reference

View file

@ -0,0 +1,113 @@
# The repo's CI checks and how to run them
What runs on every pull request to this repo, and how to run the same checks
before you push. The runner that executes them, and how to host one, is the
product side: [`swarm-ci-runner`](../../4-implementation/scheduler/ci.md).
## The checks
<!-- vale write-good.Passive = NO -->
The jobs run on every PR (and on `workflow_dispatch` for manual
re-triggers), defined in
[`.forgejo/workflows/ci.yml`](../../../.forgejo/workflows/ci.yml). The first four
below are required checks (forge branch protection) — a hit on any of them
blocks merge. The two vale jobs split what used to be a single check: the
error-only one exists so it _can_ become a required check without also
gating on the full job's standing warning/suggestion backlog, but flipping
that switch on the forge is a separate operator action, not something this
table can assert ahead of it happening.
<!-- vale write-good.Passive = YES -->
| Job | What it runs | Required? |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| **nix flake check** | `scripts/ci-flake-check.sh`: nix-eval-jobs, then builds each check (treefmt, clippy, tests, module eval); no VM tests | yes |
| **tracker-tag lint** | flags `#NNN` issue tags in source and comments (`scripts/check-issue-refs.sh`) | yes |
| **comment-block lint** | flags contiguous comment blocks over 30 lines (`scripts/check-comment-blocks.sh`) | yes |
| **doc-pointer lint** | flags `docs/…md` paths and relative markdown links that no longer resolve (`scripts/check-doc-refs.sh`) | yes |
| **attribution-trailer lint** | flags `Co-Authored-By` trailers with Claude/Anthropic attribution in PR commits (`scripts/check-attribution-trailers.sh`) | not yet — intended to be |
| **prose lint (vale, errors)** | vale, `docs/` tree, error-severity rule hits only | not yet — intended to be |
| **prose lint (vale)** | vale, `docs/` tree, full severity range (warnings + suggestions too) | no — advisory, standing backlog |
`hive-forge ci-rerun --pr N` dispatches a `workflow_dispatch` retrigger
without an empty commit.
<!-- vale write-good.Passive = NO -->
**`ci-rerun --pr` verifies the code but doesn't reliably move the PR's own
status checks.** Measured directly (raw `GET /repos/.../actions/tasks`
JSON): a genuine PR-triggered run carries `event: pull_request` with the
`#<n>` pseudo-ref as its `head_branch`; a `ci-rerun --pr`-dispatched run
carries `event: workflow_dispatch` with the real branch name instead.
Forgejo's PR commit-status tracking appears scoped to `pull_request`-event
runs specifically, so a dispatched run — even a genuinely successful one —
never writes to that status slot. Reproduced with three dispatches on one
PR over 20+ minutes, all genuinely green, the PR's own status unmoved
throughout. **Always re-check `pr status` after a dispatch and believe
what it says — don't push a commit just to unwedge it, that's the
empty-commit anti-pattern this verb exists to avoid.** If `hive-forge
ci-log --run <n> --job 0` shows the code green (verdict is the
last line) but the status is stuck, ask the operator to select "rerun" in
the forge web UI — it's CSRF-gated, so only they can do it.
<!-- vale write-good.Passive = YES -->
## Running checks locally
Don't run `nix flake check` directly — it dispatches to the shared build farm and
wastes a remote-builder slot. Use the devshell equivalents instead:
```sh
nix develop -c cargo clippy --all-targets -- -D warnings
nix develop -c cargo test
nix fmt # authoritative; the formatter set is nix/treefmt.nix
sh scripts/check-issue-refs.sh # tracker-tag lint
sh scripts/check-comment-blocks.sh # comment-block lint
```
`scripts/pre-push` provides a git pre-push hook that automates the two
lint checks. Install it once per clone:
```sh
ln -sf ../../scripts/pre-push .git/hooks/pre-push
```
After that, any `git push` automatically runs both lints and aborts with a
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.
## VM tests
Tests that boot NixOS VMs are the `vmTests.<system>.<name>` flake output
(`nix/vm-tests.nix`), not `checks`, so the per-PR **nix flake check** job never
builds them. It does build the `vm-test-typecheck-<name>` checks
(`nix/vm-test-typecheck.nix`): the type check and lint the test driver runs over
a test script, on the script text alone. They evaluate no node configuration
and build no VM. They cover all seven tests. `semi-spread` and `swarm-builder-offline`
read node config or an agent toplevel into their script, so each builds the script
with stand-in values (`passthru.typecheckScript`), from the same function as the real
one.
`vm-test-typecheck-control` passes only when the checker rejects a known type error, which shows the
checker resolves `test_driver`. [`.forgejo/workflows/vm-nightly.yml`](../../../.forgejo/workflows/vm-nightly.yml)
builds them nightly at 02:30, one job per test, so the runner's one-hour job
limit applies to each test alone and a stuck test no longer hides the others'
results. The matrix in `vm-nightly.yml` is the list of tests;
`scripts/check-vm-test-list.sh` fails CI when it differs from `nix/vm-tests.nix`,
so a new test goes into both.
Each test sets `globalTimeout` below that hour. With the default job capacity of
1 the jobs run one after another. To run one by hand, start the workflow from
the forge UI (Actions, vm-nightly, Run workflow, then name one test in the
`test` field; the other jobs skip their steps), or run
`nix build .#vmTests.x86_64-linux.<name>` on a host with KVM.
The `full-setup` script is plain Python in `nix/vm-tests/full-setup.py`, with no
Nix interpolation. Commands the script runs in the VM find their binaries on the
node's `environment.systemPackages`. Build-time values (socket path, forge
domain, store paths) arrive as `FULL_SETUP_*` environment variables, set in
`nix/vm-tests/full-setup.nix` through `overrideTestDerivation`. To add a value,
set one there and read it with `os.environ` in the script. `nix fmt` formats and lints the Python (treefmt's
`ruff-format` and `ruff-check`, which fixes what it can), and the `formatting`
flake check fails on a file `nix fmt` would change. `nix/vm-tests/ruff.toml`
names the globals the test driver provides.

View file

@ -149,7 +149,7 @@ Nothing of it sits in this tree.
[`4-implementation/scheduler/jobq.md`](4-implementation/scheduler/jobq.md) — operator-facing, no implementation detail. [`4-implementation/scheduler/jobq.md`](4-implementation/scheduler/jobq.md) — operator-facing, no implementation detail.
- **How does the rebuild queue work? What are the concrete step kinds, - **How does the rebuild queue work? What are the concrete step kinds,
queue sources, scheduler internals?** → [`4-implementation/scheduler/coordinator.md`](4-implementation/scheduler/coordinator.md). queue sources, scheduler internals?** → [`4-implementation/scheduler/coordinator.md`](4-implementation/scheduler/coordinator.md).
- **How does the CI runner work? How does it register?** → - **How does the CI runner work? How does it register? How's it hosted?** →
[`4-implementation/scheduler/ci.md`](4-implementation/scheduler/ci.md). [`4-implementation/scheduler/ci.md`](4-implementation/scheduler/ci.md).
- **How are Claude Code metrics (tokens, cost, tool calls) exported to - **How are Claude Code metrics (tokens, cost, tool calls) exported to
Prometheus/Grafana?** → [`4-implementation/scheduler/observability.md`](4-implementation/scheduler/observability.md). Prometheus/Grafana?** → [`4-implementation/scheduler/observability.md`](4-implementation/scheduler/observability.md).
@ -229,6 +229,9 @@ How the project itself works: processes, conventions, design guides.
[`5-project/process/conventions.md`](5-project/process/conventions.md). [`5-project/process/conventions.md`](5-project/process/conventions.md).
- **Why does the nspawn flag look like that?** → [`5-project/process/gotchas.md`](5-project/process/gotchas.md) - **Why does the nspawn flag look like that?** → [`5-project/process/gotchas.md`](5-project/process/gotchas.md)
(bind mounts, conf flags, other NixOS/nspawn quirks). (bind mounts, conf flags, other NixOS/nspawn quirks).
- **Which checks run on a PR to this repo, and how do I run them before I push?** →
[`5-project/process/ci-checks.md`](5-project/process/ci-checks.md) (the jobs, the local
equivalents, the nightly VM tests).
- **What does a PR review verdict actually gate?** → - **What does a PR review verdict actually gate?** →
[`5-project/process/pr-review-gate.md`](5-project/process/pr-review-gate.md). [`5-project/process/pr-review-gate.md`](5-project/process/pr-review-gate.md).
- **How are the web UIs designed to look and behave?** → - **How are the web UIs designed to look and behave?** →

View file

@ -14,8 +14,8 @@
//! given handle: //! given handle:
//! - `--pr <n>` → refuses instead of dispatching: a `workflow_dispatch` run //! - `--pr <n>` → refuses instead of dispatching: a `workflow_dispatch` run
//! writes no commit status, so it cannot clear a red `(pull_request)` //! writes no commit status, so it cannot clear a red `(pull_request)`
//! check on the PR's sha — see `docs/4-implementation/scheduler/ci.md`'s "CI checks" for //! check on the PR's sha — see `docs/5-project/process/ci-checks.md`'s "The checks"
//! why. Re-run from the web UI instead. //! for why. Re-run from the web UI instead.
//! - `--branch <name>` → dispatches `--workflow` on that branch directly. //! - `--branch <name>` → dispatches `--workflow` on that branch directly.
//! - `--run <n>` → looks the run up by its display number (same convention //! - `--run <n>` → looks the run up by its display number (same convention
//! as `ci-log` / `artifact-get` / `ci-runs`) and dispatches the same //! as `ci-log` / `artifact-get` / `ci-runs`) and dispatches the same