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