Mike Swanson
60519be28a
Establish GuruConnect's release engineering and project tracking (SPEC-001): - docs/ scaffold: FEATURE_ROADMAP, ARCHITECTURE_DECISIONS (ADR-001 standalone+contract, ADR-002 Gitea Actions + Azure Trusted Signing), docs/specs/SPEC-001, CHANGELOG. - .gitea/workflows/release.yml: conventional-commit auto-versioning, git-cliff changelog, Windows agent build, Azure Trusted Signing via jsign (reusing the shared ACG cert profile), Gitea release via REST API. build-and-test.yml is the PR/push gate; deploy.yml de-duplicated. - server: GET /api/changelog/:component/:version (latest + by-version), path-traversal hardened. - cliff.toml; server/.env.example documents CHANGELOG_DIR. Reviewed (Code Review Agent): axum route-conflict blocker fixed; CHANGELOG ordering, toolchain target, breaking-change parsing, empty-changelog fallback addressed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3.3 KiB
GuruConnect — Architecture Decisions
Records significant architectural decisions for the GuruConnect product. Each entry: context, decision, options considered, rationale, consequences.
ADR-001: GuruConnect is a Standalone Product; Integrate with GuruRMM via a Versioned Contract
Date: 2026-05-29 Status: Decided Deciders: Mike Swanson
Context
GuruConnect is a remote-support product that must work fully on its own, with its own repository
(azcomputerguru/guru-connect), build pipeline, and release cadence. GuruRMM wants to offer native
integrated remote control by driving GuruConnect.
Decision
GuruConnect stays an independent product. It exposes a versioned integration contract
(/api/integration/v1/, capability discovery, embedded-viewer protocol) that GuruRMM consumes as a
broker. The two products do not share build pipelines or release in lockstep. GuruConnect owns the
contract; GuruRMM does no active development on GuruConnect.
Rationale
- Preserves GuruConnect as a sellable standalone product.
- Avoids coupling two independently-evolving codebases; integration changes go through the contract.
- Mirrors the GuruRMM-side decision (GuruRMM ADR-008).
Consequences
- The integration surface is semver'd; breaking changes require a major bump.
- See
docs/specs/native-remote-control/for the contract spec.
ADR-002: Release Engineering — Gitea Actions Pipeline with Azure Trusted Signing
Date: 2026-05-29 Status: Decided Deciders: Mike Swanson
Context
GuruConnect needs operational parity with GuruRMM: signed Windows binaries, automatic versioning,
changelogs, and tracking. GuruRMM achieves this with a Gitea webhook → shell-script pipeline on
shared build hosts (Saturn + Pluto) and signs via Azure Trusted Signing (jsign) using credentials
in /etc/gururmm-signing.env.
Decision
GuruConnect implements its release engineering entirely in Gitea Actions (not the webhook/script
model), and reuses GuruRMM's existing Azure Trusted Signing certificate profile (same account +
service principal) to sign the Windows agent .exe.
Options Considered
- A — Gitea Actions, reuse RMM cert profile (chosen): self-contained workflows;
jsignruns on theubuntu-latestrunner; no Pluto/webhook dependency. GC ships a single.exe(no WiX/MSI), so no Windows runner is needed. - B — Mirror RMM's webhook + shell scripts: maximal parity but adds Pluto/webhook coupling and a build host to maintain.
- C — Separate Azure Trusted Signing account for GC: cleaner attribution, more Azure setup.
Rationale
jsignis cross-platform (Java) and signs PE binaries on Linux — no Windows runner required.- Reusing RMM's cert profile means zero new Azure provisioning; GC binaries are signed by the same ACG identity.
- Actions are self-contained and versioned with the repo, simpler than maintaining build-host scripts.
Consequences
- The Azure Trusted Signing service-principal secrets must be added to the
guru-connectrepo's Gitea Actions secrets (values come from/etc/gururmm-signing.env/ the SOPS vault). See SPEC-001. - Windows binaries will be attributed to GuruRMM's cert profile until/unless a GuruConnect-specific profile is provisioned (a future, low-effort change).
- Implementation:
docs/specs/SPEC-001-operational-tooling-parity.md.