Overview: Packaging and Distributing macOS Apps to the App Store
Unlike iOS applications—which are always packaged as .ipa archives—macOS distribution involves multiple file formats and signing requirements depending on whether you distribute directly to users outside the App Store or submit to Apple's Mac App Store.
For the Mac App Store, Apple requires a signed installer package (.pkg) containing your sandboxed application bundle (.app), or an upload executed via Xcode Organizer. Direct directory bundles—such as raw .app folders or .xcarchive bundles—cannot be uploaded directly to App Store Connect ingestion APIs.
┌────────────────────────────────────────────────────────────────────────┐
│ LOCAL PACKAGING & SIGNING │
│ │
│ MyApp.app (Sandboxed) ──► Signed with "Apple Distribution" │
│ │ │
│ ▼ │
│ [ productbuild --component ] ──► Signed with "Mac Installer Distr" │
│ │ │
│ ▼ │
│ MyApp.pkg (Flat XAR Package) │
└───────────┬────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ FLIGHTDECK MCP WORKFLOW PIPELINE │
│ │
│ MyApp.pkg ──► [ build_upload_preview ] │
│ │ (In-process XAR parsing & SHA-256 hash) │
│ ▼ │
│ [ Approval Center Confirmation ] │
│ │ (Human-in-the-loop review) │
│ ▼ │
│ [ build_upload_start ] ──► Apple Ingestion Pipeline │
└────────────────────────────────────────────────────────────────────────┘
FlightDeck includes native support for inspecting and uploading macOS .pkg packages through its MCP tools (build_upload_preview and build_upload_start). This guide explains how to package and sandbox your macOS app correctly, how FlightDeck validates flat packages, and how to execute the upload using natural-language AI prompts.
1. Mac App Store Distribution Requirements
Before packaging a macOS application for App Store Connect, verify that your project complies with Apple's strict platform requirements:
1. Mandatory App Sandboxing
Every application submitted to the Mac App Store must have App Sandbox enabled. In your target's .entitlements file:
<key>com.apple.security.app-sandbox</key>
<true/>
Without this entitlement, Apple's automated binary ingestion system will immediately reject the package with error ITMS-90236: Missing App Sandbox.
2. Dual Cryptographic Signatures
A macOS package requires two separate certificates from your Apple Developer account:
- Application Binary Signature: The executable code inside
MyApp.appmust be signed with your Apple Distribution certificate (or legacy 3rd Party Mac Developer Application). - Installer Package Signature: The outer
.pkginstaller container must be signed with your Mac Installer Distribution certificate (or legacy 3rd Party Mac Developer Installer).
3. Build Versioning Constraints
CFBundleShortVersionString: The public marketing version (e.g.,1.2.0).CFBundleVersion: The internal build number (e.g.,12). Must be strictly higher than any previously uploaded build for that marketing version.
2. Mac App Store Submission vs Developer ID Notarization
Developers frequently confuse Mac App Store submission with direct distribution outside the App Store. They use different tooling, certificates, and validation pipelines:
| Feature | Mac App Store Submission | Developer ID Direct Distribution |
|---|---|---|
| Distribution Channel | Mac App Store | Direct download, DMG, website, or Sparkle updater |
| App Signature | Apple Distribution / 3rd Party Mac Developer App | Developer ID Application |
| Installer Signature | Mac Installer Distribution | Developer ID Installer |
| App Sandbox | Mandatory | Optional (Hardened Runtime required) |
Notarization (notarytool) |
Not used (Apple ingests, reviews, and signs via FairPlay) | Mandatory (must staple notarization ticket) |
| Upload Destination | App Store Connect (buildUploads API / FlightDeck) |
Apple Notary Service (xcrun notarytool) |
Do not attempt to notarize a Mac App Store build using xcrun notarytool. The notarization service only accepts binaries signed with Developer ID certificates and will reject packages signed with Mac App Store distribution certificates.
3. Creating the Signed .pkg Installer Package
To generate an uploadable .pkg from your compiled and sandboxed .app bundle, use Apple's productbuild utility:
Step 1: Sign Embedded Frameworks and the Inner Application Bundle
Code signing for macOS must proceed from the inside out: sign embedded dylibs, frameworks, and helper tools first, followed by the main application bundle:
# 1. Sign embedded frameworks and dynamic libraries
for framework in ./build/Release/MyApp.app/Contents/Frameworks/*.framework; do
codesign --force --options runtime --timestamp \
--sign "Apple Distribution: Acme Corporation (ABCDE12345)" \
"$framework"
done
# 2. Sign embedded helper tools or XPC services with their entitlements
# (Repeat for each binary in Contents/MacOS/ or Contents/XPCServices/)
# 3. Sign the main application bundle with sandboxing entitlements
codesign --force --options runtime --timestamp \
--sign "Apple Distribution: Acme Corporation (ABCDE12345)" \
--entitlements MyApp.entitlements \
./build/Release/MyApp.app
Verify the signature:
codesign -dvvv ./build/Release/MyApp.app
Step 2: Package and Sign the Installer Package
Use Apple's productbuild --component utility to wrap the .app inside a signed flat installer package destined for /Applications:
productbuild \
--component ./build/Release/MyApp.app /Applications \
--sign "Mac Installer Distribution: Acme Corporation (ABCDE12345)" \
./build/MyApp.pkg
Complex Multi-Component Packages: For simple standalone applications, productbuild --component is the standard Apple command. For multi-bundle installations requiring custom pre-install scripts or distribution XML definition files, developers synthesize a distribution file with productbuild --synthesize and compile with productbuild --distribution. For standard Mac App Store submissions, --component produces the required flat XAR package format.
Step 3: Verify the Package Signature
Verify that the package was signed with the correct installer certificate:
pkgutil --check-signature ./build/MyApp.pkg
Expected output:
Package "MyApp.pkg":
Status: signed by a developer certificate issued by Apple for Mac App Store submission
Certificate Chain:
1. Mac Installer Distribution: Acme Corporation (ABCDE12345)
2. Apple Worldwide Developer Relations Certification Authority
3. Apple Root CA
4. How FlightDeck Validates macOS Packages
FlightDeck's build_upload_preview tool performs comprehensive local validation on .pkg files before any data is sent over the network.
Pure In-Process XAR Inspection
A modern macOS .pkg file is an XAR archive (eXtensible ARchive with magic header 0x78617221). FlightDeck's ArtifactInspector inspects .pkg files using a pure in-process parser without shelling out to external command-line binaries:
- Magic Header & Table of Contents: Reads the XAR header, decompresses the XML Table of Contents (TOC), and enforces memory limits to protect against malicious zip-bomb payloads.
- Metadata Extraction: Extracts
CFBundleIdentifier,CFBundleShortVersionString,CFBundleVersion, and target platform (MAC_OS). - Cryptographic Checksums: Streams the package file to compute SHA-256 and MD5 checksums.
- App Store Connect Matching: Compares the extracted
CFBundleIdentifieragainst the selected application record in App Store Connect to prevent uploading the wrong binary.
Rejection of Raw Directory Bundles
If a developer accidentally attempts to upload a .app or .xcarchive directory bundle directly, FlightDeck detects the directory package and throws an informative error:
UnsupportedArtifactException: The .app directory bundle exists at ".../MyApp.app",
but .app directory bundles cannot be uploaded directly to App Store Connect.
A Mac App Store upload requires an appropriate packaged artifact (.pkg).
FlightDeck does not perform App Store distribution signing or packaging.
Please package and sign your application using Xcode or productbuild prior to upload.
Implementation Evidence & Verification Boundaries: FlightDeck's in-process .pkg parser and upload streaming pipeline are fully implemented and validated in the application repository. In testing environments without a live Apple Developer account or enrolled macOS app record, local preview inspection (build_upload_preview) is verified offline (Level 3 evidence), while live binary ingestion on Apple's Mac App Store servers (Level 4 evidence) requires production App Store Connect credentials.
5. Executing the Upload Workflow via AI Prompts
With your .pkg file prepared, you can orchestrate the preview and upload through natural-language prompts.
Step 1: Pre-Upload Inspection Prompt
Inspect the macOS installer package at ./build/MyApp.pkg for my Mac App Store app "Quest Desktop". Verify the bundle identifier, version, and build number before initiating an upload.
What the AI Assistant Does:
- Invokes FlightDeck's
build_upload_previewtool with the path to the.pkgand the target app ID. - Displays the verified package properties:
- File:
MyApp.pkg - Platform:
MAC_OS - Bundle ID:
com.mycompany.questdesktop - Version:
2.1.0(Build45) - SHA-256 Checksum:
7f83b...d29a - Status: Ready for upload.
Step 2: Upload Execution Prompt
Upload ./build/MyApp.pkg to App Store Connect for app "Quest Desktop". Explain what operations will be executed and stage the mutation for my approval.
What the AI Assistant & FlightDeck Do:
- Under FlightDeck's Approval Center ON mode, the AI assistant invokes
build_upload_start. - FlightDeck stages the mutation and displays a human-in-the-loop confirmation card on your desktop showing the target app, package name, file size, and calculated SHA-256 hash.
- Once you click Approve, FlightDeck: - Creates a
buildUploadscontainer on Apple's App Store Connect API (POST /v1/buildUploads). - Registers the.pkgasset (POST /v1/buildUploadFiles). - Streams the binary chunks directly to Apple's presigned storage endpoint. - Finalizes the asset registration with the verified MD5 checksum (PATCH /v1/buildUploadFiles/{id}). - Polls until Apple registers the upload and begins ingestion processing.
6. Verifying Ingestion Processing
Once the upload transfer completes, Apple's backend processes the package. You can verify processing status with a follow-up prompt:
Check the processing status of the newly uploaded build for "Quest Desktop". Let me know once the build state is VALID and ready for TestFlight or release.
What FlightDeck Does:
- Calls
builds_listorbuild_getto monitor Apple's server-side ingestion pipeline. - Reports when Apple transitions the build state from
PROCESSINGtoVALID.
For complete details on processing states and diagnostics, see Checking Build Processing State.
7. Troubleshooting Common macOS Upload Errors
1. ITMS-90236: Missing App Sandbox
- Cause: The application was built without the
com.apple.security.app-sandboxentitlement. - Fix: Add
<key>com.apple.security.app-sandbox</key><true/>to your macOS entitlements file, recompile, re-package withproductbuild, and re-upload.
2. ITMS-90242: Invalid Code Signing (Installer Package)
- Cause: The
.pkgpackage was signed with an application certificate instead of a Mac Installer certificate, or was created without a signature. - Fix: Ensure you pass
--sign "Mac Installer Distribution: ..."when runningproductbuild. Check withpkgutil --check-signature MyApp.pkg.
3. UnsupportedArtifactException in FlightDeck
- Cause: A path to
MyApp.apporMyApp.xcarchivewas provided instead ofMyApp.pkg. - Fix: Wrap the application bundle into a flat
.pkgusingproductbuildbefore previewing or uploading with FlightDeck.