claudetools/.claude/memory/feedback_gururmm_build_verification.md

name: feedback_gururmm_build_verification description: Before touching the GuruRMM build pipeline, verify locally first — merge-to-main IS the build+deploy. Canonical refs: docs/BUILD.md + the gururmm-build skill. Compile-gate trap. metadata: type: feedback

Every Claude instance that touches the GuruRMM build pipeline must internalize this before editing agent/server/dashboard code:

Merging to main IS the build-and-deploy trigger — there is no separate build step. A push to main fires the Gitea webhook → webhook-handler.py on 172.16.3.30 → build-shared.sh (version bump + [ci-version-bump] commit) → per-component builds (each self-gated on change). New agent/server/dashboard artifacts land on beta first; prod promotion is deliberate.

Canonical, kept-current references (use these, don't re-derive from the scripts):

• projects/msp-tools/guru-rmm/docs/BUILD.md — developer build + pre-merge verification guide.
• gururmm-build skill — verify.sh {server|agent|dashboard|all|migrations} [--check] runs the same cargo/npm the server runs, on the right OS, with the gotchas baked in + errorlog on failure.
• projects/msp-tools/guru-rmm/deploy/build-pipeline/README.md — server-side pipeline source of truth (webhook, Beast/Pluto hosts, signing, dashboard channels, repo↔/opt sync). The repo's older scripts/build-agents.sh + scripts/webhook-handler.py are a PRIOR generation — do not follow them.

The traps that break a post-merge build:

• Compile gate: Linux-gated agent code (#[cfg(target_os="linux")], e.g. is_docker_container() in agent/src/updater/mod.rs) is ONLY compiled by the Linux agent build — Windows cargo check CANNOT verify it (openssl-sys won't cross-build). The Linux agent build on .30 is the real gate. Build agent changes on the OS family they target; Windows-only paths (MSI/tray/legacy/x86) are gated only by the Beast/Pluto Windows build.
• sqlx offline cache: the server build uses SQLX_OFFLINE=true + server/.sqlx. If you changed queries/migrations, run cargo sqlx prepare and commit server/.sqlx, or the build fails.
• Migration number collisions across branches: check the highest NNN_ on origin/main before naming a new one (verify.sh migrations). Idempotent (IF NOT EXISTS) keeps overlaps harmless.
• Webhook builds from origin/main, so verify the COMMITTED state, not the working tree.

Why: merging deploys, so an unverified merge breaks the build or ships broken code. Howard hit this 2026-06-21 — couldn't cross-build the Linux-gated BUG-019 path from his Windows box, so the post-merge Linux build on .30 was the only gate.

How to apply: before merging gururmm changes, run gururmm-build verify.sh for each touched component (on the OS it targets); read docs/BUILD.md if unfamiliar with the model; after merge, watch the matching /var/log/gururmm-build-*.log on .30. Promote the dashboard beta→prod only via promote-dashboard.sh --confirm.

Related: reference_gururmm rmm-dashboard-beta-before-main feedback_dashboard_beta_first feedback_gururmm_build_channel_default feedback_verify_committed_state_before_push reference_guru5070_rust_toolchain reference_sqlx_migrations_immutable gururmm-beast-windows-build-host feedback_gururmm rmm-agent-update-model