diff --git a/docs/4-implementation/scheduler/ci.md b/docs/4-implementation/scheduler/ci.md index c1d8d6176..3deaca45b 100644 --- a/docs/4-implementation/scheduler/ci.md +++ b/docs/4-implementation/scheduler/ci.md @@ -36,113 +36,12 @@ Two things worth knowing before you rely on it: Everything below this point is implementation detail: registration internals, container design, and the full security writeup. -## CI checks +## This repo's own 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. +Which jobs run on this repo's pull requests, how to run them locally and how the +nightly VM tests work are project process, in +[the repo's CI checks](../../5-project/process/ci-checks.md). This page covers the +runner itself. ## Configuration reference diff --git a/docs/5-project/process/ci-checks.md b/docs/5-project/process/ci-checks.md new file mode 100644 index 000000000..4875e8ed7 --- /dev/null +++ b/docs/5-project/process/ci-checks.md @@ -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 + + + +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. diff --git a/docs/README.md b/docs/README.md index be56a5cd8..5132f1679 100644 --- a/docs/README.md +++ b/docs/README.md @@ -149,7 +149,7 @@ Nothing of it sits in this tree. [`4-implementation/scheduler/jobq.md`](4-implementation/scheduler/jobq.md) — operator-facing, no implementation detail. - **How does the rebuild queue work? What are the concrete step kinds, queue sources, scheduler internals?** → [`4-implementation/scheduler/coordinator.md`](4-implementation/scheduler/coordinator.md). -- **How does the CI runner work? How does it register?** → +- **How does the CI runner work? How does it register? How's it hosted?** → [`4-implementation/scheduler/ci.md`](4-implementation/scheduler/ci.md). - **How are Claude Code metrics (tokens, cost, tool calls) exported to Prometheus/Grafana?** → [`4-implementation/scheduler/observability.md`](4-implementation/scheduler/observability.md). @@ -229,6 +229,9 @@ How the project itself works: processes, conventions, design guides. [`5-project/process/conventions.md`](5-project/process/conventions.md). - **Why does the nspawn flag look like that?** → [`5-project/process/gotchas.md`](5-project/process/gotchas.md) (bind mounts, conf flags, other NixOS/nspawn quirks). +- **Which checks run on a PR to this repo, and how do I run them before I push?** → + [`5-project/process/ci-checks.md`](5-project/process/ci-checks.md) (the jobs, the local + equivalents, the nightly VM tests). - **What does a PR review verdict actually gate?** → [`5-project/process/pr-review-gate.md`](5-project/process/pr-review-gate.md). - **How are the web UIs designed to look and behave?** → diff --git a/hive-forge/src/verbs/ci_rerun.rs b/hive-forge/src/verbs/ci_rerun.rs index e7b90dd52..d71fa0dbb 100644 --- a/hive-forge/src/verbs/ci_rerun.rs +++ b/hive-forge/src/verbs/ci_rerun.rs @@ -14,8 +14,8 @@ //! given handle: //! - `--pr ` → refuses instead of dispatching: a `workflow_dispatch` run //! writes no commit status, so it cannot clear a red `(pull_request)` -//! check on the PR's sha — see `docs/4-implementation/scheduler/ci.md`'s "CI checks" for -//! why. Re-run from the web UI instead. +//! check on the PR's sha — see `docs/5-project/process/ci-checks.md`'s "The checks" +//! for why. Re-run from the web UI instead. //! - `--branch ` → dispatches `--workflow` on that branch directly. //! - `--run ` → looks the run up by its display number (same convention //! as `ci-log` / `artifact-get` / `ci-runs`) and dispatches the same