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>
82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
# 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; `jsign` runs on
|
|
the `ubuntu-latest` runner; 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
|
|
|
|
- `jsign` is 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-connect` repo'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`.
|