Workflow: Ship/Release a macOS App

<required_reading> Read these reference files NOW:

1. references/security-code-signing.md
2. references/cli-workflow.md </required_reading>

<process> ## Step 1: Prepare for Release

Ensure the app is ready:

• All features complete and tested
• No debug code or test data
• Version and build numbers updated in Info.plist
• App icon and assets finalized

# Verify build succeeds
xcodebuild -project AppName.xcodeproj -scheme AppName -configuration Release build

Step 2: Choose Distribution Method

Step 3: Code Signing

For Direct Distribution (Developer ID):

# Archive
xcodebuild -project AppName.xcodeproj \\
  -scheme AppName \\
  -configuration Release \\
  -archivePath ./build/AppName.xcarchive \\
  archive

# Export with Developer ID
xcodebuild -exportArchive \\
  -archivePath ./build/AppName.xcarchive \\
  -exportPath ./build/export \\
  -exportOptionsPlist ExportOptions.plist

ExportOptions.plist for Developer ID:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>developer-id</string>
    <key>signingStyle</key>
    <string>automatic</string>
</dict>
</plist>

For App Store:

<key>method</key>
<string>app-store</string>

Step 4: Notarization (Direct Distribution)

Required for apps distributed outside the App Store:

# Submit for notarization
xcrun notarytool submit ./build/export/AppName.app.zip \\
  --apple-id "your@email.com" \\
  --team-id "TEAMID" \\
  --password "@keychain:AC_PASSWORD" \\
  --wait

# Staple the ticket
xcrun stapler staple ./build/export/AppName.app

Step 5: Create DMG (Direct Distribution)

# Create DMG
hdiutil create -volname "AppName" \\
  -srcfolder ./build/export/AppName.app \\
  -ov -format UDZO \\
  ./build/AppName.dmg

# Notarize the DMG too
xcrun notarytool submit ./build/AppName.dmg \\
  --apple-id "your@email.com" \\
  --team-id "TEAMID" \\
  --password "@keychain:AC_PASSWORD" \\
  --wait

xcrun stapler staple ./build/AppName.dmg

Step 6: App Store Submission

# Validate
xcrun altool --validate-app \\
  -f ./build/export/AppName.pkg \\
  -t macos \\
  --apiKey KEY_ID \\
  --apiIssuer ISSUER_ID

# Upload
xcrun altool --upload-app \\
  -f ./build/export/AppName.pkg \\
  -t macos \\
  --apiKey KEY_ID \\
  --apiIssuer ISSUER_ID

Then complete submission in App Store Connect.

Step 7: Verify Release

For direct distribution:

# Verify signature
codesign -dv --verbose=4 ./build/export/AppName.app

# Verify notarization
spctl -a -vv ./build/export/AppName.app

For App Store:

• Check App Store Connect for review status
• Test TestFlight build if applicable </process>

<checklist> Before shipping: - [ ] Version number incremented - [ ] Release notes written - [ ] Debug logging disabled or minimized - [ ] All entitlements correct and minimal - [ ] Privacy descriptions in Info.plist - [ ] App icon complete (all sizes) - [ ] Screenshots prepared (if App Store) - [ ] Tested on clean install </checklist>

<common_issues>