Identify the app bundle

Everything you ship on macOS revolves around one artifact: the app bundle. Before you sign or package anything, you should know exactly what is inside it.

A .app is not a file. It’s a directory with a fixed structure that Finder presents as a single application. Look inside your built app:

find Notes.app/Contents -maxdepth 2 -print

You’ll see a predictable layout. Contents/MacOS holds the executable. Contents/Resources holds assets like images and localizations. Contents/Frameworks holds embedded libraries. And Contents/Info.plist holds the metadata that describes the app to the system.

Read that metadata with plutil:

plutil -p Notes.app/Contents/Info.plist

The value that matters most is CFBundleIdentifier, the bundle identifier. Mine is com.flaviocopes.Notes. This reverse-DNS string is your app’s durable identity. macOS keys preferences, privacy permissions, and Keychain access to it, and Apple’s distribution services track your app by it.

Pick it once and never change it. If you rename it later, macOS treats the app as a brand new one: users lose their granted permissions, and their saved preferences point at the old identity.

One more rule, and it will matter a lot in the signing module: once a bundle is signed, treat it as read-only. The signature seals the executable and every resource. Change one file and the seal breaks.

This is a classic failure. You sign the app, then “quickly fix” a typo in a resource file or swap the icon. Now codesign --verify fails and Gatekeeper refuses to launch the app on other Macs. The fix is always the same: rebuild, then re-sign the fresh bundle.