/native

Shipping a Mac App — Distribution, Signing, Notarization, Updates

Production reference for taking a macOS app from build to a user's Dock: channel decision, code-signing chain, hardened runtime, notarization flow, packaging, self-updating (Sparkle), and Mac App Store submission. Exact command flags live in reference/macos-xcrun-cli.md — this file owns the decision and flow narrative; do not duplicate flag tables here.

Scope: release-time decisions and pipeline shape. Entitlement selection (sandbox) is reference/sandbox-entitlements.md. XPC/helper-tool lifecycle is reference/xpc-helpers.md.

1. App Store vs. Developer ID — Decision Matrix

Both as separate targets is common: one target with app-sandbox = true + Mac App Distribution signing for the Store, one target with hardened runtime + Developer ID signing for direct download, sharing the same source and differing only in entitlements/scheme. Decide this at DETECT, not after the sandbox entitlement set is already locked in — retrofitting sandbox onto a Developer-ID-first app is a real rework cost (see reference/sandbox-entitlements.md § 9 for what breaks).

2. Code Signing Chain

• Provisioning profiles are generally not required for Developer ID direct distribution (Developer ID signing does not consume a profile the way iOS ad hoc/App Store builds historically did). Mac App Store builds use an App Store provisioning profile the same way iOS does, managed automatically by Xcode when "Automatically manage signing" is on.
• Certificate discovery/import for CI: reference/macos-xcrun-cli.md § 5 (security keychain commands).

3. Hardened Runtime

Hardened Runtime is a separate system from App Sandbox — restated in full at reference/sandbox-entitlements.md § 9; the short version: Sandbox governs what resources the app can touch, Hardened Runtime governs what code can execute inside the app's process. Notarization requires Hardened Runtime; it does not require Sandbox.

Enable via codesign --options runtime (or the Xcode "Hardened Runtime" capability, which sets the same build flag). By default this blocks: loading unsigned dylibs/frameworks, JIT'ing executable memory, DYLD environment-variable injection, and debugger attachment from arbitrary processes.

3.1 Exception Entitlements

Each exception weakens the hardened-runtime guarantee it belongs to — request only the ones the app's actual architecture needs (a plugin host needs disable-library-validation; it does not also need allow-jit unless it separately runs a script engine).

4. Deep-Signing Order

codesign must sign from the inside out: embedded frameworks and helper/XPC bundles before the outer .app, because the outer signature's seal covers the already-signed inner components' checksums.

1. Sign every embedded .framework / .dylib          (Frameworks/)
2. Sign every embedded XPC service                    (Contents/XPCServices/*.xpc)
3. Sign every embedded helper tool / login item .app   (Contents/Library/LoginItems/, .../Helpers/)
4. Sign the outer .app bundle last                     (with --entitlements for the outer app)

• codesign --deep will attempt this walk automatically, but it applies one flat signing pass with one entitlements file to everything — it cannot give the outer app one set of entitlements and an XPC service a different, narrower set. Any nontrivial app (embedded XPC service, differently-scoped helper) needs manual per-component signing in the order above; --deep is acceptable only for the trivial case of "no embedded components need distinct entitlements."
• Exact codesign flags (-s, --options runtime, --entitlements, -dv --verbose=4) → reference/macos-xcrun-cli.md § 2.

5. Notarization Flow

xcodebuild archive/export (or manual codesign chain, § 4)
        │
        ▼
zip or .dmg/.pkg the signed artifact
        │
        ▼
xcrun notarytool submit <artifact> --keychain-profile <profile> --wait
        │
        ├─ Accepted ──▶ xcrun stapler staple <artifact>
        │                        │
        │                        ▼
        │               xcrun spctl -a -vvv <artifact>   (verify Gatekeeper acceptance)
        │
        └─ Invalid ───▶ xcrun notarytool log <submission-id>   (diagnose, § 5.1)

• Exact notarytool/stapler/spctl flags and the store-credentials keychain-profile setup → reference/macos-xcrun-cli.md § 5.
• Staple the artifact you actually distribute (.dmg/.pkg), not just the inner .app — Gatekeeper checks the outer container's staple on first launch from that container; if you staple only the .app before zipping into a .dmg, the staple still travels with the .app and is checked when the user drags it out, but stapling the .dmg itself additionally lets Gatekeeper validate offline before the user even opens it.
• Notarization requires Hardened Runtime (§ 3) and a Developer ID (or Mac App Distribution, though the Store path skips notarytool entirely — App Review is the gate there) signature; unsigned or ad-hoc-signed artifacts are rejected outright.

5.1 Ticket/Log Troubleshooting

6. Packaging

• pkgbuild --component App.app --install-location /Applications ComponentApp.pkg builds a single-component package; productbuild --distribution dist.xml --package-path . Final.pkg composes multiple .pkg components (e.g. main app + privileged helper installer) plus a distribution XML controlling install-location choices and welcome/license panes.
• create-dmg (third-party, common in CI) wraps hdiutil with background image, icon positions, and Applications-folder symlink placement — evaluate as a build-script dependency, not a standard Apple tool.
• Exact hdiutil/pkgbuild/productbuild/productsign invocations → reference/macos-xcrun-cli.md § 6.

7. Sparkle 2.x Self-Updating (Developer ID only)

Sparkle is the de facto standard for Developer-ID-distributed Mac apps that need in-app update checking (the App Store path has its own built-in updater and must not ship Sparkle).

• Sparkle's own update-downloading and unpacking path is signature-verified against the embedded EdDSA public key before install — a compromised appcast host without the private key cannot push a malicious update, but a compromised build machine holding the private key can. Treat the EdDSA private key like a code-signing key.
• Update UI conventions: Sparkle's default UI follows Mac HIG (a small "Update Available" panel with release notes, Install/Skip/Remind-Me-Later) — customize the delegate only for real product needs, not cosmetic drift from the platform-standard flow.

7.1 Minimal Setup

<!-- Info.plist -->
<key>SUFeedURL</key>
<string>https://example.com/updates/appcast.xml</string>
<key>SUPublicEDKey</key>
<string>base64-ed25519-public-key-from-generate_keys</string>
<key>SUEnableAutomaticChecks</key>
<true/>

# One-time key generation (Sparkle's bundled tool)
./bin/generate_keys
# Per-release: sign the update archive, paste the output into the appcast entry
./bin/sign_update App-1.2.0.zip

<!-- appcast.xml — one <item> per release -->
<item>
  <title>Version 1.2.0</title>
  <sparkle:version>120</sparkle:version>
  <sparkle:shortVersionString>1.2.0</sparkle:shortVersionString>
  <sparkle:minimumSystemVersion>13.0</sparkle:minimumSystemVersion>
  <enclosure url="https://example.com/updates/App-1.2.0.zip"
             sparkle:edSignature="base64-signature-from-sign_update"
             length="12345678"
             type="application/octet-stream" />
</item>

• Sandboxed hosts must embed Sparkle's Autoupdate.app, Downloader.xpc, and Installer.xpc helper targets alongside the main app and sign each per the deep-signing order in § 4 — omitting the XPC targets is the most common "Sparkle works unsandboxed but silently fails once I add App Sandbox" report.

8. Mac App Store Submission Specifics

• Upload via Xcode Organizer, xcodebuild -exportArchive with the App Store export method, or notarytool-adjacent App Store Connect API tooling (Store submissions do not go through notarytool — App Review is the gate).
• TestFlight for macOS is available the same as iOS — internal/external testers, build expiration, matching entitlement/sandbox constraints as the eventual Store build (a TestFlight build that isn't sandboxed will not later pass Store review unmodified).
• Phased release: Store updates can roll out over 7 days to a growing percentage of existing users (opt-in per release in App Store Connect) — use for high-risk updates; pair with crash-rate monitoring during the rollout window.
• In-app purchase (if used) must go through StoreKit/Apple IAP — this is the primary constraint that pushes apps with existing payment infrastructure toward Developer ID instead (§ 1).
• App Sandbox is non-negotiable for this channel — if reference/sandbox-entitlements.md § 9's "sandbox-incompatible feature" list intersects the app's core functionality, Developer ID is the only viable channel, not a preference.

9. Common Distribution Mistakes

10. Release Checklist

• Distribution channel decided (App Store / Developer ID / both) — locked before entitlement scaffolding, not retrofitted
• Hardened Runtime enabled (codesign --options runtime), with only the exception entitlements (§ 3.1) the app actually needs
• com.apple.security.get-task-allow absent from the release entitlements file
• App Sandbox entitlements least-privilege audited (reference/sandbox-entitlements.md)
• Deep-signing order followed inside-out: frameworks → XPC services → helper tools → outer .app (§ 4)
• (Developer ID) notarytool submit --wait accepted, stapler staple applied to the distributed artifact (.dmg/.pkg), spctl -a -vvv confirms Gatekeeper acceptance
• (Developer ID) DMG or PKG packaged and tested on a clean machine (no prior dev-cert trust)
• (Developer ID, self-updating) Sparkle appcast published, EdDSA-signed, SUFeedURL reachable, sandboxed XPC services included if the app is sandboxed
• (App Store) TestFlight build validated with production-matching entitlements before submission
• (App Store) Phased release configured for high-risk updates
• Release artifact handed to Launch (NATIVE_MACOS_TO_LAUNCH_HANDOFF — reference/macos-handoffs.md) with distribution channel, notarization status, and appcast coordination noted

Sources

• Notarizing macOS software before distribution | Apple Developer Documentation (accessed 2026-07)
• Hardened Runtime | Apple Developer Documentation
• Configuring the hardened runtime | Apple Developer Documentation
• NOTARYTOOL(1) man page (accessed 2026-07)
• Customizing the notarization workflow | Apple Developer Documentation
• Sparkle project documentation — https://sparkle-project.org/documentation/ (EdDSA signing, appcast format, sandboxed XPC services; verify against the Sparkle 2.x release notes for the version pinned in the project)
• Distributing your app for beta testing and releases (TestFlight for macOS) | Apple Developer Documentation
• Cross-reference: reference/macos-xcrun-cli.md (exact codesign/notarytool/pkgbuild/productbuild command flags + CI recipe), reference/sandbox-entitlements.md (entitlement catalog + hardened-runtime-vs-sandbox distinction), reference/xpc-helpers.md (helper-tool lifecycle referenced by Sparkle's XPC services)