Building and Signing a Desktop Application for macOS

Building and Signing a Desktop Application for macOS

Situation: the app is built, but on modern macOS versions (14+) Gatekeeper blocks it from launching. Users report: "cannot be opened because Apple cannot check it for malicious software." The root cause is the lack of code signing and notarization. Without them, Gatekeeper blocks the launch, and bypassing it through "System Settings" requires non-standard actions that most users won't perform.

It can be fixed in 3–4 days if the chain is set up correctly: Developer ID certificate → entitlements → code signing → notarization → stapling. We do this turnkey for Electron, Qt, SwiftUI, and other frameworks. With over 5 years of experience, we've delivered more than 50 releases for macOS — not one was blocked. Apple Notarization Guide

Entry cost: you need an Apple Developer Program subscription ($99/year) to obtain a Developer ID Application certificate. Notarization itself is free for developers.

Why Code Signing Is Critical

Code signing is a digital signature that guarantees the application's integrity. macOS checks it on every launch. Without it, Gatekeeper blocks the app, forcing the user to manually authorize it via "System Settings" or Terminal. For enterprise environments this is unacceptable: MDM policies prohibit running unsigned apps. Notarization adds Apple's verification for malicious code. Both are mandatory for distribution outside the Mac App Store.

How We Sign and Notarize macOS Apps

The process includes 2 mandatory stages: Code Signing and Notarization. First, obtain a Developer ID Application certificate (requires Apple Developer Account). Then configure the build with the correct entitlements. Below is a minimal config for Electron.

// electron-builder.yml mac: target: - target: dmg - target: zip icon: build/icon.icns category: public.app-category.productivity hardenedRuntime: true gatekeeperAssess: false entitlements: build/entitlements.mac.plist entitlementsInherit: build/entitlements.mac.plist identity: "Developer ID Application: Company Name (TEAM_ID)" 

<!-- build/entitlements.mac.plist --> <?xml version="1.0" encoding="UTF-8"?> <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/> <key>com.apple.security.cs.allow-dyld-environment-variables</key><true/> <key>com.apple.security.network.client</key><true/> </dict> </plist> 

What Entitlements Are Needed for Electron Apps?

Electron requires 4 keys: allow-jit (for V8), allow-unsigned-executable-memory (for JIT compilation), allow-dyld-environment-variables (for Node.js), and network.client (for HTTP requests). Without them the app will crash on start or fail to make network requests. Compare this with entitlements for native SwiftUI apps: there you typically only need com.apple.security.app-sandbox and com.apple.security.files.user-selected.read-write.

Notarization and Stapling

After code signing we submit the .dmg for notarization via notarytool. Apple scans the binaries for viruses and malicious code. The result is a notarization ticket, which is attached to the file using the stapler command.

# Using notarytool (Xcode 13+) xcrun notarytool submit AppName.dmg \ --apple-id "[email protected]" \ --password "@keychain:AC_PASSWORD" \ --team-id "TEAM_ID" \ --wait # Stapling (embedding the notarization ticket into the file) xcrun stapler staple AppName.dmg 

Notarytool works 3x faster than the old altool and has better support since it's actively developed by Apple.

Step-by-Step Code Signing Configuration in CI/CD

1. Obtain a Developer ID Application certificate from the Apple Developer Portal (type Developer ID Application, not Development).
2. Export the certificate as .p12 and store it in CI secrets (e.g., GitHub Secrets).
3. Configure electron-builder or equivalent with the required entitlements (see above).
4. Add a step to import the certificate into the CI pipeline.
5. Set up a notarization stage with notarytool and stapling.
6. Test the build both locally and in CI.

GitHub Actions for macOS

- uses: actions/checkout@v3 - name: Import Certificate run: | echo "$MACOS_CERTIFICATE" | base64 --decode > certificate.p12 security import certificate.p12 -P "$MACOS_CERTIFICATE_PWD" \ -A -t cert -f pkcs12 -k ~/Library/Keychains/login.keychain - name: Build and Sign run: npm run build:mac env: APPLE_ID: ${{ secrets.APPLE_ID }} APPLE_ID_PASS: ${{ secrets.APPLE_ID_PASS }} APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }} CSC_LINK: ${{ secrets.MACOS_CERTIFICATE }} CSC_KEY_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PWD }} 

Universal Binary (Intel + Apple Silicon)

A universal binary is a build containing both architectures (x86_64 and arm64). It runs natively on M1/M2/M3 without Rosetta 2. This is mandatory for the App Store and many enterprise environments. Performance savings: without a universal binary you lose up to 30% on Apple Silicon.

# electron-builder automatically creates a universal binary npx electron-builder --mac --universal 

What's Included in Our Turnkey Configuration

Additionally: setting up auto-update (Sparkle, Electron auto-updater), white-label signing, Apple Developer Enterprise Program support.

Typical Pitfalls

• Using an Apple Development certificate instead of Developer ID — only works for debugging.
• Missing hardenedRuntime: true — notarization will fail.
• Wrong entitlements for Electron — crash on launch.
• Skipping stapling — users see a warning if offline.
• Forgetting the universal binary — performance loss on Apple Silicon.
• Developer ID Application certificate is invalid if you chose the wrong type (must be Developer ID, not Development).
• Notarization fails if hardenedRuntime is not enabled.
• App crashes on start — check entitlements: for Electron, allow-jit and allow-unsigned-executable-memory are mandatory.
• Stapling fails if the file is corrupted — run stapler immediately after notarytool.

Based on our experience, we recommend testing notarization on every release. Even an Electron version upgrade can break entitlements.

Timelines and Guarantee

Basic setup takes 3–4 working days. We guarantee that the app will pass notarization and run on macOS 10.14 and later. Contact us to configure signing in 3–4 days and avoid Gatekeeper blocks. Get a consultation for your project — we'll help you avoid typical mistakes and save time.