macos-distribution

macOS App Distribution

End-to-end signing, notarization, stapling, and packaging for macOS apps distributed via Developer ID (outside the Mac App Store).

Scope

Trigger this skill for:

• Signing a .app bundle with a Developer ID Application certificate
• Notarizing builds with Apple's notary service via notarytool
• Stapling notarization tickets to apps, DMGs, or PKGs
• Building and signing distribution containers (DMG, ZIP)
• Generating Sparkle-compatible signed update artifacts
• Diagnosing spctl Gatekeeper rejections, stapler failures, or notary log errors
• Setting up keychain-stored notarization credentials

Out of scope: Mac App Store submission (different certificate, no notarization step) and iOS/tvOS/watchOS distribution.

Pipeline overview

Release build → sign nested code (inside-out) → sign outer .app
              → notarize → staple → verify
              → package DMG/ZIP → sign+notarize+staple container

Apple enforces inside-out signing: nested binaries must be signed before their containers. The bundled scripts/sign_and_notarize.sh automates the full traversal.

Prerequisites

Before signing, confirm:

1. Developer ID Application certificate is in the login keychain (security find-identity -v -p codesigning)
2. Team ID is known (10-character alphanumeric, visible at developer.apple.com → Membership)
3. Notarytool credentials are stored in keychain (one-time setup, see below)
4. App is built Release with ENABLE_HARDENED_RUNTIME=YES
5. Info.plist has CFBundleIdentifier, CFBundleVersion, CFBundleShortVersionString, and LSMinimumSystemVersion

Run scripts/preflight.sh /path/to/MyApp.app to validate all five.

One-time notarytool credentials

Apple ID with two-factor auth requires an app-specific password (appleid.apple.com → Sign-In and Security → App-Specific Passwords).

Store credentials in keychain once:

xcrun notarytool store-credentials NOTARYTOOL_PROFILE \
  --apple-id "[email protected]" \
  --team-id "ABCDE12345" \
  --password "xxxx-xxxx-xxxx-xxxx"

After this, all notarytool calls use --keychain-profile NOTARYTOOL_PROFILE and never see the password again. Use scripts/setup_credentials.sh for an interactive walkthrough.

Step 1 — Sign nested code, leaves first

Apple's signature is a Merkle tree: the outer signature only covers code that was already signed at the time. Sign in this order:

1. *.dylib and *.framework/Versions/*/Frameworks/* (deepest first)
2. Contents/Frameworks/*.framework
3. Contents/XPCServices/*.xpc
4. Contents/Helpers/* and Contents/Library/LoginItems/*
5. Any non-main executables in Contents/MacOS/
6. The outer .app (Step 2)

For each nested item:

codesign --force --options runtime --timestamp \
  --sign "Developer ID Application: <Name> (<TEAMID>)" \
  <path-to-nested-item>

Never use --deep. It applies the outer entitlements to nested code (wrong) and is officially deprecated. The provided sign_and_notarize.sh walks the bundle bottom-up automatically.

Step 2 — Sign the outer .app

After all nested code is signed:

codesign --force --options runtime --timestamp \
  --entitlements assets/entitlements.plist.template \
  --sign "Developer ID Application: <Name> (<TEAMID>)" \
  Build/Release/MyApp.app

--options runtime enables hardened runtime — without it notarization rejects.

Step 3 — Notarize

Notarytool requires a ZIP, DMG, or PKG (it does not accept loose .app):

ditto -c -k --keepParent MyApp.app MyApp.zip
xcrun notarytool submit MyApp.zip \
  --keychain-profile NOTARYTOOL_PROFILE --wait

--wait blocks until Apple responds (typically 30 s – 2 min). On Invalid status, fetch the diagnostic log:

xcrun notarytool log <submission-id> --keychain-profile NOTARYTOOL_PROFILE

Common causes are listed in references/troubleshooting.md.

Step 4 — Staple

Embed the notarization ticket so Gatekeeper can validate offline:

xcrun stapler staple MyApp.app

If stapler fails with "cannot find the ticket," wait 1–2 minutes for Apple's CDN to propagate, then retry.

Step 5 — Verify

Run all four checks (also bundled in scripts/verify_signed.sh):

codesign -dv --verbose=4 MyApp.app           # signature metadata
codesign --verify --strict MyApp.app          # signature validity
spctl -a -vvv -t exec MyApp.app               # Gatekeeper acceptance
stapler validate MyApp.app                    # ticket embedded

Expected output: all four succeed with no errors. spctl should print source=Notarized Developer ID.

Packaging containers

DMG (recommended)

Apple requires the container itself to be notarized when distributed. The bundled script handles this:

scripts/create_dmg.sh MyApp.app MyApp-1.0.dmg

Steps performed:

1. Build the DMG via hdiutil create -srcfolder ... -format UDZO
2. Sign the DMG with the same Developer ID
3. Submit DMG to notarytool and wait
4. Staple the ticket to the DMG

The signed+stapled DMG can be distributed as-is.

ZIP (Sparkle-compatible)

ZIP archives cannot be stapled — staple the app first, then zip:

xcrun stapler staple MyApp.app
ditto -c -k --keepParent MyApp.app MyApp-1.0.zip

The stapled ticket inside the app travels with the ZIP.

Sparkle update integration

For apps using Sparkle 2.x for auto-updates:

• Generate EdDSA keys once with Sparkle's generate_keys tool (stored in keychain)
• Embed the public key in Info.plist as SUPublicEDKey
• Sign each release ZIP with sign_update MyApp-1.0.zip → produces an ed25519 signature for the appcast XML

Sparkle's embedded XPC services (org.sparkle-project.*) must themselves be signed and notarized as part of Step 1. See references/sparkle.md for appcast format and XPC entitlement requirements.

Common pitfalls

Symptom	Likely cause	Fix
Notary log: "hardened runtime not enabled"	Missing --options runtime or built without ENABLE_HARDENED_RUNTIME	Re-sign with --options runtime
Notary log: "binary uses an SDK older than ..."	Built with old Xcode	Build with current Xcode
spctl rejects after notarization	App not stapled, or modified after stapling	Staple, do not modify after
Stapler: "cannot find the ticket"	CDN propagation delay	Wait 1–2 min, retry
codesign rejects nested framework	Already had ad-hoc signature from build	Strip with codesign --remove-signature, re-sign
Notary log: "missing secure timestamp"	--timestamp flag omitted	Re-sign with --timestamp

For detailed diagnosis see references/troubleshooting.md.

Resources

Scripts (scripts/)

• preflight.sh — Validate prerequisites before signing
• setup_credentials.sh — Interactive notarytool store-credentials walkthrough
• sign_and_notarize.sh — End-to-end inside-out signing + notarize + staple for an .app bundle
• create_dmg.sh — Build, sign, notarize, staple a DMG container
• verify_signed.sh — Run the four-check verification suite

References (load as needed)

• references/entitlements.md — Hardened runtime exception entitlements (JIT, library validation, debugger, etc.)
• references/troubleshooting.md — Notary log error catalog and recovery procedures
• references/sparkle.md — Sparkle 2.x EdDSA appcast signing and XPC entitlements

Assets

• assets/entitlements.plist.template — Minimal hardened runtime entitlements starting point