Overview: Shipping Flutter iOS Apps to App Store Connect
Flutter enables developers to build high-performance mobile applications from a single Dart codebase. However, delivering an iOS release to Apple requires compiling an Apple distribution package (.ipa), validating code signatures, uploading the binary to App Store Connect, and distributing it to TestFlight or App Review.
Traditionally, completing this final mile meant launching Xcode, opening Runner.xcworkspace, archiving the project, navigating distribution wizards in the Xcode Organizer, and waiting through upload dialogs.
When working with an AI coding assistant (such as Cursor, Claude Code, Xcode with MCP, or Antigravity), you can keep your momentum entirely in your terminal and editor. You compile the signed .ipa with flutter build ipa, then command your AI assistant through FlightDeck to inspect the archive, stream it directly to Apple's ingestion servers, monitor processing, and assign the build to TestFlight.
Toolchain Division: Local Terminal vs. FlightDeck MCP
- Local Coding Environment: The Flutter SDK and
xcodebuildcompile your Dart and native iOS code, bundle plugin frameworks, and apply cryptographic code signatures using certificates stored in your macOS Keychain. FlightDeck does not run Flutter commands, compile Dart, or sign binaries. - FlightDeck MCP Capabilities: Once Flutter exports the
.ipaarchive, FlightDeck connects your AI assistant directly to App Store Connect over Apple's official REST API to inspect the binary locally, stream it over HTTPS, poll Apple backend ingestion, and manage TestFlight distribution under human approval.
Step 1: Flutter Prerequisites and Code Signing Configuration
Before compiling your release binary, ensure your Flutter project is properly configured for App Store distribution:
1. Environment Checklist
- Flutter SDK: Flutter 3.19 or later (
flutter doctorshould report zero issues). - Xcode Command Line Tools: Installed via
xcode-select --install. - Apple Developer Account: Active membership in the Apple Developer Program ($99/year).
2. Version and Build Counter in pubspec.yaml
Apple requires every uploaded binary to have both a marketing version (CFBundleShortVersionString) and a monotonically increasing build counter (CFBundleVersion). Flutter manages both in pubspec.yaml:
name: my_app
description: "A Flutter application built with AI."
version: 1.0.0+42 # 1.0.0 is the marketing version; 42 is the build counter
When building an update, increment the number after the + sign (e.g., 1.0.0+43) to avoid Apple's duplicate build number error (ITMS-90189).
3. Signing Setup in ios/Runner.xcodeproj
Open ios/Runner.xcworkspace in Xcode once to verify signing settings:
- Select the Runner project in the navigator, click the Runner target, and open Signing & Capabilities.
- Select your paid Team.
- Confirm Bundle Identifier matches your registered Apple App ID (e.g.,
com.yourcompany.myapp). - Ensure Automatically manage signing is checked for both Debug and Release.
4. Create ios/ExportOptions.plist
Flutter uses an export options property list to instruct xcodebuild how to package the archive for App Store distribution. Create ios/ExportOptions.plist in your project:
<?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>app-store-connect</string>
<key>signingStyle</key>
<string>automatic</string>
<key>stripSwiftSymbols</key>
<true/>
<key>uploadSymbols</key>
<true/>
</dict>
</plist>
Modern Xcode versions use app-store-connect as the export distribution method name. While xcodebuild accepts the legacy value app-store as an alias, app-store-connect is Apple's current standard.
Step 2: Compile the Signed IPA via Flutter CLI
Run the release build command from your terminal:
flutter build ipa --release --export-options-plist=ios/ExportOptions.plist
What Happens During Compilation:
- Flutter compiles Dart code into native AOT (ahead-of-time) ARM64 machine code.
- Integrates CocoaPods or Swift Package Manager plugin dependencies.
- Invokes
xcodebuild archiveto buildbuild/ios/archive/Runner.xcarchive. - Invokes
xcodebuild -exportArchiveto sign the app with your Apple Distribution Certificate and package the final.ipa.
Flutter places the output archive at:
build/ios/ipa/my_app.ipa
(If your project scheme is named Runner, the file will be build/ios/ipa/Runner.ipa).
Step 3: Inspect and Upload via Your AI Assistant
Once the .ipa is built, switch to your AI coding assistant (Cursor, Claude Code, Antigravity) connected to FlightDeck.
The Primary Flutter Upload Prompt:
I just compiled our Flutter iOS app to build/ios/ipa/my_app.ipa.
Using FlightDeck:
1. Locate our app record in App Store Connect.
2. Inspect the local IPA to confirm that its bundle ID, version string, and build number match our App Store Connect registration.
3. If inspection passes, stage an upload request for my approval in FlightDeck.
4. Once I authorize the upload in the FlightDeck Desktop Approval Center, monitor the upload stream until complete.
5. Report the final build upload status and Apple processing state.
What Happens Behind the Prompt
Your assistant executes the upload and validation pipeline without requiring you to handle low-level API operations:
Developer Prompt: "Inspect and upload build/ios/ipa/my_app.ipa"
│
▼
[1. Local Binary Inspection]
Assistant verifies bundle ID, architecture (arm64),
and version concordance before transmitting data
│
▼
[2. FlightDeck Desktop Approval Center]
Developer reviews package path, size, and version
│
▼
[3. Direct HTTPS Chunk Streaming]
FlightDeck streams binary directly to Apple's ingestion servers
│
▼
[4. Monitor Processing via FlightDeck]
Assistant tracks status until Apple marks build as VALID
1. In-Process Archive Inspection
Your assistant calls build_upload_preview to inspect the .ipa archive locally:
- Validates the ZIP container format and confirms
Payload/Runner.appexists. - Reads
Info.plistto confirmCFBundleIdentifiermatches your App Store Connect app record. - Verifies that
CFBundleShortVersionStringandCFBundleVersionmatch yourpubspec.yaml. - Confirms native 64-bit ARM architecture (
arm64).
If an issue is found (e.g., an unincremented build number or mismatched bundle identifier), FlightDeck halts locally before any network traffic is sent.
2. Desktop Approval Center Confirmation
Because uploading a new application binary is an impactful operation, FlightDeck presents a confirmation card in the native Approval Center on your Mac. You review the app name, bundle ID, target version, and package size, then click Approve.
3. Direct Streaming to Apple Ingestion Servers
Upon approval, FlightDeck initiates chunked multi-part streaming directly to Apple's presigned storage nodes over encrypted HTTPS. No third-party proxy or cloud intermediary touches your binary.
4. Tracking Apple Processing
Once streaming completes, Apple's ingestion servers run automated checks (symbol indexing, asset slicing, private API scanning). Ask your assistant to track progress:
Check the processing status of our latest Flutter build for [Your App Name]. Let me know when Apple marks it as VALID.
Your assistant queries builds_list until the build reports VALID.
Step 4: Distribute to TestFlight Internal Testers
Once the build reaches VALID, prompt your assistant to assign it to your internal QA team:
Our Flutter build is VALID. Please list our internal TestFlight groups for [Your App Name] and stage adding this build to our "Core Team" group so we can test on physical iPhones.
- Zero Review Wait: Internal test groups do not require Apple Beta App Review.
- Tester Access: Team members receive notifications in the TestFlight app on their devices and can install the update wire-free.
Common Flutter Build and Upload Failures
| Error | Root Cause | Resolution |
|---|---|---|
No profiles for 'com.example.app' were found |
Xcode cannot find a matching distribution provisioning profile. | Open ios/Runner.xcworkspace in Xcode, select your paid Team under Signing, and let Xcode generate the managed profile. |
Podfile out of date / Pods-Runner error |
Native CocoaPods dependencies out of sync. | Run cd ios && pod install --repo-update from your project terminal and rebuild. |
CFBundleVersion duplicate error (ITMS-90189) |
Apple already ingested a build with this build number. | Increment the build number in pubspec.yaml (e.g., 1.0.0+42 $\rightarrow$ 1.0.0+43) and run flutter build ipa again. |
Missing ITSAppUsesNonExemptEncryption |
Build reaches VALID, but distribution is paused for encryption declaration. |
Add <key>ITSAppUsesNonExemptEncryption</key><false/> to ios/Runner/Info.plist. (See Fixing Missing Encryption Key). |
Capability 'uploads' is disabled |
FlightDeck MCP capability filter has uploads disabled. | Open FlightDeck settings on your Mac and ensure the Uploads capability is toggled ON. |
Related Documentation and Guides
- Uploading iOS .ipa to App Store Connect Without Opening Xcode
- From Vibe Coding to App Store: The Complete Step-by-Step Publishing Guide
- Automating TestFlight Beta Distribution from Your AI Coding Assistant
- Fixing 'Missing ITSAppUsesNonExemptEncryption' in iOS Info.plist
- Flutter.dev: Preparing an iOS App for Release