Skip to main content
Building, signing, and binary uploads Level: Developer 12 min read

From 'flutter build ipa' to App Store Connect: Automated Pipeline

A complete step-by-step guide to taking your Flutter release build from 'flutter build ipa' directly into App Store Connect and TestFlight using your AI coding assistant and FlightDeck MCP.

Published: 2026-10-31 • Last Updated: 2026-11-01 • Author: Kip Lawrence
Key MCP Tools: build_upload_previewbuild_upload_startbuild_upload_statusbuilds_listbeta_groups_listbuild_add_to_beta_group

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.

Important

Toolchain Division: Local Terminal vs. FlightDeck MCP

  • Local Coding Environment: The Flutter SDK and xcodebuild compile 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 .ipa archive, 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 doctor should 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:

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:

  1. Select the Runner project in the navigator, click the Runner target, and open Signing & Capabilities.
  2. Select your paid Team.
  3. Confirm Bundle Identifier matches your registered Apple App ID (e.g., com.yourcompany.myapp).
  4. 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
<?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>
Note

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:

BASH
flutter build ipa --release --export-options-plist=ios/ExportOptions.plist

What Happens During Compilation:

  1. Flutter compiles Dart code into native AOT (ahead-of-time) ARM64 machine code.
  2. Integrates CocoaPods or Swift Package Manager plugin dependencies.
  3. Invokes xcodebuild archive to build build/ios/archive/Runner.xcarchive.
  4. Invokes xcodebuild -exportArchive to sign the app with your Apple Distribution Certificate and package the final .ipa.

Flutter places the output archive at:

TEXT
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:

TEXT
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:

TEXT
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.app exists.
  • Reads Info.plist to confirm CFBundleIdentifier matches your App Store Connect app record.
  • Verifies that CFBundleShortVersionString and CFBundleVersion match your pubspec.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:

TEXT
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:

TEXT
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.

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