Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Packaging and Auto-update

Installers, Code Signing and Notarization

Choose installer formats for Windows, macOS and Linux, understand code signing and Apple notarization, configure electron-builder, and automate signed releases in CI.

A packaged app that you email to a friend works. A packaged app that you put on a website meets two problems: operating systems distrust unsigned software, and users expect a real installer. On Windows, an unsigned installer shows a blue SmartScreen warning that scares most people away. On macOS, an unsigned and un-notarized app is blocked by Gatekeeper, and on recent versions the user must go into system settings to override it.

This lesson covers the common installer formats, what signing and notarization actually do, how to configure the other popular packaging tool (electron-builder) and how to keep certificates safe in CI.

Choosing installer formats

Platform Common formats Notes
Windows NSIS .exe, MSI, MSIX, Squirrel NSIS is flexible and popular; MSI for enterprise deployment; MSIX for the Microsoft Store
macOS .dmg, .zip, .pkg DMG is the drag-to-Applications experience; ZIP is needed for some auto-update paths; PKG for the Mac App Store
Linux AppImage, .deb, .rpm, Snap, Flatpak AppImage runs anywhere; deb and rpm integrate with package managers

Pick based on your audience. Developers like archives and package managers; ordinary users want a double-clickable installer. Forge uses makers for each format (previous lesson), while electron-builder uses targets in one config block.

What code signing does

A code-signing certificate ties your app to a verified identity. The operating system checks two things on launch: that the signature is valid (the files were not altered after signing) and that the certificate chains up to an authority it trusts.

flowchart LR
  A["Packaged app"] --> B["Sign with private key"]
  B --> C["Signed app + certificate chain"]
  C --> D["User downloads and opens"]
  D --> E{"OS verifies signature"}
  E -- "valid and trusted" --> F["Runs normally"]
  E -- "unsigned or altered" --> G["Warning or block"]

Any change to a file after signing breaks the signature, so you must sign as the very last step.

  • Windows: you need a code-signing certificate from a certificate authority. Standard certificates build SmartScreen reputation slowly; EV certificates and cloud signing services (such as Azure Trusted Signing) are accepted sooner. Sign with signtool or let your packager call it.
  • macOS: you need an Apple Developer account (paid), a Developer ID Application certificate and, since macOS 10.15, notarization.
  • Linux: signing is not required for AppImage or deb installs, though repositories sign their metadata.

Notarization on macOS

Notarization means uploading the signed app to Apple's service, which scans it for malicious content and returns a ticket. You then staple the ticket to the app so it validates offline. Gatekeeper trusts notarized apps; without it users see "cannot be opened because the developer cannot be verified".

You also need entitlements for the hardened runtime. Electron needs a few to run JIT-compiled JavaScript:

XML
<!-- entitlements.plist -->
<plist version="1.0">
<dict>
  <key>com.apple.security.cs.allow-jit</key><true/>
  <key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/>
</dict>
</plist>

In Forge, signing and notarizing is part of packagerConfig:

JavaScript
packagerConfig: {
  osxSign: {
    identity: 'Developer ID Application: Example Ltd (ABCDE12345)',
    optionsForFile: () => ({ entitlements: './entitlements.plist' }),
  },
  osxNotarize: {
    appleId: process.env.APPLE_ID,
    appleIdPassword: process.env.APPLE_APP_SPECIFIC_PASSWORD,
    teamId: process.env.APPLE_TEAM_ID,
  },
},

Credentials come from environment variables, never from the repository.

electron-builder

electron-builder is the other widely used packager. It is configured by one block in package.json or electron-builder.yml:

YAML
appId: com.example.notesstudio
productName: Notes Studio
directories:
  output: dist
files:
  - "out/**"
  - "package.json"
win:
  target: nsis
  signtoolOptions:
    publisherName: Example Ltd
nsis:
  oneClick: false
  allowToChangeInstallationDirectory: true
mac:
  category: public.app-category.productivity
  hardenedRuntime: true
  entitlements: build/entitlements.plist
  notarize: true
  target: [dmg, zip]
linux:
  target: [AppImage, deb]
  category: Office
fileAssociations:
  - ext: note
    name: Notes Studio Document
    role: Editor
publish:
  provider: github

Run it with npx electron-builder --win --mac --linux on a machine that can build each target. Notice fileAssociations: this is where the .note extension from the drag and drop lesson gets registered with the operating system at install time. Protocol handlers are declared the same way through protocols.

Forge or electron-builder? Forge is the official tool and integrates with Electron's own packager and updater story; electron-builder offers more installer options and its own mature auto-update. Both are fine. Choose one per project, not both.

Signing in CI

Certificates are secrets. Rules that keep them safe:

  1. Store the certificate (base64) and its password in the CI provider's encrypted secrets, never in the repository.
  2. Decode the certificate to a temp file only inside the build job and delete it after.
  3. Sign only builds from your protected branches or tags, not from pull requests of forks.
  4. Rotate the certificate before expiry; mark the date in your calendar. An expired certificate does not invalidate existing signatures when a timestamp is used, so always timestamp your signatures.

A typical GitHub Actions fragment:

YAML
- name: Build and sign (macOS)
  if: matrix.os == 'macos-latest'
  env:
    APPLE_ID: ${{ secrets.APPLE_ID }}
    APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_PASSWORD }}
    APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
  run: npm run make

A pre-release gate

Signing problems are tedious to debug after a ten-minute build. A script that checks the inputs first saves time. This stand-in simulates the gate: it checks required environment variables per platform and refuses to build a release when something is missing.

Node.js A signing pre-flight check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Verifying a signed build

After building, verify from the outside, on a clean machine if possible:

  • Windows: signtool verify /pa /v setup.exe, and right-click the file, Properties, Digital Signatures.
  • macOS: codesign --verify --deep --strict --verbose=2 "Notes Studio.app", spctl --assess --type execute -vv "Notes Studio.app", and xcrun stapler validate "Notes Studio.app".
  • Linux: check the checksum you publish: sha256sum against the file users download.

Always publish SHA-256 checksums next to your downloads. Users and package managers can verify them, and the next example shows how the check works.

Node.js Publishing and verifying checksums

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must code signing be the last step of the build?

    The signature covers the exact bytes. Flipping fuses, adding files or editing the binary afterwards breaks it.
  2. 2. What does Apple's notarization add on top of signing?

    Notarization is an automated malware scan by Apple. The ticket is stapled to the app so it verifies even offline.
  3. 3. Where should signing certificates and passwords be stored for CI?

    Anything committed to the repository is exposed to everyone with access. CI secrets are injected only into the job that needs them.
  4. 4. Where do you declare that your installer registers the .note file extension?

    File associations are written into the installed app's metadata, so they are configured at packaging time.

Summary

  • Pick installer formats per platform: NSIS or MSI on Windows, DMG and ZIP on macOS, AppImage, deb or rpm on Linux.
  • Signing proves identity and integrity; macOS additionally requires notarization and hardened-runtime entitlements.
  • electron-builder and Forge both work; use one, and keep credentials in environment variables and CI secrets.
  • Timestamp signatures, verify the result on a clean machine, and publish SHA-256 checksums.
  • Check signing inputs in a pre-flight script before long builds.

Next: Auto-update Flow