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.
113 lines
6.9 KiB
Markdown
113 lines
6.9 KiB
Markdown
# 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.
|