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

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

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

Why Electron releases are harder than web releases Version strategy: one source of truth Version numbering in practice The release pipeline shape CI build matrix Signing and notarization as pipeline gates Build artifacts and update metadata Release channels: latest, beta, nightly Changelog and release notes Artifact integrity and verification Rollback and emergency response Common pitfalls 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 };

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 }}
// 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".

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

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

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 bina
Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.