Signing and notarizing a macOS Electron app without losing your mind

What Gatekeeper checks

Unsigned apps can trigger warnings because macOS cannot establish who built them or whether the bundle was modified. Developer ID Application signing identifies the app, while notarization submits the signed artifact to Apple for automated checks. Both steps matter for a smooth download experience.

Credentials and automation

The release workflow needs a Developer ID certificate, Apple Developer Team ID, Apple ID, and an app-specific password or issuer credentials. Keep these in CI secrets, import the certificate only for the job, sign the app and installer, then submit and staple the notarization ticket.

Most failures are mundane: the bundle identifier does not match, entitlements are incomplete, the certificate chain is missing, or the artifact changes after signing. Save the notarization log, verify the final artifact with codesign and spctl, and make the pipeline fail at the exact step that needs attention.

Practical follow-up

Run verification against the exact artifact users will download, not an intermediate app bundle. A successful signature on an app that is later repackaged or modified does not prove that the shipped DMG will pass Gatekeeper.

Keep a small release checklist beside the workflow: inspect entitlements, verify the signing identity, submit notarization, staple the ticket, and test on a clean machine. These checks turn an opaque release failure into a repeatable handoff.