Changelog

• awsCredentials.source is required to publish (no default, no implicit credentials).
• awsCredentials.source: "env" reads only AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN, or the variable names given in awsCredentials.env.
• awsCredentials.source: "profile" with profile (plus optional credentialsFile / configFile) reads a named profile from the shared config and credentials files: static keys, IAM Identity Center (SSO), credential_process and assume-role. The AWS SDK providers are loaded lazily, only for non-static profiles, and are given explicit paths. Assume-role hops use an explicitly configured STS client (named profile's region, no configured endpoint URLs). credential_source and web identity (web_identity_token_file) are rejected anywhere in the chain, before the SDK is loaded.
• awsCredentials.source: "sso-role-chain" with profile resolves an assume-role profile whose source_profile chain (up to 5 hops, no cycles) starts at an IAM Identity Center (SSO) profile: the SSO profile is resolved from the configured files, then STS AssumeRole is called per hop with explicit region, endpoint and credentials (never AWS_REGION, AWS_PROFILE or AWS_ENDPOINT_URL*). credential_source, mfa_serial, web identity and credential_process are rejected in the chain. source: "profile" keeps rejecting SSO-sourced role chains and points to this source.
• Resolved credentials are reused for every file of a publish instead of being resolved again per upload.

BREAKING CHANGE: S3 publishing fails with an InvalidConfigurationError unless awsCredentials.source is set (add { "source": "env" } to keep using AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY). AWS_PROFILE, AWS_SDK_LOAD_CONFIG, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE and an implicit ~/.aws/credentials are no longer read. Missing credentials now fail with a clear error instead of an unsigned or env-fallback signature. For dotted bucket names without region, the region is looked up only when publishing. awsCredentials is never written to app-update.yml.

BREAKING CHANGE: when updateManifest.publicKey is set explicitly and none of the keys the build signs update manifests with is in it, a publishing build now fails at build start, before anything is packed or uploaded, with an InvalidConfigurationError naming the key ids of the signing keys and of the listed keys (never key material). Such a release embeds no key it is signed with, so its installs would reject manifests signed with the current key(s). This was a warning before; a build without a publish policy still only warns. For a deliberate cutover release that is signed with the old key but embeds only the new one, set the new updateManifest.allowSigningKeyOutsideTrustList: true (explicit config only) to keep the warning. Nothing changes when publicKey is not set, since the trust list is then derived from the signing keys. See the v27 breaking changes guide.

• awsCredentials.source is required to publish (no default, no implicit credentials).
• awsCredentials.source: "env" reads only AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN, or the variable names given in awsCredentials.env.
• awsCredentials.source: "profile" with profile (plus optional credentialsFile / configFile) reads a named profile from the shared config and credentials files: static keys, IAM Identity Center (SSO), credential_process and assume-role. The AWS SDK providers are loaded lazily, only for non-static profiles, and are given explicit paths. Assume-role hops use an explicitly configured STS client (named profile's region, no configured endpoint URLs). credential_source and web identity (web_identity_token_file) are rejected anywhere in the chain, before the SDK is loaded.
• awsCredentials.source: "sso-role-chain" with profile resolves an assume-role profile whose source_profile chain (up to 5 hops, no cycles) starts at an IAM Identity Center (SSO) profile: the SSO profile is resolved from the configured files, then STS AssumeRole is called per hop with explicit region, endpoint and credentials (never AWS_REGION, AWS_PROFILE or AWS_ENDPOINT_URL*). credential_source, mfa_serial, web identity and credential_process are rejected in the chain. source: "profile" keeps rejecting SSO-sourced role chains and points to this source.
• Resolved credentials are reused for every file of a publish instead of being resolved again per upload.

BREAKING CHANGE: S3 publishing fails with an InvalidConfigurationError unless awsCredentials.source is set (add { "source": "env" } to keep using AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY). AWS_PROFILE, AWS_SDK_LOAD_CONFIG, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE and an implicit ~/.aws/credentials are no longer read. Missing credentials now fail with a clear error instead of an unsigned or env-fallback signature. For dotted bucket names without region, the region is looked up only when publishing. awsCredentials is never written to app-update.yml.

The three file-copy lists live in a fileOptions?: FilesBuildOptions | null property at the configuration root and in every platform section (mac, mas, masDev, win, linux), the same way directories groups the build directories: fileOptions.files, mac.fileOptions.extraResources, and so on. PlatformSpecificBuildOptions does not extend FilesBuildOptions, and the TypeScript types and the JSON schema only have fileOptions.

Flat files / extraResources / extraFiles keys in a config file, an extends parent, a -c.files=… override or the config object passed to build() are applied as their fileOptions counterparts before the configuration is validated, logging one warning per process that names the keys found and where they belong. When a flat key and its fileOptions counterpart are set on the same object, fileOptions wins and the build warns about the conflict. A CLI override or a parent config's flat key is merged with fileOptions. A fileOptions that is not an object (for example a list of globs written directly under it) fails the build with a message showing the nested form.

Code that reads files, extraResources or extraFiles from the loaded configuration (for example a hook reading context.packager.config.files, or buildResult.configuration.extraResources) gets the fileOptions value, with a warning per key: the loaded configuration and its platform sections forward these reads through non-enumerable properties, which stay out of the effective config, JSON.stringify and Object.keys. Assigning them throws a configuration error naming the fileOptions property to set instead.

deepAssign (builder-util-runtime) copies only enumerable own properties, so the forwarding properties are never copied into merged options.

electron-builder migrate-schema (static and JS/TS configs) moves flat keys under fileOptions at the root and per platform. A flat key also set under fileOptions is removed with a warning, since the build ignores it.

See https://www.electron.build/docs/migration/v27-breaking-changes#file-options-fileoptions

The flatpak target now runs flatpak and flatpak-builder itself, and the @malept/flatpak-bundler dependency is removed. A failed command prints the tool's output in the build error, and five known failures (Failure spawning rofiles-fuse, a bwrap: failure in flatpak build-export, No remote refs found, Command 'electron-wrapper' not found when rofiles-fuse cannot mount the app directory, and execvp appstream-compose when a flatpak-builder older than 1.4 composes AppStream metadata with the freedesktop SDK 24.08 or newer) log how to fix them first. A build with flatpak.modules warns once when flatpak-builder is older than 1.4.4, which the 24.08 and newer SDKs recommend for meson and cmake modules. The scratch directory is removed when the build ends.

New options:

• flatpak.additionalArgs passes extra arguments to the tools, by tool: flatpakBuilder, buildExport and buildBundle. With { flatpakBuilder: ["--disable-rofiles-fuse"], buildExport: ["--disable-sandbox"] } the target builds in CI containers that have neither FUSE nor user namespaces (#10306).
• flatpak.installOrUpdateRefs, "all" (the default) or a list of "runtime", "sdk" and "base": the refs that are left out are used as installed, without a flatpak install or flatpak update, and a missing one fails the build before anything is downloaded. [] builds with the refs of an image or an offline machine, and where the build user cannot update the base app (based on the options proposed in #10313).

BREAKING CHANGE: flatpak >= 1.12.4 and flatpak-builder >= 1.2.2 are required, and checked before a runtime is installed. The stock packages of Ubuntu 22.04, Debian 12, RHEL 8 and 9 and newer releases meet this; v26 accepted older tools. DEBUG=@malept/flatpak-bundler no longer has any effect, and a flatpak build warns once when DEBUG still names it: use DEBUG=electron-builder to log every command.

BREAKING CHANGE: flatpak.runtimeVersion and flatpak.baseVersion default to 26.08 instead of 20.08, which Flathub reports as end-of-life. A build that sets neither is built for the 26.08 runtime, and the build machine installs the 26.08 runtime, SDK and base app if they are missing (about 3.2 GB). A build that leaves either option unset warns once, naming electron-builder v27 and the migration guide. Set both to "20.08" to keep the previous ones.

BREAKING CHANGE: the default flatpak.finishArgs grant --filesystem=xdg-download instead of --filesystem=home: with read/write access to the home directory, code running in the app could write ~/.config/autostart or ~/.bashrc and so run outside the sandbox at the next login. App data under ~/.var/app and files picked in a dialog are not affected; paths the app opens on its own outside Downloads are. They also leave out --talk-name=org.freedesktop.Notifications unless the base is org.electronjs.Electron2.BaseApp older than 23.08, whose libnotify predates the notification portal; on desktops without a portal backend for notifications, notifications no longer appear. Builds that set flatpak.finishArgs are not affected, and a build that uses the defaults warns once, naming electron-builder v27 and the migration guide. To keep the v26 permissions, set finishArgs to the v26 list from the migration guide.

BREAKING CHANGE: a flatpak.files destination or a flatpak.symlinks link that leaves the app prefix with .. fails the build with an InvalidConfigurationError, before anything is installed. It was written outside the app in the build directory, for example over the app's metadata. The pairs of flatpak.files are copied one after another, and a directory can no longer be copied onto a symlink to a directory: v26 copied through the link, and the build now fails with Cannot overwrite non-directory with directory (ERR_FS_CP_DIR_TO_NON_DIR). Symlinks inside a copied directory are kept as they are. The errors of the tool-version check and of the app-prefix check say that they are new in electron-builder v27 and link the migration guide.

• Added warnOnRemovedEnvVars() (registry in app-builder-lib/src/util/removedEnvVars.ts), invoked once per build from the Packager constructor so both the CLI and programmatic build() API surface the same guidance. When a removed variable is still present in the environment it is otherwise silently ignored — this logs a one-time deprecation warning naming the variable and its replacement.
• Covers the removed toolset-path overrides (APPIMAGE_TOOLS_PATH, MKSQUASHFS_PATH, LINUX_TOOLS_MAC_PATH, CUSTOM_FPM_PATH, ELECTRON_BUILDER_NSIS_DIR, ELECTRON_BUILDER_NSIS_RESOURCES_DIR, CUSTOM_NSIS_RESOURCES, ELECTRON_BUILDER_WINE_TOOLSET_DIR, ELECTRON_BUILDER_7ZIP_PATH, ELECTRON_BUILDER_ICONS_TOOLSET_DIR, ELECTRON_BUILDER_OSSL_SIGNCODE_PATH, ELECTRON_BUILDER_RCEDIT_PATH, ELECTRON_BUILDER_WINDOWS_KITS_PATH, SIGNTOOL_PATH) → toolsets.* / win.sign; the USE_SYSTEM_* toggles; ELECTRON_BUILDER_BINARIES_ALLOW_HTTP → ELECTRON_BUILDER_DANGEROUSLY_ALLOW_HTTP; CI_BUILD_TAG → CI_COMMIT_TAG; and ALLOW_ELECTRON_BUILDER_AS_PRODUCTION_DEPENDENCY → ignoredProductionDependencies.
• Internal/test-only variables (JEST_WORKER_ID, TEST_SET_BABEL_PRESET) and npm_lifecycle_event (set by npm for every script) are intentionally excluded from the runtime scan.
• Migration docs: filled the previously undocumented removed vars in the v27 breaking-changes catalogue (the toolset-path family plus MKSQUASHFS_PATH), added a "Replace with" column, and documented the ELECTRON_BUILDER_BINARIES_ALLOW_HTTP rename and the removed npm run release implicit-publish behavior.

• Warns once per build when --no-sandbox reaches the flatpak's electron-wrapper, naming linux.executableArgs and/or flatpak.executableArgs as its source: inside flatpak, Chromium's sandbox works through zypak, and the flag gives renderer processes every permission of the app. The flag is kept. linux.executableArgs are merged into the flatpak options, and an empty flatpak.executableArgs adds nothing: --no-sandbox for the AppImage alone belongs in appImage.executableArgs, and flatpak.executableArgs: null leaves all of linux.executableArgs out of the flatpak.
• Warns once per build when the flatpak id is derived from the package name (neither linux.appId nor appId is set: the id names the app's ~/.var/app/<id> data directory, and another vendor's bundle with the same com.electron.<name> id installs over the app), and when desktopName is set but is not <flatpak id>.desktop (the bundle's desktop entry is named after the id, and Electron names the app's windows after desktopName, so desktops cannot match the two).
• The electron-wrapper script replaces itself with the app (exec) instead of staying as its parent shell, and tests the session with the POSIX =: the == failed with "unexpected operator" where /bin/sh is dash, and dropped the Wayland flags.
• flatpak.useWaylandFlags picks its flags by Electron version: none from Electron 38, which chooses Wayland by itself in a Wayland session (the build logs that the option has no effect), --ozone-platform=wayland from Electron 16, and --enable-features=UseOzonePlatform --ozone-platform=wayland before that or for an unknown version. From Electron 16 the wrapper no longer adds a second --enable-features, which could replace one in executableArgs; a build with Electron 16 to 37 warns once about the change, naming electron-builder v27 and the migration guide.
• An invalid flatpak id (fewer than three elements, an empty element or one starting with a digit, more than 255 characters), such as com.myapp or com.electron.3d_viewer from a package named 3d-viewer, fails the build before the runtime, SDK and base app are installed, with an InvalidConfigurationError naming the rule. It failed in flatpak-builder, after those were installed (about 3.2 GB for the default version).
• The __flatpak-<arch> stage directory is removed from the output directory when preparing it fails, for example on an invalid desktop entry or a missing license file.
• The MIME types of fileAssociations (every mimeType that is set) are declared in the bundle's share/mime/packages/<id>.xml, which flatpak exports, as the AppImage and deb/rpm targets do: the desktop entry listed the types, but nothing defined a custom one. Set mimeType only for a type of your own: each is declared with the description <productName> document, which for a standard type such as text/markdown can change how the desktop describes every such file. List standard types in linux.mimeTypes, which only adds them to the desktop entry.

The desktop entry of every Linux target that writes one is checked before it is written, so a configuration can no longer produce a corrupt .desktop file. The build fails with an InvalidConfigurationError naming the group and the key for a value with \r or \n inside it (from linux.desktop.entry, desktopActions, linux.category, linux.mimeTypes, fileAssociations or protocols), whose second line would become a new key or group of the file; a key that GLib, which most desktops read the file with, rejects (empty, or with =, a line break, or brackets other than a trailing locale such as Name[de]), which makes it ignore the whole file; and a desktopActions name with [, ] or a control character. Write such a value on one line, with a newline in a string value as \n. Line breaks at the end of a value, as in a YAML block scalar, are dropped, and values are otherwise still written as given, so escapes such as \; keep working. Keys that the specification does not allow but desktop environments read, such as X_Foo, are kept.

The three file-copy lists live in a fileOptions?: FilesBuildOptions | null property at the configuration root and in every platform section (mac, mas, masDev, win, linux), the same way directories groups the build directories: fileOptions.files, mac.fileOptions.extraResources, and so on. PlatformSpecificBuildOptions does not extend FilesBuildOptions, and the TypeScript types and the JSON schema only have fileOptions.

Flat files / extraResources / extraFiles keys in a config file, an extends parent, a -c.files=… override or the config object passed to build() are applied as their fileOptions counterparts before the configuration is validated, logging one warning per process that names the keys found and where they belong. When a flat key and its fileOptions counterpart are set on the same object, fileOptions wins and the build warns about the conflict. A CLI override or a parent config's flat key is merged with fileOptions. A fileOptions that is not an object (for example a list of globs written directly under it) fails the build with a message showing the nested form.

Code that reads files, extraResources or extraFiles from the loaded configuration (for example a hook reading context.packager.config.files, or buildResult.configuration.extraResources) gets the fileOptions value, with a warning per key: the loaded configuration and its platform sections forward these reads through non-enumerable properties, which stay out of the effective config, JSON.stringify and Object.keys. Assigning them throws a configuration error naming the fileOptions property to set instead.

deepAssign (builder-util-runtime) copies only enumerable own properties, so the forwarding properties are never copied into merged options.

electron-builder migrate-schema (static and JS/TS configs) moves flat keys under fileOptions at the root and per platform. A flat key also set under fileOptions is removed with a warning, since the build ignores it.

See https://www.electron.build/docs/migration/v27-breaking-changes#file-options-fileoptions

BREAKING CHANGE: signing auto-update manifests is now REQUIRED by default. A build with a publish policy (--publish) that includes a target writing auto-update metadata (latest*.yml: NSIS, AppImage, deb/rpm/pacman, macOS zip/dmg, AppX with electronUpdaterAware) fails when no Ed25519 signing key resolves. The check runs at build start, before anything is packed or uploaded, so no artifact of that build is published; a build of only targets that write no update info (snap, flatpak, MSI/MSIX, portable, mas/pkg, plain archives) needs no key. Third-party targets declare update info with the new Target.writesUpdateInfo getter; one that does not is still checked, but only when its own artifact is created. The error names electron-builder create-update-key and the ELECTRON_BUILDER_UPDATE_SIGN_KEY / ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE environment variables (updateManifest.signingKey / signingKeyFile work too). A build without a publish policy only warns, so local builds are unaffected. To keep publishing unsigned manifests, set updateManifest: false - the only opt-out; every build that emits a manifest then logs a warning, and false also short-circuits the signing-key environment variables, so a leftover CI secret cannot re-enable signing behind the opt-out. updateManifest: null is not an opt-out. A platform block may be false on its own and shadows a root signing config for that platform, while a platform null still falls back to the root. publishAutoUpdate: false waives the requirement only when every publish provider sets it (no manifest is emitted then); a single provider that still emits a manifest keeps it enforced. A publicKey with no private key does not satisfy it. Because installs that carry a public key are fail-closed, do not switch to updateManifest: false after shipping signed manifests - those installs would refuse every further update. getAppUpdatePublishConfiguration (exported for third-party targets) can now throw for this reason. See the v27 breaking changes guide.

Ed25519 signing of auto-update manifests (latest*.yml). Each manifest is signed over its integrity-critical fields with the keys from updateManifest.signingKey/signingKeyFile or the ELECTRON_BUILDER_UPDATE_SIGN_KEY/ ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE env vars, and the matching public keys are embedded into app-update.yml (both resolved from the same keys on the platform packager, so signing and embedding cannot disagree). electron-updater verifies the signature before downloading and refuses to update on tamper/missing-signature (fail-closed). Installs built before a public key existed keep skipping verification with a one-time warning. New CLI: electron-builder create-update-key (prints the public key and its key id).

Key rotation without a flag day: an install trusts a list of public keys (updateManifestPublicKey is a string or an array; updateManifest.publicKey, signingKey and signingKeyFile accept arrays, a PEM value may hold several concatenated keys, and ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE accepts several paths joined with the OS path delimiter), and a manifest may carry several signatures (signatures: [{ keyId, signature }], one per signing key, next to the legacy signature of the first key). A manifest is accepted when any trusted key validates any of its signatures, so a release signed with [old, new] verifies on installs that trust either. AppUpdater.updateManifestPublicKey accepts a string or an array. A build-time warning flags an explicit publicKey list that contains none of the signing keys.

app-update.yml (the embedded feed and trust list) now follows the targets that write update info: each packaged app embeds the first manifest-receiving provider of the publish settings of its manifest-emitting targets (NSIS/NSIS web, AppX with electronUpdaterAware, macOS dmg/zip, AppImage, deb/rpm/pacman), resolving target, then platform, then top level, instead of the platform/top-level publish only. A build with only nsis.publish therefore ships that feed and the key verifying its signed manifests, where it used to ship no app-update.yml (or, with a GitHub repository, a GitHub feed while the manifests went elsewhere). With no such target (snap-only, publish: null or publishAutoUpdate: false on the target) the platform/top-level settings apply as before, including the GitHub fallback. AppImage and deb/rpm/pacman honor appImage.publish/deb.publish etc. for the file they write. When two targets built from the same app (e.g. dmg and zip, or nsis and an updater-aware appx) resolve different feeds (first providers that differ in more than upload-only options such as publishAutoUpdate or timeout), a publishing build fails at build start with an InvalidConfigurationError; a build without a publish policy warns that publishing will fail and writes no app-update.yml for that app. Configure publish once at the platform level, or give those targets the same first provider. getAppUpdatePublishConfiguration now honors the target-specific options passed to it. A provider with publishAutoUpdate: false is no longer embedded as the feed when a later provider receives the manifest (e.g. [{ provider: "s3", publishAutoUpdate: false }, "github"] now embeds GitHub instead of an S3 feed that never gets a latest*.yml).

Gating of the Linux package-manager signature-bypass flags landed separately as AppUpdater.allowUnverifiedLinuxPackages (#9990).

v27 had stopped using a custom NSIS bundle set via nsis.customNsisBinary (also on nsisWeb / portable) or customNsisResources and silently built with the default NSIS. Both keys and the exported CustomNsisBinary type are now removed, and a config that sets them fails the build with a message naming the replacement:

• a custom NSIS build moves to toolsets.nsis: { url, checksum, version }. The url and the v26 base64 SHA-512 checksum work as before (see https://www.electron.build/docs/toolsets#custom-toolset-checksum), but the bundle must contain the NSIS plugins (plugins/ or windows/Plugins/), which v26 read from a separate resources bundle
• customNsisBinary.debugLogging becomes nsis.installerDebugLogging (also on nsisWeb). It needs a log-enabled NSIS (makensis and stubs compiled with NSIS_CONFIG_LOG=yes), which the bundled toolsets.nsis versions are not, so setting it without a custom toolsets.nsis now fails with a configuration error instead of a LogSet error from makensis

electron-builder migrate-schema (static and JS/TS configs) moves debugLogging to installerDebugLogging (dropping it, with a warning, for portable, where it had no effect) and removes a customNsisBinary that sets nothing else. It leaves a custom bundle in place and warns, without printing its url or checksum, because the bundle itself has to change.

Any custom toolset (toolsets.<name>: { url, checksum }) with a checksum that is neither a SHA-256 hex value nor a base64 SHA-512 (for example a sha256: prefixed value) now fails with a configuration error linking to https://www.electron.build/docs/toolsets#custom-toolset-checksum before anything is downloaded, instead of a generic checksum mismatch afterwards. An uppercase hex value is lowercased.

When migrate-schema finds no config, its error now lists every auto-detected file name (including electron-builder.mjs) and says that a config file with another name needs --config <path>.

NSIS installers now write a resources/package-type marker (nsis or nsis-web) at install time, mirroring the existing Linux package-type mechanism. electron-updater's NsisUpdater reads this marker and, for nsis-web installs, pre-seeds disableWebInstaller = false so web-installer auto-updates keep working without the app wiring the flag by hand.

This is a default only: a value the app sets (autoUpdater.disableWebInstaller = …) still wins, and a plain nsis marker, or no marker, leaves the default (true), so web-installer updates are rejected with ERR_UPDATER_WEB_INSTALLER_DISABLED. The marker is written by the installer script — the only build artifact that differs between nsis and nsis-web (the app payload is byte-identical, since both targets share one app archive). Only go-forward installs carry the marker; existing deployments are unaffected.

toolsets.<name>.checksum now accepts the base64-encoded SHA-512 of the archive (88 characters, e.g. openssl dgst -sha512 -binary <archive> | openssl base64 -A) as well as the SHA-256 hex. v26 used base64 SHA-512 for all toolset checksums, so a v26 value carries over unchanged. v27 defaults to SHA-256 hex because toolset downloads moved to the official @electron/get package, whose checksum verification (sumchecker) only supports SHA-256 hex, so a SHA-512 download is verified by electron-builder before it is cached or extracted, and a corrupted download is deleted. A local file:// archive is now verified against its checksum before it is extracted; on a mismatch the build fails with a configuration error naming the file and both checksums, and the file is left in place. Prefixed values (sha256:…, sha512-…) and a hex-encoded SHA-512 are still rejected before anything is downloaded. See https://www.electron.build/docs/toolsets#custom-toolset-checksum

Note for apps already shipping "store-asar" (available since 26.x via #10201 and 27.0.0-alpha.9): the block boundaries inside the asar region change once. The first differential update from an installer built without this change to one built with it re-downloads close to the whole asar; updates between installers built with it get the smaller deltas.

codesign --sign was given the certificate's common name, which fails with ambiguous (matches "X" and "X" ...) when the keychain holds more than one valid certificate with that name. It is now given the certificate's SHA-1 hash, which is unique.

@electron/osx-sign parses the Team ID out of the identity name to fill in ElectronTeamID for sandboxed (MAS) apps, so electron-builder now writes that key into the app's Info.plist itself before signing — the same value from the same source — instead of relying on the identity string carrying it. A custom signer replaces osx-sign entirely, so it keeps receiving the bare hash and its Info.plist is left untouched.

Also fixes savePlistFile destroying <data> and <date> values, which it rewrote as a <dict> of byte integers and an empty <dict> respectively.

AppUpdater.verifyUpdateFile lets an app run its own verification of an update file before that file is allowed to become installable. The default implementation is a stub that immediately succeeds. It runs on every path that can lead to an install — right after a fresh download (while the file still sits under a temporary name, so an unverified file is never executable under its real name), when an update downloaded by an earlier session is reused from the cache, and before an install-on-next-launch spawns the cached installer. On failure the file is deleted and an ERR_UPDATER_INVALID_UPDATE_FILE error is emitted. Assigning null restores the default.

The NSIS Authenticode verification interface now returns an unambiguous result object instead of the null-means-success / string-means-error convention:

type VerifyUpdateFileResult = { response: "success" } | { response: "failure"; message: string }

BREAKING CHANGE: NsisUpdater.verifyUpdateCodeSignature is deprecated in favour of verifyUpdateFileAuthenticodeSignature, which differs in return type. The old name is kept as a compatibility shim that translates in both directions and shall be removed in electron-builder v28.

// Before
autoUpdater.verifyUpdateCodeSignature = async (publisherNames, path) => (isValid ? null : "why it failed")

// After
autoUpdater.verifyUpdateFileAuthenticodeSignature = async (publisherNames, path) =>
  isValid ? { response: "success" } : { response: "failure", message: "why it failed" }

BREAKING CHANGE: the protected NsisUpdater._verifyUpdateCodeSignature member is renamed to _verifyUpdateFileAuthenticodeSignature and takes the new return type. A deprecated accessor under the old name forwards to it, so a subclass that assigns this._verifyUpdateCodeSignature keeps working; a subclass that redeclares it as a class field shadows the accessor and must be migrated.

BREAKING CHANGE: the protected BaseUpdater.verifyInstallerSignatureOnLaunch returns Promise<VerifyUpdateFileResult> instead of Promise<string | null>. An override that resolves null to mean "verified" now reports every install-on-next-launch as unsigned; return { response: "success" } instead. (This member was introduced earlier in the same v27 pre-release cycle, so only apps on a 7.0.0-alpha are affected.)

BREAKING CHANGE: AppUpdater.disableWebInstaller now defaults to true. NSIS web-installer packages are no longer loaded unless you opt in, because their payload is fetched from a manifest-supplied URL that may not undergo signature verification.

A web-installer update is rejected with ERR_UPDATER_WEB_INSTALLER_DISABLED unless disableWebInstaller is false. Installs made by an nsis-web installer built with electron-builder v27+ opt in automatically through the resources/package-type marker. If you publish and rely on an NSIS web installer for other installs, set autoUpdater.disableWebInstaller = false in your main process.

BREAKING CHANGE: signing auto-update manifests is now REQUIRED by default. A build with a publish policy (--publish) that includes a target writing auto-update metadata (latest*.yml: NSIS, AppImage, deb/rpm/pacman, macOS zip/dmg, AppX with electronUpdaterAware) fails when no Ed25519 signing key resolves. The check runs at build start, before anything is packed or uploaded, so no artifact of that build is published; a build of only targets that write no update info (snap, flatpak, MSI/MSIX, portable, mas/pkg, plain archives) needs no key. Third-party targets declare update info with the new Target.writesUpdateInfo getter; one that does not is still checked, but only when its own artifact is created. The error names electron-builder create-update-key and the ELECTRON_BUILDER_UPDATE_SIGN_KEY / ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE environment variables (updateManifest.signingKey / signingKeyFile work too). A build without a publish policy only warns, so local builds are unaffected. To keep publishing unsigned manifests, set updateManifest: false - the only opt-out; every build that emits a manifest then logs a warning, and false also short-circuits the signing-key environment variables, so a leftover CI secret cannot re-enable signing behind the opt-out. updateManifest: null is not an opt-out. A platform block may be false on its own and shadows a root signing config for that platform, while a platform null still falls back to the root. publishAutoUpdate: false waives the requirement only when every publish provider sets it (no manifest is emitted then); a single provider that still emits a manifest keeps it enforced. A publicKey with no private key does not satisfy it. Because installs that carry a public key are fail-closed, do not switch to updateManifest: false after shipping signed manifests - those installs would refuse every further update. getAppUpdatePublishConfiguration (exported for third-party targets) can now throw for this reason. See the v27 breaking changes guide.

Ed25519 signing of auto-update manifests (latest*.yml). Each manifest is signed over its integrity-critical fields with the keys from updateManifest.signingKey/signingKeyFile or the ELECTRON_BUILDER_UPDATE_SIGN_KEY/ ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE env vars, and the matching public keys are embedded into app-update.yml (both resolved from the same keys on the platform packager, so signing and embedding cannot disagree). electron-updater verifies the signature before downloading and refuses to update on tamper/missing-signature (fail-closed). Installs built before a public key existed keep skipping verification with a one-time warning. New CLI: electron-builder create-update-key (prints the public key and its key id).

Key rotation without a flag day: an install trusts a list of public keys (updateManifestPublicKey is a string or an array; updateManifest.publicKey, signingKey and signingKeyFile accept arrays, a PEM value may hold several concatenated keys, and ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE accepts several paths joined with the OS path delimiter), and a manifest may carry several signatures (signatures: [{ keyId, signature }], one per signing key, next to the legacy signature of the first key). A manifest is accepted when any trusted key validates any of its signatures, so a release signed with [old, new] verifies on installs that trust either. AppUpdater.updateManifestPublicKey accepts a string or an array. A build-time warning flags an explicit publicKey list that contains none of the signing keys.

app-update.yml (the embedded feed and trust list) now follows the targets that write update info: each packaged app embeds the first manifest-receiving provider of the publish settings of its manifest-emitting targets (NSIS/NSIS web, AppX with electronUpdaterAware, macOS dmg/zip, AppImage, deb/rpm/pacman), resolving target, then platform, then top level, instead of the platform/top-level publish only. A build with only nsis.publish therefore ships that feed and the key verifying its signed manifests, where it used to ship no app-update.yml (or, with a GitHub repository, a GitHub feed while the manifests went elsewhere). With no such target (snap-only, publish: null or publishAutoUpdate: false on the target) the platform/top-level settings apply as before, including the GitHub fallback. AppImage and deb/rpm/pacman honor appImage.publish/deb.publish etc. for the file they write. When two targets built from the same app (e.g. dmg and zip, or nsis and an updater-aware appx) resolve different feeds (first providers that differ in more than upload-only options such as publishAutoUpdate or timeout), a publishing build fails at build start with an InvalidConfigurationError; a build without a publish policy warns that publishing will fail and writes no app-update.yml for that app. Configure publish once at the platform level, or give those targets the same first provider. getAppUpdatePublishConfiguration now honors the target-specific options passed to it. A provider with publishAutoUpdate: false is no longer embedded as the feed when a later provider receives the manifest (e.g. [{ provider: "s3", publishAutoUpdate: false }, "github"] now embeds GitHub instead of an S3 feed that never gets a latest*.yml).

Gating of the Linux package-manager signature-bypass flags landed separately as AppUpdater.allowUnverifiedLinuxPackages (#9990).

NSIS installers now write a resources/package-type marker (nsis or nsis-web) at install time, mirroring the existing Linux package-type mechanism. electron-updater's NsisUpdater reads this marker and, for nsis-web installs, pre-seeds disableWebInstaller = false so web-installer auto-updates keep working without the app wiring the flag by hand.

This is a default only: a value the app sets (autoUpdater.disableWebInstaller = …) still wins, and a plain nsis marker, or no marker, leaves the default (true), so web-installer updates are rejected with ERR_UPDATER_WEB_INSTALLER_DISABLED. The marker is written by the installer script — the only build artifact that differs between nsis and nsis-web (the app payload is byte-identical, since both targets share one app archive). Only go-forward installs carry the marker; existing deployments are unaffected.

BREAKING: the squirrelWindows.customSquirrelVendorDir option has been removed. Supply a custom Squirrel vendor bundle with the toolsets.squirrel config (a ToolsetCustom object) instead — it goes through the same rcedit/WiX provisioning as the default bundle.

"system" runs Windows tools with the host wine on PATH, restoring the capability of the USE_SYSTEM_WINE env var removed in v27. The host-wine branch already existed but was reachable only on Linux, so macOS had no way to opt out of the downloaded bundle: ToolsetCustom requires the directory to contain a prebuilt wine-home prefix, which a real Wine installation does not have.

Behaviour change: "latest" — the default — now resolves to "system" rather than the "1.0.1" bundle, so building a Windows target on macOS requires Wine to be installed (brew install --cask wine-stable). The published wine@1.0.1 bundles ship no PE builtins (lib/wine/<arch>-windows is deleted at package time), so they cannot execute any Windows binary; toolsets.wine: "1.0.1" still resolves and downloads for anyone pinning it explicitly. Linux already defaulted to the host Wine.

fix(msi): only emit Icon="…" on shortcuts and ProgIds when the app has an icon

The MSI template declares <Icon Id="…"/> only when iconPath is set, but MsiTarget referenced that id unconditionally, so building an MSI for an app without an icon failed in light.exe with LGHT0094: The identifier 'Icon:<Product>Icon.exe' could not be found.

• nsis.include (and nsisWeb.include) now also accepts an array of paths — every entry is resolved relative to the build resources directory first, then the project directory, and all scripts are included in order.
• The build resources directory is now always registered via !addincludedir, so custom scripts can !include sibling files by name even when the main include is auto-discovered.
• The portable target now honors an explicitly set portable.include (string or array). It still does not auto-discover build/installer.nsh, so existing portable builds are unaffected.
• Both build/x86-unicode and build/x86-ansi user plugin directories are now registered (each when it exists) instead of only the one matching the unicode option, matching the documented behavior.
• Fixed the !ifmacrodef customInstallmode case mismatch in multiUserUi.nsh to match the documented customInstallMode macro name (NSIS macro-name matching is case-insensitive, so this is a consistency fix).

Optional Ed25519 signing of auto-update manifests (latest*.yml). When signing keys are configured (updateManifest.signingKey/signingKeyFile in config, or ELECTRON_BUILDER_UPDATE_SIGN_KEY/ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE env vars), each manifest is signed over its integrity-critical fields and the matching public keys are embedded into app-update.yml (both resolved from the same keys on the platform packager, so signing and embedding cannot disagree). electron-updater verifies the signature before downloading and refuses to update on tamper/missing-signature (fail-closed). Opt-in: when no public key is configured, verification is skipped with a one-time warning. New CLI: electron-builder create-update-key (prints the public key and its key id).

Key rotation without a flag day: an install trusts a list of public keys (updateManifestPublicKey is a string or an array; updateManifest.publicKey, signingKey and signingKeyFile accept arrays, a PEM value may hold several concatenated keys, and ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE accepts several paths joined with the OS path delimiter), and a manifest may carry several signatures (signatures: [{ keyId, signature }], one per signing key, next to the legacy signature of the first key). A manifest is accepted when any trusted key validates any of its signatures, so a release signed with [old, new] verifies on installs that trust either. AppUpdater.updateManifestPublicKey accepts a string or an array. A build-time warning flags an explicit publicKey list that contains none of the signing keys.

Gating of the Linux package-manager signature-bypass flags landed separately as AppUpdater.allowUnverifiedLinuxPackages (#9990).

electron-builder migrate-schema (static and JS/TS configs) now also rewrites the v26 shapes it previously left behind, which failed v27 schema validation on the next build:

• platform-level mac/mas/masDev/win/linux asarUnpack → <platform>.asar.unpack, merging the root ASAR options in because a platform-level asar replaces the root one in v27; root ASAR keys that have no effect under asar: false are removed
• toolsets.*: null entries are removed and the retired toolsets.appimage: "1.0.2" pin becomes "1.0.3"
• nativeRebuilder: "legacy", electronDownload.force, and v26 null ("unset") values on mac.type / provisioningProfile / binaries / signIgnore / singleArchFiles / x64ArchFiles are dropped instead of carried into keys that reject them; a hand-renamed electronGet still in the v26 shape is reshaped
• GitHub publish entries are migrated in every section (e.g. nsis.publish), a non-empty tagNamePrefix next to vPrefixedTagName is kept (it won in v26), and an empty tagNamePrefix — ignored by v26 — becomes "v" with a warning so existing tag names do not change
• win.signAndEditExecutable: false also maps to win.sign: false (it skipped signing in v26), and win.signtoolOptions / win.azureSignOptions under disabled signing are dropped with a warning instead of producing an invalid config
• snap options the snapcraft.core24 shape does not support are dropped with a warning

It warns about squirrelWindows.customSquirrelVendorDir (not mechanically migratable) and prints an advisory for mac/mas/masDev configs that rely on the tightened default entitlements. The build-time legacy-config guard now also names squirrelWindows.customSquirrelVendorDir and electronGet.force, and the USE_SYSTEM_WINE removal message points at toolsets.wine: "system".

BREAKING CHANGE: the promise returned by AppUpdater.downloadUpdate() (and UpdateCheckResult.downloadPromise when autoDownload is enabled) now resolves with { updateFile, packageFile? } instead of [updateFile] / [updateFile, packageFile]. The array shape depended on element order to tell the installer apart from the optional NSIS web-installer package; the new DownloadExecutorResult type (exported from electron-updater) names both files. UpdateDownloadedEvent additionally gains an optional packageFile field for web installers.

// Before (v6)
const files = await autoUpdater.downloadUpdate()
const installer = files[0]
const webInstallerPackage = files[1] // only for NSIS web installers

// After (v7)
const { updateFile, packageFile } = await autoUpdater.downloadUpdate()

The same applies to the result of checkForUpdates():

// Before (v6)
const result = await autoUpdater.checkForUpdates()
const [installer] = (await result?.downloadPromise) ?? []

// After (v7)
const result = await autoUpdater.checkForUpdates()
const download = await result?.downloadPromise
const installer = download?.updateFile

The underlying cache-consistency fix from #10098 already produced this object internally; this change stops converting it back to an array at the public API boundary.

Optional Ed25519 signing of auto-update manifests (latest*.yml). When signing keys are configured (updateManifest.signingKey/signingKeyFile in config, or ELECTRON_BUILDER_UPDATE_SIGN_KEY/ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE env vars), each manifest is signed over its integrity-critical fields and the matching public keys are embedded into app-update.yml (both resolved from the same keys on the platform packager, so signing and embedding cannot disagree). electron-updater verifies the signature before downloading and refuses to update on tamper/missing-signature (fail-closed). Opt-in: when no public key is configured, verification is skipped with a one-time warning. New CLI: electron-builder create-update-key (prints the public key and its key id).

Key rotation without a flag day: an install trusts a list of public keys (updateManifestPublicKey is a string or an array; updateManifest.publicKey, signingKey and signingKeyFile accept arrays, a PEM value may hold several concatenated keys, and ELECTRON_BUILDER_UPDATE_SIGN_KEY_FILE accepts several paths joined with the OS path delimiter), and a manifest may carry several signatures (signatures: [{ keyId, signature }], one per signing key, next to the legacy signature of the first key). A manifest is accepted when any trusted key validates any of its signatures, so a release signed with [old, new] verifies on installs that trust either. AppUpdater.updateManifestPublicKey accepts a string or an array. A build-time warning flags an explicit publicKey list that contains none of the signing keys.

Gating of the Linux package-manager signature-bypass flags landed separately as AppUpdater.allowUnverifiedLinuxPackages (#9990).

• DataSplitter only recognised CRLF. Some CDNs answer multipart/byteranges with bare LF line endings, so no part was ever split and the whole response accumulated in memory. Header lists now end at whichever of \r\n\r\n / \n\n comes first, and the <EOL>--boundary separator size follows the line ending the server actually uses.
• A header-list terminator split across two chunks was never found: only the new chunk was searched, the buffered bytes never were, so the parser locked onto the next part's header instead. Only the last few bytes of an unfinished header list are now carried over and searched together with the next chunk, instead of accumulating the whole list.
• The 10s watchdog armed when a batch response ends was never disarmed after that batch succeeded. With more than 1000 operations (several range requests) it failed the whole download whenever a later batch took longer than the grace period.

With generateUpdatesFilesForAllChannels enabled, the extra alpha/beta update files were only written when the channel was exactly alpha, beta, or latest. A per-arch feed configured as channel: "${channel}-${arch}" resolves to something like beta-arm64, which hit the default branch, so alpha-arm64.yml was never written and arm64 pre-release users stopped getting promoted. The base channel is now read off the front of the name and the suffix is reattached to the expanded channels, so beta-arm64 yields beta-arm64 and alpha-arm64, and latest-arm64 yields all three.

Breaking: a suffixed beta-*/latest-* channel now publishes 2–3 update files instead of 1, so a latest-x64 publish overwrites beta-x64.yml/alpha-x64.yml in the same bucket. Turn off generateUpdatesFilesForAllChannels if you relied on suffixed channels staying single-file.

feat(linux): support the "default" keyword in depends for the fpm targets (deb, rpm, pacman), mirroring the snap target's plugs/stagePackages/buildPackages convention. "default" expands in place to the target's default depends list, so extras can be appended without repeating the defaults — e.g. ["default", "http-parser"] restores http-parser on top of the defaults. The final list is deduplicated.

• The unconditional Signing <file>... log line is removed — the sign managers already log signing with certificate details right before executing, so unsigned builds no longer look like they are signing.
• The skip message now states the actual reason at info level (signing skipped reason=no code signing certificate configured) instead of a debug-level "no signing configuration found".
• A file signed by a custom win.sign hook is now logged as signed with custom `sign` hook instead of being misattributed to signtool.exe.
• MacPackager.sign reports the same type explicitly instead of a bare true/false ("skipped:unsupported" on non-mac hosts and pull-request CI guard, "skipped:disabled" for sign/identity: null, "skipped:no-certificate" when no identity is found, "signed:custom" for a custom mac.sign hook), and MacTargetHelper.handleNullIdentity returns "skipped:disabled" instead of false.
• Behavior change: WinPackager.signApp and MacPackager.signApp previously discarded the per-file results and returned true unconditionally, so the afterSign hook fired even for fully unsigned builds. signApp now reports the combined real result (a signed result wins) — for unsigned builds, afterSign is skipped and the standard skipping "afterSign" hook as no signing occurred, perhaps you intended "afterPack"? warning is logged, matching the documented gating in doSignAfterPack and the mas/mas-dev behavior (#10071). Builds that relied on afterSign firing without any signing should move that logic to afterPack.

When a GitHub or Bitbucket publish configuration omits owner/repo, electron-builder fills them in from the repository info (package.json repository, CI env vars, then .git/config) and writes the result into app-update.yml inside the packaged app, where it becomes the update feed for every installed copy. Until now nothing in the build output said which repository had been chosen - not even at DEBUG=electron-builder, which logged the pre-resolution owner=undefined project=undefined.

The build now logs the resolved provider/owner/repo (or slug for Bitbucket) once per build, together with the source the repository was detected from. A repository taken from the package.json repository field is deliberate configuration and is reported at info level; one picked up from CI environment variables or .git/config is reported at warn level. Nothing about what gets written to app-update.yml changes, and builds that already specify owner/repo explicitly are unaffected.

Two guards around Windows update signature verification:

• electron-updater: when app-update.yml exists but contains no publisherName, the updater used to skip signature verification (including custom verifyUpdateCodeSignature hooks) completely silently. It now logs a warning explaining that verification was skipped, how to fix it (sign the build so publisherName is derived automatically, or set win.publisherName explicitly), and that this fail-open behavior is deprecated: electron-builder v28 will treat a missing publisherName as a verification failure (fail-closed). The no-app-update.yml path (unpackaged/dev mode) stays silent.
• app-builder-lib: when publisherName is explicitly configured and the subject of the local code signing certificate is known, the build now fails with a clear error if none of the configured names match the certificate (same DN-subset/CN matching semantics as the updater's verifier; any one of multiple configured names matching passes, so certificate-rotation setups keep working). This catches signing with the wrong certificate at build time instead of at update time. The check is skipped whenever the actual signing certificate's subject is not genuinely known (custom sign hooks, Azure Trusted Signing, PKCS#11 without an extractable certificate, x509 files without a CN), and publisherName: null remains a pure opt-out.

• builder-util removePassword: redact single-letter/URI secret flags (security … -k <password>, osslsigncode -key <pkcs11-uri?pin-value=…>) and whitespace-containing secrets in debug logs, and make the /b … /c block-redaction regex ReDoS-safe.
• builder-util-runtime httpExecutor: fix the non-functional maxRedirects guard (the redirect counter was never advanced), so a redirect loop from a malicious feed/mirror no longer hangs the updater.
• electron-updater GitLabProvider: only forward the GitLab token to the channel-file request when its URL is same-origin as the API host, so an off-host/http:// direct_asset_url in the release JSON cannot exfiltrate the token.
• app-builder-lib: defense-in-depth hardening — validate executableName before interpolating it into the generated Flatpak launcher, contain custom-toolset extraction within the cache dir, and XML-escape MSI file-association ext/description.
• electron-builder migrate-schema: auto-remove the removed linux.syncDesktopName flag.

Before: packaging an app that declares zero production dependencies (e.g. everything is bundled by a JS bundler) from inside a monorepo skipped the app's own empty node_modules, climbed to the workspace root, and copied the entire hoisted workspace node_modules into app.asar.

After: an app with no production dependencies (neither in its package.json nor added via extraMetadata) bundles no node_modules at all — the collection step is skipped with an informational log message.

Two guards around Windows update signature verification:

• electron-updater: when app-update.yml exists but contains no publisherName, the updater used to skip signature verification (including custom verifyUpdateCodeSignature hooks) completely silently. It now logs a warning explaining that verification was skipped, how to fix it (sign the build so publisherName is derived automatically, or set win.publisherName explicitly), and that this fail-open behavior is deprecated: electron-builder v28 will treat a missing publisherName as a verification failure (fail-closed). The no-app-update.yml path (unpackaged/dev mode) stays silent.
• app-builder-lib: when publisherName is explicitly configured and the subject of the local code signing certificate is known, the build now fails with a clear error if none of the configured names match the certificate (same DN-subset/CN matching semantics as the updater's verifier; any one of multiple configured names matching passes, so certificate-rotation setups keep working). This catches signing with the wrong certificate at build time instead of at update time. The check is skipped whenever the actual signing certificate's subject is not genuinely known (custom sign hooks, Azure Trusted Signing, PKCS#11 without an extractable certificate, x509 files without a CN), and publisherName: null remains a pure opt-out.

• builder-util removePassword: redact single-letter/URI secret flags (security … -k <password>, osslsigncode -key <pkcs11-uri?pin-value=…>) and whitespace-containing secrets in debug logs, and make the /b … /c block-redaction regex ReDoS-safe.
• builder-util-runtime httpExecutor: fix the non-functional maxRedirects guard (the redirect counter was never advanced), so a redirect loop from a malicious feed/mirror no longer hangs the updater.
• electron-updater GitLabProvider: only forward the GitLab token to the channel-file request when its URL is same-origin as the API host, so an off-host/http:// direct_asset_url in the release JSON cannot exfiltrate the token.
• app-builder-lib: defense-in-depth hardening — validate executableName before interpolating it into the generated Flatpak launcher, contain custom-toolset extraction within the cache dir, and XML-escape MSI file-association ext/description.
• electron-builder migrate-schema: auto-remove the removed linux.syncDesktopName flag.

• macOS product and executable names are no longer normalized to NFD. The .app bundle, the helper bundles, and CFBundleName now all use the product name exactly as configured, which is required for Electron's helper-app lookup (${CFBundleName} Helper.app).
• macOS builds now require productName and executableName to be usable as a bundle name without any filename sanitization. A name that would otherwise be silently altered (for example one containing /, \, :, *, control characters, or trailing dots/spaces) now fails with a clear configuration error so you can choose a valid name.

BREAKING CHANGE: The default DMG volume filesystem changed from HFS+ to APFS. APFS is the modern macOS filesystem and produces smaller, faster-to-mount images on current macOS. If you must support pre-10.13 (High Sierra) macOS, which cannot mount APFS volumes, set dmg.filesystem: "HFS+" explicitly.

BREAKING CHANGE: The legacy top-level UpdateInfo.path / UpdateInfo.sha512 fields are now written to latest*.yml only when the declared electronUpdaterCompatibility semver range intersects electron-updater versions <2.16.0 (previously they were written unconditionally), mirroring how the Windows sha2 field is gated; the legacy latest-mac.json is likewise emitted only when the range intersects <2.0.0. The default electronUpdaterCompatibility is now >=2.16 (previously >=2.15), so none of the legacy fields are emitted by default. Both fields are now optional on the UpdateInfo type. Modern clients (electron-updater >=2.16) read the files[] array and are unaffected. If you still ship apps that embed electron-updater 1.x – 2.15, set electronUpdaterCompatibility to a range that includes them (e.g. >=1.0.0) so the legacy descriptor keeps being emitted.

electron-builder migrate-schema now prints an advisory when the config builds an nsis-web target, reminding you that AppUpdater.disableWebInstaller defaults to true as of v27 and that you must set autoUpdater.disableWebInstaller = false in your main process to keep downloading web installers. The advisory is informational only — it surfaces on the JSON/YAML and programmatic (JS/TS) paths and never rewrites the config (disableWebInstaller is an electron-updater runtime setting, not a build-config key).

NSIS installers now write a resources/package-type marker (nsis or nsis-web) at install time, mirroring the existing Linux package-type mechanism. electron-updater's NsisUpdater reads this marker and, for nsis-web installs, pre-seeds disableWebInstaller = false so web-installer auto-updates keep working without the app wiring the flag by hand.

This is a default only: an explicit autoUpdater.disableWebInstaller = … set by the app still wins, and a plain nsis marker leaves the secure ?? true default (and the v27 grace-period warning) untouched. The marker is written by the installer script — the only build artifact that differs between nsis and nsis-web (the app payload is byte-identical, since both targets share one app archive). Only go-forward installs carry the marker; existing deployments are unaffected.

Bitbucket Cloud is deprecating app passwords (https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens). The Bitbucket publisher now selects the auth scheme by whether a username is set: with a username it sends HTTP Basic auth (Bitbucket username + app password, or Atlassian account email + API token); without a username it sends the token as a repository/project/workspace access token via Authorization: Bearer. Previously a token was always sent as Basic auth using the repo owner as the username, so access tokens could not be used.

BREAKING CHANGE: AppUpdater.disableWebInstaller now defaults to true. NSIS web-installer packages are no longer loaded unless you opt in, because their payload is fetched from a manifest-supplied URL that may not undergo signature verification.

v27 ships a one-major-version grace period so existing deployments are not broken without warning:

• If you never set disableWebInstaller (the default) and a web-installer update is received, the updater logs a deprecation warning and still downloads it. In v28 this becomes an error and the download is blocked (ERR_UPDATER_WEB_INSTALLER_DISABLED).
• If you explicitly set disableWebInstaller = true, the download throws ERR_UPDATER_WEB_INSTALLER_DISABLED immediately.

If you intentionally publish and rely on an NSIS web installer, opt back in before v28 by setting autoUpdater.disableWebInstaller = false in your main process.

BREAKING CHANGE: The legacy top-level UpdateInfo.path / UpdateInfo.sha512 fields are now written to latest*.yml only when the declared electronUpdaterCompatibility semver range intersects electron-updater versions <2.16.0 (previously they were written unconditionally), mirroring how the Windows sha2 field is gated; the legacy latest-mac.json is likewise emitted only when the range intersects <2.0.0. The default electronUpdaterCompatibility is now >=2.16 (previously >=2.15), so none of the legacy fields are emitted by default. Both fields are now optional on the UpdateInfo type. Modern clients (electron-updater >=2.16) read the files[] array and are unaffected. If you still ship apps that embed electron-updater 1.x – 2.15, set electronUpdaterCompatibility to a range that includes them (e.g. >=1.0.0) so the legacy descriptor keeps being emitted.

BREAKING: quitAndInstall now takes a single destructured options object instead of positional booleans, so v27 migrators discover the new deferred-install flag and can never swap arguments silently. Defaults are unchanged; there is no backward-compat shim.

// Before (v26)
autoUpdater.quitAndInstall(true, false)

// After (v27)
autoUpdater.quitAndInstall({ isSilent: true, isForceRunAfter: false })

BREAKING: the autoInstallOnAppQuit boolean is replaced by an autoInstallEvent: "manual" | "onQuit" | "onNextLaunch" enum (default "onQuit", which preserves prior behavior). There is no compat alias — a single boolean cannot express the three states.

// Before (v26)
autoUpdater.autoInstallOnAppQuit = false

// After (v27)
autoUpdater.autoInstallEvent = "manual"

Installing an update while the app quits spawns a detached installer process; when the quit is caused by the OS session ending (shutdown/reboot/log off on Windows), the OS can kill that installer mid-install and leave the app uninstalled but not re-installed (#7807). Two mitigations, both implemented in BaseUpdater so NSIS, AppImage, deb, rpm and pacman targets all inherit them:

• Session-end guard (always on): when the OS session is ending, the on-quit install is skipped with a warning and the downloaded update stays cached for the next quit. Detection is best-effort: powerMonitor shutdown on macOS/Linux, BrowserWindow session-end on Windows (windowless apps cannot be covered on Windows).
• autoInstallEvent: "onNextLaunch" (opt-in; default is "onQuit"): any app quit persists the downloaded update as pending instead of spawning the installer. On the next launch the updater re-validates the cached installer against freshly fetched update info (checksum, code signature on Windows, and an installable-change version check — newer, or a downgrade when allowDowngrade is set — as a loop guard) and installs it silently, restarting the app. A single quit can be deferred via the new quitAndInstall({ waitUntilNextLaunch: true }) option.

The automatic install at startup is restricted to targets that install without an elevation prompt: NSIS (per-user installs) and AppImage only. deb/rpm/pacman always elevate via pkexec/sudo to install — an authentication dialog at app launch is not acceptable — so they keep the pending update and log why; per-machine NSIS installs (UAC) are skipped the same way. For those targets, call the new installPendingUpdateIfAvailable() explicitly at a moment the app controls.

autoInstallEvent: "onNextLaunch" is opt-in in v27 and is planned to become the DEFAULT in v28 to resolve this class of session-end corruption once and for all. macOS is unaffected: Squirrel.Mac natively stages downloaded updates and applies them on relaunch (there "onQuit" and "onNextLaunch" behave identically).

NSIS installers now write a resources/package-type marker (nsis or nsis-web) at install time, mirroring the existing Linux package-type mechanism. electron-updater's NsisUpdater reads this marker and, for nsis-web installs, pre-seeds disableWebInstaller = false so web-installer auto-updates keep working without the app wiring the flag by hand.

This is a default only: an explicit autoUpdater.disableWebInstaller = … set by the app still wins, and a plain nsis marker leaves the secure ?? true default (and the v27 grace-period warning) untouched. The marker is written by the installer script — the only build artifact that differs between nsis and nsis-web (the app payload is byte-identical, since both targets share one app archive). Only go-forward installs carry the marker; existing deployments are unaffected.

Adds AppUpdater.allowUnverifiedLinuxPackages. Because electron-builder does not sign Linux packages, this defaults to true, preserving the existing behavior: .deb/.rpm auto-updates install with the package manager's signature/GPG checks bypassed where a bypass flag exists (--allow-unauthenticated for the apt fallback, --allow-unsigned-rpm for zypper, --nogpgcheck for dnf/yum).

If you sign your Linux packages through your own pipeline and the target systems trust your keys, set autoUpdater.allowUnverifiedLinuxPackages = false. What this enforces depends on the package manager used on the target system:

• dpkg (the default for .deb): no effect — dpkg performs no signature verification (a warning is logged); enforcing .deb signatures requires a debsig-verify/debsigs policy on the target system.
• apt (.deb fallback): --allow-unauthenticated is omitted.
• zypper: enforced — unsigned/untrusted packages fail to install.
• dnf/yum: enforced via --setopt=localpkg_gpgcheck=1 (local package files are not GPG-checked by default).
• bare rpm (fallback): cannot be enforced via the CLI (a warning is logged) — rpm verifies signatures when present but by default does not fail the install on unsigned/untrusted packages; the rpm -Uvh ... --nodeps fallback command is unchanged (--nodeps is a dependency-resolution bypass, not a signature bypass).

The new allowUnverified parameter on DebUpdater.installWithCommandRunner / RpmUpdater.installWithCommandRunner is a trailing optional argument (default true), so existing callers remain source- and runtime-compatible.

• allowPrerelease=true with no explicit channel and a stable current version now selects the newest valid semver release in the Atom feed (skipping unrelated non-semver tags such as other packages in a monorepo) instead of blindly taking the first feed entry (#9894).
• When every published release is older than the installed version, the updater now reports "update not available" gracefully (and honors allowDowngrade) instead of throwing.
• allowPrerelease=false no longer throws ERR_UPDATER_NO_PUBLISHED_VERSIONS when the latest release tag (from /releases/latest) is absent from GitHub's truncated Atom feed; it proceeds with the resolved tag.
• Harden the release download path against path traversal: a tag containing ./.. path segments is rejected with ERR_UPDATER_INVALID_TAG.

The updater previously used a fuzzy heuristic (looking for +, /, Z, or = characters) to decide whether a manifest sha512 was hex- or base64-encoded. It now uses a strict check: a value that is exactly 128 hexadecimal characters is treated as legacy hex; anything else is decoded as base64, which is what electron-builder has emitted since 19.x (2017). The two forms cannot collide — base64-encoded sha512 is always 88 characters ending in == — and a wrong pick can only fail closed with a checksum mismatch.

Hex-encoded sha512 values (from pre-19.x manifests or hand-rolled manifests built from raw sha512sum output) remain accepted in v27 but are deprecated: support will be removed in v28. Emit base64 instead, e.g. sha512sum file.ext | cut -d' ' -f1 | xxd -r -p | base64 -w0.

SHA-256 (sha2) update checksums are unchanged here — they remain accepted in v27 under the existing v28-removal grace period.

• Remove the USE_SYSTEM_FPM environment flag — the last of the USE_SYSTEM_* toolset overrides. To use a non-bundled fpm, configure toolsets.fpm with a custom toolset pointing at the directory containing the fpm executable, e.g. { url: "file:///opt/homebrew/bin" }.
• A custom toolset is now honored before the platform fallback in getFpmPath() and getOsslSigncodeBundle(), so an explicit override is respected on every platform (previously it was silently ignored on Windows).
• On Windows with no custom toolset configured, getFpmPath() now throws InvalidConfigurationError instead of resolving a bare fpm from $PATH, closing a binary-hijack vector (getOsslSigncodeBundle() throws as defense-in-depth on the same path).

electron-builder migrate-schema previously printed manual steps for programmatic configs (.js/.cjs/.mjs/.ts). It now rewrites them in place via an AST-located text codemod that applies the same v26→v27 transforms as static configs while preserving comments, imports, functions, and formatting. Falls back to manual steps when typescript is not installed or the config cannot be statically reduced to a single object literal (dynamic function bodies, spreads, computed keys).

Node modules are now filtered by their package.json cpu/os constraints against the target arch/platform, so host-installed single-arch binaries are no longer copied into mismatched single-arch builds. For universal macOS builds, both slices are kept symmetric and any single-arch binary that can't be lipo-merged — including host binaries inside packages that declare no cpu/os (such as esbuild's bin/esbuild) — is automatically reported to @electron/universal via singleArchFiles (merged with mac.universal.singleArchFiles), with a warning listing them. This fixes builds aborting with Detected file "…" that's the same in both x64 and arm64 builds and not covered by the x64ArchFiles rule (#9865, #9399).

Also add he_IL to bundledLanguages so Hebrew strings actually reach the built installer (fixes a pre-existing bug where Hebrew was never included in the default multi-language set).

BREAKING CHANGE: Publishing no longer happens automatically based on CI environment, git tags, or npm lifecycle events. You must now explicitly request publishing using the --publish CLI flag (e.g., --publish always, --publish onTag) or by setting the publish option in your configuration.

This addresses security and usability concerns where unexpected auto-publishing could accidentally expose secrets or publish unfinished work.

• DataSplitter only recognised CRLF. Some CDNs answer multipart/byteranges with bare LF line endings, so no part was ever split and the whole response accumulated in memory. Header lists now end at whichever of \r\n\r\n / \n\n comes first, and the <EOL>--boundary separator size follows the line ending the server actually uses.
• A header-list terminator split across two chunks was never found: only the new chunk was searched, the buffered bytes never were, so the parser locked onto the next part's header instead. Only the last few bytes of an unfinished header list are now carried over and searched together with the next chunk, instead of accumulating the whole list.
• The 10s watchdog armed when a batch response ends was never disarmed after that batch succeeded. With more than 1000 operations (several range requests) it failed the whole download whenever a later batch took longer than the grace period.

downloadArtifact() was ignoring electron_builder_binaries_mirror and falling back to electron_mirror due to @electron/get behavior. This affected dmg-builder (macOS) and appimage-tools (Linux) downloads.

• Extract getBinariesMirrorUrl() to share mirror URL resolution
• Use the helper in both downloadArtifact() and getBinFromUrl()
• Ensure custom mirrors are respected for all binary downloads

Replace hardcoded service-specific hostname checks with sophisticated cross-origin redirect detection that matches industry standards from Python requests library and Apache HttpClient.

Key improvements:

• Case-insensitive hostname comparison for robust origin detection
• HTTP→HTTPS upgrade allowance on standard ports (80→443) for backward compatibility
• Proper default port handling that treats implicit and explicit default ports as equivalent
• Standards-compliant cross-origin detection following RFC specifications

Fixes GitHub issue #9207: GitHub release asset downloads failing with 403 Forbidden when redirected from api.github.com to release-assets.githubusercontent.com (Azure backend) or other cloud storage services that don't accept GitHub tokens.

The implementation now handles all cross-origin redirect scenarios while maintaining compatibility with legitimate same-origin redirects and industry-standard HTTP→HTTPS upgrades.

Replace hardcoded service-specific hostname checks with sophisticated cross-origin redirect detection that matches industry standards from Python requests library and Apache HttpClient.

Key improvements:

• Case-insensitive hostname comparison for robust origin detection
• HTTP→HTTPS upgrade allowance on standard ports (80→443) for backward compatibility
• Proper default port handling that treats implicit and explicit default ports as equivalent
• Standards-compliant cross-origin detection following RFC specifications

Fixes GitHub issue #9207: GitHub release asset downloads failing with 403 Forbidden when redirected from api.github.com to release-assets.githubusercontent.com (Azure backend) or other cloud storage services that don't accept GitHub tokens.

The implementation now handles all cross-origin redirect scenarios while maintaining compatibility with legitimate same-origin redirects and industry-standard HTTP→HTTPS upgrades.

For winOptions signing configuration, it has been moved to win.signtoolOptions in order to support azureOptions as a separate field and avoid bloating win configuration object For macOptions, notarize options has been deprecated in favor of env vars for quite some time. Env vars are much more secure

For winOptions signing configuration, it has been moved to win.signtoolOptions in order to support azureOptions as a separate field and avoid bloating win configuration object For macOptions, notarize options has been deprecated in favor of env vars for quite some time. Env vars are much more secure

Deprecate legacy (altool) notarization API.