# 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 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. | 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 `#` 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 --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: ```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..` 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-` 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.` 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.