name: ios-app-store-submit description: Build, sign, and submit a Flutter/iOS app to the App Store Connect — covers Xcode archive/export, code signing (including headless-Mac keychain workarounds), the asc CLI for App Store Connect metadata automation, screenshot handoff, and final review submission. Use when asked to build and upload an iOS app, set up App Store code signing, fix a rejected/failed App Store Connect upload, automate App Store Connect metadata, or submit an app for App Store review. Triggers: "빌드해서 제출", "App Store 제출", "archive and upload", "TestFlight에 올려줘", "asc CLI로 메타데이터".

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.

Step 4 — Screenshots

Delegate to the app-store-screenshots skill for the actual editor. Two things this skill adds on top of that:

• Don't trust a remembered screenshot size. Whatever display-size guidance you have (6.9", 6.7", whatever) may be stale. If a real upload rejects a screenshot for wrong dimensions, that error is ground truth — fix the editor's export config to match it immediately, don't argue with it.
• Don't fabricate screens. If the simulator can't run the app (Step 1) and a claimed feature has no real screen backing it (e.g., a headline promises something the UI doesn't actually show yet), stop and either add the missing UI for real or renegotiate the shot list with the user — never approximate.

Step 5 — App Store Connect metadata (what asc can and can't do)

Can automate (public API):

Cannot automate — needs the user in a browser:

• App Privacy (data-use declarations) — not in the public API at all. asc web privacy needs an interactive Apple ID browser session; don't attempt it headlessly. Draft the recommended answers for the user, then have them fill it in and explicitly click Publish — saving without publishing still blocks submission with "You must have published answers to your app's data usages" at the final review submit step, and this failure mode isn't visible in asc validate beforehand (it only shows as a non-blocking "info" note there).

Territory/pricing availability has a real API quirk: asc pricing availability create --territory X can fail with an error naming a completely unrelated territory code (changes on every retry) — this isn't user error, it's because App Store Connect's POST /v2/appAvailabilities requires the entire territory catalog (~175 entries) in the initial creation call, not just the ones you care about. Work around it directly:

TOKEN=$(asc auth token --confirm 2>/dev/null)
curl -s "https://api.appstoreconnect.apple.com/v1/territories?limit=200" -H "Authorization: Bearer $TOKEN" \
  | jq -r '.data[].id' > /tmp/all_territories.txt
python3 - <<'EOF'
import json
territories = [l.strip() for l in open('/tmp/all_territories.txt') if l.strip()]
WANT_AVAILABLE = {"KOR"}  # <-- set desired territory codes here
data, included = [], []
for t in territories:
    lid = f"${{ta_{t}}}"   # literal "${...}" local-id format, required by the API
    data.append({"type": "territoryAvailabilities", "id": lid})
    included.append({"type": "territoryAvailabilities", "id": lid,
        "attributes": {"available": t in WANT_AVAILABLE},
        "relationships": {"territory": {"data": {"type": "territories", "id": t}}}})
body = {"data": {"type": "appAvailabilities",
    "attributes": {"availableInNewTerritories": False},
    "relationships": {"app": {"data": {"type": "apps", "id": "APP_ID"}},
                       "territoryAvailabilities": {"data": data}}},
    "included": included}
json.dump(body, open('/tmp/avail_body.json', 'w'))
EOF
curl -s -X POST "https://api.appstoreconnect.apple.com/v2/appAvailabilities" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d @/tmp/avail_body.json

Step 6 — Submit

asc validate --app "<APP_ID>" --version "<X.Y>" --platform IOS   # iterate to 0 blocking errors
asc review submit --app "<APP_ID>" --version "<X.Y>" --build "<BUILD_ID>" --confirm

If that wrapper errors with "does not contain target version" despite the item genuinely being attached (asc review items-list --submission <ID> shows it READY_FOR_REVIEW), drop to the lower-level command — it's more reliable:

asc review submissions-submit --id "<SUBMISSION_ID>" --confirm

Confirm with asc review status --app "<APP_ID>" — look for reviewState: WAITING_FOR_REVIEW and blockerCount: 0.

Step 7 (bonus) — Get a real, standalone-launchable build onto the user's device

Users often expect their personal iPhone to run a normal (non-Xcode-tethered) build once you've done all this work. A plain Debug build always needs Xcode/the Dart VM attached to launch — that's expected, not a bug, and no amount of signing fixes it. The fix is running Profile or Release mode instead:

flutter devices   # confirm a wirelessly-paired device
flutter build ios --profile   # or --release; needs its own dev-signing setup per Step 2 if the
                               # Release config is already pointed at an App Store profile
                               # (App Store profiles cannot sideload to an arbitrary device)

If flutter build/flutter install fails with the same keychain issues as Step 2, repeat the Step 2 signing setup with an IOS_APP_DEVELOPMENT certificate/profile instead of IOS_DISTRIBUTION, applied to the Profile (or Debug) target config block instead of Release.

To install without flutter install (e.g., if you already have a .app/.ipa):

xcrun devicectl device install app --device "<UDID>" "path/to/Runner.app"
xcrun devicectl device process launch --device "<UDID>" "<bundle.id>"

Icon/logo swaps

When the user supplies a new app icon image:

1. Actually look at it first (Read tool) before resizing anything — a file that's the right pixel dimensions can still be a marketing mockup with placeholder text ("your name here") rather than an icon design. Confirm before applying.
2. Generate all required sizes from one source with Pillow (bundled: scripts/gen_app_icons.py).
3. Every binary change (icon included) needs a build-number bump and a fresh archive/export/upload — icons are baked into the binary, not metadata.

Bundled scripts

• scripts/gen_app_icons.py — regenerates iOS/macOS/Android launcher icons from one source PNG. Edit the paths at the top for the target project, or pass them as arguments if you extend it.
• scripts/setup_build_keychain.sh — the Step 2a/2c keychain bootstrap as a single idempotent script (create-or-reuse keychain, unlock, add to search list). Import certificates separately per Step 2b/2c since those are certificate-specific.