iOS App Store Submit

iOS App Store Build & Submit

End-to-end playbook for taking a Flutter/iOS app from "code is done" to "submitted for App Store review," written for headless/agent-driven Mac environments (no interactive Xcode GUI session, no GUI keychain prompts available). Validated end-to-end on a real submission (2026-08-05) that hit — and worked around — every pitfall documented below.

This skill is project-agnostic. Never hardcode bundle IDs, App Store Connect App IDs, Team IDs, or certificate names from a prior run — always derive them from the current project (see Step 0).

When NOT to use this

• Pure UI/feature work with no build/signing/submission component — just do the work directly.
• If the user has an interactive Xcode session open and wants to do signing themselves — offer to guide them through Xcode's GUI instead of fighting headless keychain limitations for no reason.

Step 0 — Discover the project

Before anything else, gather facts from the current project (don't ask the user for things you can read yourself):

# Bundle ID, team ID, current device family
grep -n "PRODUCT_BUNDLE_IDENTIFIER\|DEVELOPMENT_TEAM\|TARGETED_DEVICE_FAMILY" ios/Runner.xcodeproj/project.pbxproj | sort -u

# App version / build number
grep "^version:" pubspec.yaml   # Flutter: X.Y.Z+N

# Is asc CLI already installed and authenticated?
which asc && asc auth status

# Is this app already registered in App Store Connect?
asc apps list --output table

If asc isn't installed or there's no cached auth, walk the user through generating an App Store Connect API key (they must do this themselves — only the account holder/Admin can):

1. https://appstoreconnect.apple.com/access/integrations/api → generate key → App Manager role (least privilege that still covers everything this skill needs) → download the .p8 immediately (one-time download).
2. Get the file to you as a file (Drive link, etc.), never ask them to paste the raw key text in chat. Save it under ~/.asc/keys/ with chmod 600.
3. Register it:

   asc auth login --name "<project>" --key-id "<KEY_ID>" --issuer-id "<ISSUER_ID>" \
     --private-key "~/.asc/keys/AuthKey_<KEY_ID>.p8" --network --bypass-keychain

   --bypass-keychain is required in headless sessions — plain asc auth login fails with -25308 User interaction is not allowed because macOS Keychain wants a GUI unlock prompt that doesn't exist here.

Step 1 — iOS Simulator does not work for ML/vision-heavy apps on Apple Silicon

If the app uses google_mlkit_* (or similar plugins shipping arm64-simulator-incomplete binaries), the app cannot even install on any iOS Simulator on an Apple Silicon Mac ("Failed to find matching arch for input file"). Don't waste time debugging this — confirm real-device testing is the only option for that Mac, and check flutter devices for a wirelessly-paired iPhone/iPad before assuming none is available.

For screenshots specifically: if simulators are unusable, don't fabricate screens. Ask the user to capture the real screens on their device, or use xcrun devicectl to install/launch things yourself if the device is paired (see Step 6).

Step 2 — Code signing (the actual hard part)

2a. The core headless-Mac problem

The login keychain requires interactive unlock in most agent/headless sessions. Any operation that touches it — asc auth login without --bypass-keychain, security import into login.keychain, or even codesign using an existing identity that's already in login.keychain — can fail with -25308 User interaction is not allowed or errSecInternalComponent. This is true even for identities that work fine when the same Mac is used interactively (e.g., via a prior Xcode session).

Fix: use a dedicated, non-interactive keychain for the whole session, exactly like a CI runner would:

KC_PASS="build-$(date +%s | tail -c 6)"
security create-keychain -p "$KC_PASS" build.keychain
security unlock-keychain -p "$KC_PASS" build.keychain
security set-keychain-settings -lut 21600 build.keychain
security list-keychains -d user -s build.keychain login.keychain

Keep $KC_PASS around (write it to a gitignored file) — you'll need it again for security set-key-partition-list.

2b. Generate certificates without ever touching a keychain interactively

asc certificates create --generate-csr creates the private key and CSR as plain files — no keychain interaction at all — then submits the CSR to Apple:

asc certificates list --output table   # check what already exists first
asc certificates create --certificate-type IOS_DISTRIBUTION --generate-csr \
  --key-out ./signing/dist.key --csr-out ./signing/dist.csr \
  --common-name "<App> Distribution" --email "<contact-email>"
# For a real-device dev/profile build later, also:
# asc certificates create --certificate-type IOS_DEVELOPMENT --generate-csr ...

Fetch/create the matching provisioning profile:

asc signing fetch --bundle-id "<bundle.id>" --profile-type IOS_APP_STORE \
  --certificate-type IOS_DISTRIBUTION --create-missing --output ./signing
# For device installs: --profile-type IOS_APP_DEVELOPMENT --device "<ASC device ID>"
# (asc devices list to find/confirm the device is already registered)

2c. Import into build.keychain — OpenSSL 3.x needs -legacy

openssl x509 -inform DER -in ./signing/<serial>.cer -out ./signing/dist.pem
openssl pkcs12 -export -legacy -inkey ./signing/dist.key -in ./signing/dist.pem \
  -out ./signing/dist.p12 -passout pass:temp

Without -legacy, OpenSSL 3.x's default PKCS12 encryption makes macOS security import fail with "MAC verification failed during PKCS12 import (wrong password?)" — the password is fine, it's an algorithm-compatibility issue.

security import ./signing/dist.p12 -k build.keychain -P temp -T /usr/bin/codesign -T /usr/bin/security
security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KC_PASS" build.keychain
security find-identity -v -p codesigning build.keychain   # confirm it shows up

Install the provisioning profile at the standard location:

UUID=$(security cms -D -i ./signing/<profile>.mobileprovision 2>/dev/null | plutil -extract UUID xml1 -o - - | sed -n 's/.*<string>\(.*\)<\/string>.*/\1/p')
cp ./signing/<profile>.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/"$UUID.mobileprovision"

2d. Scope manual signing to the app target ONLY — never pass signing flags globally

If you pass CODE_SIGN_STYLE=Manual etc. as global xcodebuild command-line overrides, every CocoaPods/SPM framework/library target in the build breaks with errors like "X does not support provisioning profiles, but provisioning profile Y has been manually specified." — because those overrides apply to every target in the workspace, including libraries that must never be signed with a profile.

Instead, edit ios/Runner.xcodeproj/project.pbxproj and add exactly these three keys only inside the Runner (app) target's Release/Profile XCBuildConfiguration blocks (there are usually two sets of Debug/Release/Profile blocks in this file — a project-level one and a target-level one; the target-level one is the one that also has PRODUCT_BUNDLE_IDENTIFIER in the same block):

CODE_SIGN_STYLE = Manual;
CODE_SIGN_IDENTITY = "<exact string from `security find-identity -v -p codesigning build.keychain`>";
PROVISIONING_PROFILE_SPECIFIER = "<profile name>";

Before editing: project.pbxproj indentation is tabs, and the depth is easy to miscount by eye. Verify exact whitespace first:

python3 -c "
with open('ios/Runner.xcodeproj/project.pbxproj') as f:
    lines = f.readlines()
for i in range(START, END): print(repr(lines[i]))
"

then construct the Edit's old_string from that exact output — don't hand-type indentation.

Also, use the exact identity string from security find-identity, not a generic prefix like "iPhone Developer" — if both a Development and Distribution identity (or an old login-keychain identity and a new build-keychain one) are visible in the combined search list, a generic prefix can non-deterministically match the wrong one, producing "Provisioning profile X doesn't include signing certificate Y".

Tell codesign which keychain to use for the archive step:

asc xcode archive --workspace ios/Runner.xcworkspace --scheme Runner --configuration Release \
  --archive-path .asc/artifacts/Runner.xcarchive \
  --xcodebuild-flag="OTHER_CODE_SIGN_FLAGS=--keychain build.keychain"

Step 3 — Archive → Export → Validate → Upload

asc xcode export-options generate --archive-path .asc/artifacts/Runner.xcarchive \
  --signing-style manual --team-id "<TEAM_ID>" --output-path .asc/artifacts/ExportOptions.plist

If this fails with "manual export options require provisioning profile mappings", don't fight it — write the plist by hand, it's a small, well-known format:

<?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>teamID</key><string>TEAM_ID</string>
  <key>signingStyle</key><string>manual</string>
  <key>provisioningProfiles</key><dict><key>BUNDLE_ID</key><string>PROFILE_NAME</string></dict>
  <key>signingCertificate</key><string>iPhone Distribution</string>
  <key>uploadSymbols</key><true/>
</dict></plist>

asc xcode export --archive-path .asc/artifacts/Runner.xcarchive \
  --ipa-path .asc/artifacts/Runner.ipa --export-options .asc/artifacts/ExportOptions.plist

asc xcode validate wraps altool, which needs its own separate credential file (not the asc auth store):

mkdir -p ~/.appstoreconnect/private_keys
cp ~/.asc/keys/AuthKey_<KEY_ID>.p8 ~/.appstoreconnect/private_keys/
asc xcode validate --ipa .asc/artifacts/Runner.ipa --api-key "<KEY_ID>" --api-issuer "<ISSUER_ID>"

Upload and attach to a version:

asc publish appstore --app "<APP_ID>" --ipa .asc/artifacts/Runner.ipa --version "<X.Y>" --wait

If the upload fails, the CLI often only surfaces a bare error code. Get the real reason directly from the API:

TOKEN=$(asc auth token --confirm 2>/dev/null)
curl -s "https://api.appstoreconnect.apple.com/v1/buildUploads/<UPLOAD_ID>" \
  -H "Authorization: Bearer $TOKEN" | jq '.data.attributes.state'

A common real failure: missing a legacy Info.plist usage-description key alongside a newer granular one — e.g., NSCalendarsFullAccessUsageDescription present but plain NSCalendarsUsageDescription missing (error 90683). Check every usage-description key the app declares has both the classic and any newer granular variant Apple currently expects.

Bump the build number for every re-upload. After editing pubspec.yaml's +N, run flutter build ios --config-only --release to regenerate ios/Flutter/Generated.xcconfig before re-archiving — a plain flutter pub get does not refresh it.