---
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]]