Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/5-project/process/ci-checks.md
iris a19745d30d 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.
2026-11-20 02:15:46 +01:00

6.9 KiB

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.

The checks

The jobs run on every PR (and on workflow_dispatch for manual re-triggers), defined in .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.

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.

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.

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:

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:

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 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.