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.
This commit is contained in:
parent
f29435fcf1
commit
a19745d30d
4 changed files with 124 additions and 109 deletions
|
|
@ -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
|
||||
|
||||
<!-- 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.
|
||||
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
|
||||
|
||||
|
|
|
|||
113
docs/5-project/process/ci-checks.md
Normal file
113
docs/5-project/process/ci-checks.md
Normal file
|
|
@ -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
|
||||
|
||||
<!-- 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.
|
||||
|
|
@ -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?** →
|
||||
|
|
|
|||
|
|
@ -14,8 +14,8 @@
|
|||
//! given handle:
|
||||
//! - `--pr <n>` → 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 <name>` → dispatches `--workflow` on that branch directly.
|
||||
//! - `--run <n>` → looks the run up by its display number (same convention
|
||||
//! as `ci-log` / `artifact-get` / `ci-runs`) and dispatches the same
|
||||
|
|
|
|||
Loading…
Reference in a new issue