App Store Distribution

Article · 3:00

Signing, provisioning, TestFlight and the review - getting the build off your Mac and onto a stranger's phone.

Signing is the part that confuses everyone, and it is three things. A certificate proves you are you. An App ID names the app and the capabilities it uses. A provisioning profile ties a certificate, an App ID and a set of devices together, and is what is actually embedded in the build. Xcode's automatic signing manages all three and is the right choice until you are on a team with a shared build machine, at which point match-style manual profiles become worth the trouble.

Before the first upload, three things must line up. The bundle identifier is permanent - you cannot change it later without shipping a different app. The version and build number must both increase; the build number must be unique for every upload even if the version is the same. And App Store Connect needs the metadata: screenshots at the required sizes, a description, keywords, a support URL, and a privacy policy URL that resolves.

TestFlight is how you get a real build to real testers. Internal testers - up to 100 people on your team - get it in minutes with no review. External testers, up to 10,000, wait for a short review of the first build. Use it; the Simulator will not tell you that your layout breaks on an iPhone SE or that your app is unusable in bright sun.

Review takes a day or two now. The rejections that catch new apps are the predictable ones: an account you can create but not delete, a permission string that does not say why, a login wall in front of content that does not need one, and placeholder content left in a screenshot.

# The command-line path. Xcode's Product > Archive does the same thing,
# and a continuous-integration machine cannot click Product > Archive.

# 1. Archive the app. -allowProvisioningUpdates lets Xcode fetch or create
#    the profile it needs rather than failing with a signing error.
xcodebuild archive \
  -scheme "MyApp" \
  -destination "generic/platform=iOS" \
  -archivePath build/MyApp.xcarchive \
  -allowProvisioningUpdates

# 2. Export a signed .ipa, following the options in the plist.
xcodebuild -exportArchive \
  -archivePath build/MyApp.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions.plist \
  -allowProvisioningUpdates

# 3. Upload to App Store Connect. Use an app-specific password or an
#    API key - never your Apple ID password in a script.
xcrun altool --upload-app \
  --type ios \
  --file build/export/MyApp.ipa \
  --apiKey "$ASC_KEY_ID" \
  --apiIssuer "$ASC_ISSUER_ID"

# Build numbers must be unique per upload. In CI, use the run number:
#   agvtool new-version -all "$GITHUB_RUN_NUMBER"

Where to go from here

Longer reading about this subject, written alongside the course.

Course guide How to work through this course What to do with each phase, how long to give it, and the three habits that decide whether any of it sticks. 4 min read