Skip to main content
Installing and testing on a real iPhone Level: Intermediate 12 min read

Deploying Cross-Platform Apps (Flutter/React Native) to TestFlight

A comprehensive guide to packaging, uploading, and distributing Flutter and React Native iOS applications to TestFlight testers using FlightDeck MCP.

Published: 2026-11-03 • Last Updated: 2026-11-03 • Author: Kip Lawrence
Key MCP Tools: build_upload_previewbuild_upload_startbuild_upload_statusbuild_add_to_beta_groupbeta_groups_listbuilds_list

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.

TEXT
┌─────────────────────────────────────────────────────────────────────────────┐
│               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

TEXT
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

TEXT
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 .ipa archive directly on your Mac, parses Payload/*.app/Info.plist, extracts CFBundleIdentifier, CFBundleShortVersionString, and CFBundleVersion, 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 ipa or npx 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:

YAML
# pubspec.yaml
version: 1.4.0+42 # 1.4.0 is CFBundleShortVersionString, 42 is CFBundleVersion

Run Flutter's native IPA compilation command:

BASH
# 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:

  1. Update version strings in ios/<ProjectName>/Info.plist or app.json: - CFBundleShortVersionString (e.g., 1.4.0) - CFBundleVersion (e.g., 42)
  2. Install CocoaPods dependencies: ``bash cd ios && pod install && cd .. ``
  3. 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:

  1. Validates that the file exists and has valid ZIP/IPA archive structure.
  2. Unpacks and inspects Payload/*.app/Info.plist.
  3. Verifies that CFBundleIdentifier matches the target App Store Connect application ID (appId).
  4. Verifies ITSAppUsesNonExemptEncryption to avoid downstream export compliance blocks.
  5. Returns a structured JSON summary confirming archive readiness.

Phase 3: Binary Upload Execution and Progress Tracking

When you instruct your assistant to upload:

  1. Your assistant calls build_upload_start(appId: "...", filePath: "/path/to/archive.ipa").
  2. FlightDeck Desktop displays an Approval Request in the native macOS window. You review the target App ID, file size, version numbers, and file path.
  3. Upon clicking Approve, FlightDeck contacts Apple’s asset delivery service, reserves upload chunks, and streams the binary directly to Apple over HTTPS.
  4. 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).

  1. The AI assistant polls builds_list(appId: "...") until the new build transitions from PROCESSING to VALID.
  2. The assistant inspects available beta groups using beta_groups_list(appId: "...").
  3. The assistant stages build_add_to_beta_group(appId: "...", betaGroupId: "...", buildId: "...").
  4. You approve the distribution in the FlightDeck Desktop Approval Center.
  5. Distribution occurs according to group type: - Internal Beta Groups: Testers receive immediate access without review as soon as the build reaches VALID status. - 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

  1. Protect Signing Identities: Never commit .p12 certificates, provisioning profiles, or distribution passwords to Git repositories.
  2. Never Paste .p8 Keys into Prompts: FlightDeck accesses your App Store Connect API key securely from the macOS Keychain. Never paste private keys into AI chat windows.
  3. Audit Native Plugins: Cross-platform npm packages and pub.dev packages can bundle arbitrary native iOS code. Regularly audit ios/Podfile.lock for unauthorized native dependencies.
  4. Enforce Human Approval: Always verify the target app and version numbers in the Desktop Approval Center before approving build_upload_start.

Official References


Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store