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

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.