Releases and auto-update

The connector is distributed as a desktop app built with Electron. Installers are produced by GitHub Actions and published on the connector repository's GitHub Releases, which is also where running agents look for updates.

Cutting a release

1. Bump version in package.json of vroum-connector and commit.

2. Tag and push: git tag v0.2.0 && git push origin main v0.2.0.

3. The Release workflow (.github/workflows/release.yml) runs the tests, builds on macos-14 and windows-latest, and publishes:

   Artifact	Used for
   Vroum Connector-0.2.0-win-x64.exe	Windows installer (NSIS, per-user, one click).
   Vroum Connector-0.2.0-mac-arm64.dmg, -mac-x64.dmg	macOS installers.
   Vroum Connector-0.2.0-mac-arm64.zip, -mac-x64.zip	What the macOS updater downloads.
   latest.yml, latest-mac.yml, *.blockmap	Update manifests read by electron-updater.

The release must be published, not a draft, for agents to see it. The version in the tag must match package.json; electron-builder refuses otherwise.

How auto-update works

electron/updater.ts wraps electron-updater:

• Checks on launch and every four hours, and from the tray menu.
• Downloads in the background. The tray shows Downloading 0.2.0… then Restart to update to 0.2.0.
• Installs on its own thirty seconds after the download, unless a job is being printed, in which case it waits for the job to finish. Quitting the app also installs a downloaded update.
• On Windows the NSIS installer runs silently and relaunches the app. On macOS the app is replaced from the zip and relaunched.

Updates are only checked when the app is packaged (app.isPackaged), never when run from source.

Code signing

Platform	Requirement
macOS	Required. Gatekeeper refuses unsigned downloads and electron-updater refuses to update an unsigned app. Needs a Developer ID Application certificate and notarization.
Windows	Optional. Unsigned builds install and update, with a SmartScreen warning on first install. An Authenticode certificate removes it.

Repository secrets read by the workflow:

Secret	Content
MAC_CSC_LINK	The Developer ID Application certificate exported as .p12, base64 encoded.
MAC_CSC_KEY_PASSWORD	Its password.
APPLE_ID	The Apple ID used for notarization.
APPLE_APP_SPECIFIC_PASSWORD	An app-specific password for that Apple ID.
APPLE_TEAM_ID	The team id shown in the Apple Developer account.
WIN_CSC_LINK	The Authenticode certificate as .pfx, base64 encoded. Optional.
WIN_CSC_KEY_PASSWORD	Its password. Optional.

Exporting a certificate to base64: base64 -i certificate.p12 | pbcopy on macOS.

Without the macOS secrets the workflow still produces a .dmg, unsigned, which is fine for testing on a Mac where Gatekeeper is bypassed with right-click › Open, but such a build cannot update itself.

The hardened-runtime entitlements are in assets/entitlements.mac.plist; the app is a menu bar item only (LSUIElement), so it never shows in the Dock.

Building locally

npm ci
npm run dist        # installers for the current platform into release/
npm run app         # run the desktop app from source

A local build is unsigned unless CSC_LINK/CSC_KEY_PASSWORD are exported in the shell. npm run dist on Linux produces an AppImage, which is not published but useful to check the packaging.

Versioning

Semantic versions. Bump the minor version when the protocol gains something the server has to know about, and mention it in the release notes; the server does not check the agent's version, so an old agent keeps working against a newer server as long as the endpoints it uses still exist.

Compatibility with the server

The agent reports its version on every heartbeat and it is shown on the settings page, which is how you find out which shops still run an old build. There is no server-side minimum version yet.