Overview: Cross-Platform Compilation Meets Apple Distribution
Cross-platform frameworks like Flutter and React Native enable developers to share substantial codebases across iOS and Android. However, when it comes to packaging and releasing software for real iPhones, Apple makes zero architectural concessions for non-native frameworks.
At the operating system level, Apple’s App Store Connect ingestion pipeline does not recognize Dart code, JavaScript bundles, or React component hierarchies. Apple ingests one standard binary artifact: a compiled Mach-O executable bundled within a valid iOS application archive (.ipa), signed with an Apple-issued distribution certificate and sealed with an embedded provisioning profile.
┌─────────────────────────────────────────────────────────────────────────────┐
│ CROSS-PLATFORM TESTFLIGHT DEPLOYMENT PIPELINE │
├─────────────────────────────────────────────────────────────────────────────┤
│ 1. CROSS-PLATFORM SOURCE 2. NATIVE PACKAGING 3. FLIGHTDECK MCP │
│ • Flutter (lib/main.dart) • flutter build ipa • build_upload_preview │
│ • React Native (App.tsx) • xcodebuild -export • build_upload_start │
│ • Dependencies / Pods • Codesign & Profile • build_upload_status │
│ • Output: Runner.ipa • build_add_to_beta_group│
└─────────────────────────────────────────────────────────────────────────────┘
Once your cross-platform build command emits a valid .ipa file, FlightDeck’s Model Context Protocol (MCP) server enables your AI coding assistant to preflight, validate, upload, monitor, and distribute the build to TestFlight beta groups directly from your editor.
This guide explains how to compile Flutter and React Native applications for TestFlight, how FlightDeck automates post-compilation distribution, and how to troubleshoot common cross-platform upload pitfalls.
Primary Cross-Platform TestFlight Invocations
Use these conversational prompts with your AI assistant in Cursor, Claude Code, Windsurf, or Roo Code to manage cross-platform TestFlight releases:
Preflight Binary Inspection Prompt
Inspect the compiled iOS archive at build/ios/ipa/Runner.ipa before uploading. Verify that its bundle identifier matches our App Store Connect app, verify the version and build numbers, and confirm that the cryptographic signature is valid.
End-to-End Upload and Beta Distribution Prompt
Upload our latest compiled iOS archive at build/ios/ipa/Runner.ipa to App Store Connect. Track the upload progress, wait for Apple cloud processing to reach VALID status, and then ask for my approval to attach the build to the "Internal QA" TestFlight beta group.
What FlightDeck Can and Cannot Do
To maintain a reliable development workflow, cross-platform engineers must understand the exact operational boundary between framework CLI tools and FlightDeck MCP:
What FlightDeck Can Do
- Preflight Binary Inspection (
build_upload_preview): Reads the.ipaarchive directly on your Mac, parsesPayload/*.app/Info.plist, extractsCFBundleIdentifier,CFBundleShortVersionString, andCFBundleVersion, checks package file size, and verifies alignment with App Store Connect requirements before transmitting bytes. - Direct Asset Streaming (
build_upload_start): Initiates a direct, multi-part chunked upload from your Mac to Apple’s presigned asset delivery endpoints without passing through any intermediate proxy. - Upload Progress Tracking (
build_upload_status): Monitors byte progress, chunk transfer rates, and terminal completion states. - Automated Beta Distribution (
build_add_to_beta_group): Associates processed builds with internal or external TestFlight beta groups once Apple finishes ingestion. - Safety Governance: Enforces human-in-the-loop confirmation in the native FlightDeck Desktop Approval Center before dispatching mutating operations.
What FlightDeck Cannot Do
- Compile Dart or JavaScript: FlightDeck does not compile Dart into AOT ARM64 machine code, nor does it bundle JavaScript/Hermes bytecode. Compilation must be performed by
flutter build ipaornpx react-native build-ios. - Install Framework Toolchains: FlightDeck does not install Flutter, Xcode, CocoaPods, Node.js, or Ruby environments.
- Resolve Framework Native Conflicts: FlightDeck cannot resolve native CocoaPods version locks, missing iOS deployment target declarations, or Swift bridging header compilation errors.
- Bypass Beta App Review: External TestFlight groups require Apple Beta App Review approval on the first build of a new version train. FlightDeck cannot skip Apple review requirements.
Step-by-Step Cross-Platform Deployment Workflow
Phase 1: Compile the Production iOS Archive
Before interacting with FlightDeck MCP, generate a clean, signed production .ipa archive using your framework's native build tools.
Option A: Flutter Workflow
Ensure your pubspec.yaml reflects the intended marketing version and monotonic build number:
# pubspec.yaml
version: 1.4.0+42 # 1.4.0 is CFBundleShortVersionString, 42 is CFBundleVersion
Run Flutter's native IPA compilation command:
# Clean previous build artifacts
flutter clean
flutter pub get
cd ios && pod install && cd ..
# Compile and export signed production archive
flutter build ipa --release --export-options-plist=ios/ExportOptions.plist
Flutter places the compiled archive in build/ios/ipa/*.ipa.
Option B: React Native / Expo Workflow
For bare React Native or Expo Prebuild applications:
- Update version strings in
ios/<ProjectName>/Info.plistorapp.json: -CFBundleShortVersionString(e.g.,1.4.0) -CFBundleVersion(e.g.,42) - Install CocoaPods dependencies: ``
bash cd ios && pod install && cd ..`` - Archive and export using
xcodebuild: ```bash xcodebuild -workspace ios/YourApp.xcworkspace \ -scheme YourApp \ -configuration Release \ -archivePath build/YourApp.xcarchive \ -destination 'generic/platform=iOS' \ archive
xcodebuild -exportArchive \ -archivePath build/YourApp.xcarchive \ -exportOptionsPlist ios/ExportOptions.plist \ -exportPath build/ios/ipa ```
Phase 2: Preflight Inspection via FlightDeck MCP
Once the .ipa file exists on disk, prompt your AI assistant to run build_upload_preview.
The tool executes read-only inspection:
- Validates that the file exists and has valid ZIP/IPA archive structure.
- Unpacks and inspects
Payload/*.app/Info.plist. - Verifies that
CFBundleIdentifiermatches the target App Store Connect application ID (appId). - Verifies
ITSAppUsesNonExemptEncryptionto avoid downstream export compliance blocks. - Returns a structured JSON summary confirming archive readiness.
Phase 3: Binary Upload Execution and Progress Tracking
When you instruct your assistant to upload:
- Your assistant calls
build_upload_start(appId: "...", filePath: "/path/to/archive.ipa"). - FlightDeck Desktop displays an Approval Request in the native macOS window. You review the target App ID, file size, version numbers, and file path.
- Upon clicking Approve, FlightDeck contacts Apple’s asset delivery service, reserves upload chunks, and streams the binary directly to Apple over HTTPS.
- Your assistant polls
build_upload_status(buildUploadId: "...")to observe byte progress until Apple acknowledges full receipt.
Phase 4: Apple Cloud Processing & Beta Group Assignment
After upload completes, Apple’s servers process the binary. This phase involves automated binary analysis (checking private API usage, Swift runtime dependencies, asset catalogs, and encryption declarations).
- The AI assistant polls
builds_list(appId: "...")until the new build transitions fromPROCESSINGtoVALID. - The assistant inspects available beta groups using
beta_groups_list(appId: "..."). - The assistant stages
build_add_to_beta_group(appId: "...", betaGroupId: "...", buildId: "..."). - You approve the distribution in the FlightDeck Desktop Approval Center.
- Distribution occurs according to group type: - Internal Beta Groups: Testers receive immediate access without review as soon as the build reaches
VALIDstatus. - External Beta Groups: The first build in a new version train (CFBundleShortVersionString) requires passing Apple's Beta App Review before external invitations activate. Subsequent builds within the same version train generally distribute without repeating full review.
Cross-Platform Troubleshooting & Common Failure Modes
| Symptom / Error Code | Root Cause | Remediation |
|---|---|---|
ITMS-90034: Missing or invalid signature |
Framework build used development profile instead of App Store distribution certificate | Verify ExportOptions.plist specifies method: "app-store-connect" and matches your Team ID. |
ITMS-90189: Redundant Binary Upload |
CFBundleVersion has already been uploaded for this CFBundleShortVersionString |
Increment the build number (e.g. from 42 to 43) in pubspec.yaml or Info.plist and recompile. |
ITMS-90683: Missing Purpose String |
A cross-platform plugin (camera, location, contacts) linked native APIs without Info.plist description | Add required NSCameraUsageDescription or equivalent permission keys to ios/Runner/Info.plist. |
Build stuck in PROCESSING |
Heavy framework dSYMs or initial symbol processing delay | Allow 10–30 minutes. Builds cannot be expedited or canceled while in PROCESSING. |
| Missing Export Compliance prompt | ITSAppUsesNonExemptEncryption omitted from cross-platform Info.plist |
Set <key>ITSAppUsesNonExemptEncryption</key><false/> in Info.plist to enable automated distribution. |
Security Considerations
- Protect Signing Identities: Never commit
.p12certificates, provisioning profiles, or distribution passwords to Git repositories. - Never Paste
.p8Keys into Prompts: FlightDeck accesses your App Store Connect API key securely from the macOS Keychain. Never paste private keys into AI chat windows. - Audit Native Plugins: Cross-platform npm packages and pub.dev packages can bundle arbitrary native iOS code. Regularly audit
ios/Podfile.lockfor unauthorized native dependencies. - Enforce Human Approval: Always verify the target app and version numbers in the Desktop Approval Center before approving
build_upload_start.
Official References
- Flutter: Build and release an iOS app
- React Native: Publishing to App Store
- Apple Developer Documentation: TestFlight Overview
- App Store Connect API: Uploading App Assets
Related Developer Guides
- Flutter Build IPA to App Store Connect — Deep dive into Flutter CLI compilation arguments.
- React Native and Expo IPA Upload Guide — React Native packaging and EAS CLI integration.
- From Vibe Coding to App Store Guide — The foundational iOS deployment roadmap.
- Automating TestFlight Beta Distribution with AI — Managing multi-group TestFlight automation.