DEV Community

Cover image for Electron Release Engineering: A Practical Guide to Versioning, CI Build Matrices, Update Channels, Artifact Integrity, and Safe Rollbacks
mp3sss
mp3sss

Posted on AI-assisted

Electron Release Engineering: A Practical Guide to Versioning, CI Build Matrices, Update Channels, Artifact Integrity, and Safe Rollbacks

Shipping a web app mostly means deploying a new build to a server; users load the fresh code on their next request. An Electron release is the opposite: you produce native installers for Windows, macOS, and Linux, each signed and packaged for several architectures, host them somewhere a feed can read, keep update metadata in sync, and then decide which users actually move to which version. When something goes wrong, the fix is not a redeploy of one bundle — it is withdrawing or blocking a native build that may already be installed on thousands of machines. Release engineering for Electron is the layer between "the code works on my laptop" and "a built artifact can be safely signed, shipped, updated, and rolled back across platforms." This guide covers a single source of truth for version numbers, a CI build matrix that handles the platform and architecture combinations, where signing and notarization belong as gates, what update metadata actually contains, how release channels separate beta and stable audiences, how changelogs are generated from history, how artifact integrity is verified, and how to plan a rollback before you need one.

TL;DR

  • One version source. Keep the version in package.json (or a single manifest) and derive everything else from it; do not hand-edit installer metadata, about boxes, and feed files separately.
  • Build from tagged commits. CI should build release artifacts from an immutable git tag, and stamp the commit hash and channel into the build so every installed copy can report exactly what it is.
  • The matrix matters more than one happy path. Windows x64/arm64, macOS x64/arm64/universal, and Linux x64/arm64 each have their own toolchain; a release pipeline that only builds the machine you test on will ship broken installers elsewhere.
  • Signing and notarization are pipeline gates, not afterthoughts. A build that fails to sign must stop the release; do not publish unsigned installers "for now" and sign later.
  • Update metadata is generated, not written. The latest.yml, latest-mac.yml, latest-linux.yml, blockmaps, and checksums are produced alongside the installers; editing them by hand is how feeds desync from the artifacts.
  • Channels control who upgrades. Separate latest, beta, and nightly feeds so pre-release audiences validate a build before it reaches stable users; promotion between channels is a deliberate step, not an accident of upload order.
  • Verify integrity before and after publish. Checksum and signature checks should run in CI, and the feed should only expose artifacts that passed those checks.
  • Plan the rollback before the incident. Know how you will block a bad version, force a floor on the minimum supported version, and point a channel back to the last good build; practice it once on a non-production channel.

Table of contents

  1. Why Electron releases are harder than web releases
  2. Version strategy: one source of truth
  3. Version numbering in practice
  4. The release pipeline shape
  5. CI build matrix
  6. Signing and notarization as pipeline gates
  7. Build artifacts and update metadata
  8. Release channels: latest, beta, nightly
  9. Changelog and release notes
  10. Artifact integrity and verification
  11. Rollback and emergency response
  12. Common pitfalls
  13. Checklist

Why Electron releases are harder than web releases

A web deployment and an Electron release look similar at first — both run tests, produce a build, and publish somewhere. The differences show up the moment you have installed software on a user's machine.

Concern Web deployment Electron release
Delivery New code served on next request Native installer installed on the user's OS
Platforms One browser-compatible bundle Windows, macOS, Linux, each with packages and architectures
Trust HTTPS origin and browser warnings Code signature, macOS notarization, package repository trust
Update Server-side swap Client reads an update feed and downloads an installer/blockmap
Bad release Redeploy the old bundle Withdraw, block, or push a corrective native build
State Server controls the running version Many installed versions coexist until users update

The consequence is that an Electron release has more moving parts that cannot be changed after the fact. An installer already downloaded and installed keeps its signature and version; you cannot quietly patch it the way you would patch a deployed JavaScript bundle. That is why the pipeline — not the final upload — is where most release risk is managed.


Version strategy: one source of truth

The first release decision is where the version number lives. In Electron apps it can appear in several places: the version field of package.json, the productVersion some packagers read, the About dialog, the installer metadata, the update feed, and any telemetry that reports the running build. If these are maintained independently, you eventually ship an app whose About box says one version and whose feed metadata says another.

The reliable rule is a single manifest that everything else derives from.

Field Purpose Source
package.json version Canonical semver for the app Hand-edited or bumped by release tooling
productVersion Version shown in the installer/package metadata Derived from the canonical version unless you have a distinct marketing version
app.getVersion() Runtime version reported by the main process Reads the packaged package.json
Build metadata Commit hash, channel, build number Injected by CI at build time, not authored by hand

The main process should never hardcode a version string. It reads the packaged manifest at runtime:

// main process
const { app } = require('electron');

function getAppVersion() {
  // Reads the version baked into the packaged app; no hardcoded string.
  return app.getVersion();
}

function getBuildStamp() {
  // Injected at build time (see next section); safe to fall back to dev values.
  return {
    version: getAppVersion(),
    commit: process.env.APP_BUILD_COMMIT || 'dev',
    channel: process.env.APP_RELEASE_CHANNEL || 'dev',
  };
}

module.exports = { getAppVersion, getBuildStamp };
Enter fullscreen mode Exit fullscreen mode

If your packager supports a separate productVersion, keep it aligned to the canonical version by default; only introduce a marketing version when you genuinely need a different user-facing label, and document the mapping explicitly.


Version numbering in practice

Use semantic versioning: MAJOR.MINOR.PATCH, with pre-release suffixes for non-stable channels.

  • MAJOR for breaking changes that require migration or remove long-standing behavior.
  • MINOR for backward-compatible features.
  • PATCH for backward-compatible fixes.
  • Pre-release tags such as 1.4.0-beta.1 or 1.4.0-nightly.20261117 identify builds that must not land on the stable feed.

Beyond the semver number, every releaseable build should carry build metadata that identifies the exact source. CI injects the commit hash and channel as environment variables before packaging:

# .github/workflows/release.yml (excerpt)
env:
  APP_BUILD_COMMIT: ${{ github.sha }}
  APP_RELEASE_CHANNEL: ${{ github.ref_name }}
Enter fullscreen mode Exit fullscreen mode
// Renderer or telemetry payload
const stamp = {
  version: window.appBridge.getBuildStamp().version,
  commit: window.appBridge.getBuildStamp().commit,
  channel: window.appBridge.getBuildStamp().channel,
};
// Send this with crash reports and support tickets so a report can be traced
// to an exact build instead of a vague "latest version".
Enter fullscreen mode Exit fullscreen mode

A version that cannot be tied to a commit makes rollback and diagnosis guesswork: you cannot tell whether a reported issue exists in the shipped build, a local patch, or a stale cached installer.


The release pipeline shape

A safe Electron pipeline is a sequence of gates; a later gate should not run unless the earlier one passed.

Stage What happens Gate / artifact
Test Unit, integration, and e2e tests on the source commit Green test run; no release artifact yet
Build matrix Package installers for each platform and architecture Unsigned build outputs
Sign / notarize Sign Windows and macOS packages; notarize and staple macOS Signed, trusted installers
Verify Checksums, signature validation, feed metadata consistency Verified artifact set
Publish Upload to the channel feed and storage Publicly reachable channel metadata
Observe Track adoption, crash rates, update success Feedback that feeds the next release decision

Keeping these stages separate means a failed signature does not get hidden behind a successful upload. The pipeline should fail closed: if signing or verification does not pass, the artifacts are not published to any user-facing channel.


CI build matrix

The platform matrix is where most "works on my machine" releases break. Electron targets three OSes, and several of them ship more than one architecture.

OS Architectures to cover Common packages
Windows x64, arm64 NSIS installer, portable exe
macOS x64, arm64, universal DMG, zip; universal combines both slices
Linux x64, arm64 AppImage, deb, rpm as needed

A matrix workflow runs the packaging step once per combination. Caching the Node modules and the Electron download reduces build time, but native modules must be rebuilt for the target Electron ABI and architecture rather than reused from a host build.

# Excerpt: one packaging job per platform/architecture pair
strategy:
  fail-fast: false
  matrix:
    include:
      - os: windows-latest
        arch: x64 
      - os: windows-latest
        arch: arm64
      - os: macos-latest
        arch: arm64
      - os: macos-latest
        arch: x64
      - os: ubuntu-latest
        arch: x64
Enter fullscreen mode Exit fullscreen mode

fail-fast: false matters: one platform failing should not cancel the others, because you want the full set of failures visible before deciding what can ship. Each job should produce its own installer and its own update metadata, then hand both to the verification stage.


Signing and notarization as pipeline gates

Unsigned or unnotarized builds trigger OS warnings and, on macOS, Gatekeeper blocks that make the app look broken to users. Signing is not a cosmetic step; it is part of whether the installer can be trusted at all.

Platform Required action What it proves
Windows Authenticode sign the installer and main executable Publisher identity and that the binary was not tampered with after signing
macOS Codesign the app bundle, then notarize with Apple and staple the ticket App is signed and has been scanned by Apple's notarization service
Linux Maintain repository signing or package metadata where you host debs/rpms Package origin and integrity for the package manager

The pipeline should treat missing credentials or a notarization failure as a hard stop. Signing later, after an unsigned build has already been uploaded, means the early downloaders ran an untrusted binary. Store signing certificates and keys in the CI secret store, not in the repository, and keep the notarization ticket stapled into the macOS artifact so the validation works offline.


Build artifacts and update metadata

The installer is only one half of a release. The update feed also needs metadata that describes the latest version, the files, their hashes, and differential update blocks.

File Platform Contents
latest.yml Windows / generic Latest version, file names, SHA512 hashes, blockmap references
latest-mac.yml macOS Latest version, DMG/zip URLs, hashes, minimum system version
latest-linux.yml Linux Latest version, AppImage/package URLs and hashes
*.blockmap Differential updates Binary patch map for downloading only changed blocks

These files are generated by the packager alongside the installers. The rule is: never hand-edit feed metadata to force a version. If the metadata and the actual installer disagree, the updater either fails integrity checks or installs a mismatched build. After packaging, the verification stage should cross-check that every file referenced in the metadata exists, has the recorded hash, and matches the channel's version.


Release channels: latest, beta, nightly

Channels separate audiences so a build can be validated by early adopters before it reaches everyone.

Channel Audience Build shape Upgrade path
nightly Internal / power users Built from head or recent commits, pre-release version Feeds early feedback; not promoted automatically
beta Opt-in testers Release-candidate quality, pre-release tag Validated, then promoted to stable
latest All stable users Signed, verified release build Receives promoted beta builds only

The updater reads a channel-specific feed. Promoting a beta to stable is an explicit pipeline step that publishes the verified artifacts to the latest feed; it should not happen just because files were uploaded in a certain order. Keeping channels separate also means a bad nightly or beta build cannot corrupt the stable audience's update path.


Changelog and release notes

Users and support teams need to know what changed, and the changelog should come from project history rather than be written from memory at release time. Conventional commits — feat:, fix:, chore:, refactor:, and so on — let tooling generate a draft changelog grouped by change type.

feat: add per-window zoom persistence
fix: prevent tray menu from duplicating on second instance
chore: bump Electron to 33.x
refactor: split window manager from main process
Enter fullscreen mode Exit fullscreen mode

A generated changelog usually needs a human pass: group technical commits into user-visible notes, call out breaking changes and required migrations, and link the issues or pull requests that motivated the release. Keep two views if useful: a short user-facing release note for the About/update dialog, and a fuller technical changelog for support and audit.


Artifact integrity and verification

Integrity checks run both in CI and at update time. In CI, every published installer should be checksummed and signature-validated before it reaches the feed. At update time, the updater verifies the downloaded file against the hash and signature recorded in the metadata before installing.

Practical checks to keep in the pipeline:

  • Every installer referenced by a metadata file exists in the same channel directory.
  • Recorded SHA512 hashes match the actual uploaded files.
  • Windows binaries carry a valid Authenticode signature; macOS bundles are signed and notarized.
  • The version in the metadata matches the packaged app version for that artifact.
  • No artifact from another channel or architecture was copied into this channel's folder.

If you distribute installers outside the feed — direct download links, mirrors, internal shares — apply the same checks there; a mirror that serves an old or tampered installer bypasses the feed's integrity path.


Rollback and emergency response

A rollback plan should exist before a bad version reaches users. The goal is to stop the bad build from spreading and to bring affected installs back to a known-good state.

Action Purpose When to use it
Point the channel feed back to the last good version Stop new updates to the bad build Bad build detected before wide adoption
Blocklist the bad version Prevent already-updated installs from staying on a broken build Bad version is installed and causes crashes or data issues
Enforce a minimum supported version Force a floor below which the app must update A version has a critical security or data-corruption flaw
Ship a corrective patch build Deliver a fixed version to the affected audience The bad version cannot simply be uninstalled at scale

The main process can enforce a minimum version reported by a remote feed, so an unsupported build is prompted to update rather than kept running:

// Example: compare the local version against a server-provided minimum
const semver = require('semver');

function isVersionSupported(localVersion, minimumSupported) {
  return semver.gte(localVersion, minimumSupported);
}

// If false: show an update-required state and route the user to the stable feed.
Enter fullscreen mode Exit fullscreen mode

Before an incident, record which versions are known good, how to republish the previous feed, and how to reach the channel storage to withdraw artifacts. Test one rollback on a non-production channel so the runbook is not being improvised under pressure.


Common pitfalls

Pitfall Why it hurts Avoid it by
Version number edited in several places About box, installer, and feed disagree One canonical manifest; derive the rest
Building release artifacts on a developer machine Missing platform toolchain, stale caches, unreproducible build Build only in CI from tagged commits
Ignoring one architecture in the matrix Users on that CPU get an installer that fails to run Run the full OS/arch matrix; do not assume x64 covers arm64
Publishing unsigned builds and signing later Early downloaders ran untrusted binaries; signature cannot be retroactively applied cleanly Make signing/notarization a hard publish gate
Hand-editing latest*.yml Feed and installer hashes desync; updater fails integrity checks Let the packager generate metadata; verify, don't edit
Mixing channel artifacts in one folder Testers and stable users pull the wrong build Separate channel directories and explicit promotion
No commit hash in the build Reports cannot be traced to an exact source Inject commit and channel at build time
No rollback runbook Incident response improvises under pressure Practice a feed rollback on a test channel beforehand
Mirrors skip integrity checks Old or tampered installers bypass the feed Apply hash/signature checks to every distribution path

Checklist

  1. The version lives in one manifest and is read at runtime via app.getVersion(), not hardcoded.
  2. Release builds come from immutable git tags, with commit hash and channel injected into the build.
  3. The CI matrix covers your supported OSes and architectures, with fail-fast: false so all failures are visible.
  4. Native modules are rebuilt for the target Electron ABI and architecture; host build artifacts are not reused.
  5. Signing and notarization are hard gates; a failed credential or validation stops publish.
  6. Update metadata is generated by the packager and verified against the uploaded installers.
  7. nightly, beta, and latest channels have separate feeds, and promotion is an explicit step.
  8. Changelog drafts are generated from conventional commits and reviewed for user-visible notes and breaking changes.
  9. Every distribution path (feed, direct download, mirror) enforces checksum and signature verification.
  10. A rollback runbook exists: known-good versions, feed republish steps, version blocklist, and minimum-version enforcement.

Top comments (1)

Collapse
 
skepagent profile image
SkepAgent •

The part about treating signing and notarization as hard pipeline gates rather than a step you bolt on later is the bit I'd underline — I've seen teams ship an unsigned build "temporarily" and then spend weeks chasing the trust fallout. The fail-fast: false matrix note is a good call too: you want the full failure picture across architectures instead of stopping at the first broken one. Have you ever had to actually roll a channel feed back to a previous version in production, and did the blocklist or the minimum-version floor end up doing the heavy lifting?