How to upload a build to TestFlight from your Mac
By Senthil Kumar P · Updated · 7 min read
Short answer
To upload a build to TestFlight from a Mac, archive the app in Xcode and choose Distribute App › App Store Connect in the Organizer, or drag the .ipa into Apple's Transporter app. To do it from the command line, export the archive with xcodebuild -exportArchive using an export options plist with destination set to upload and an App Store Connect API key. VenelX Studio does the upload from your Mac with one click and then manages TestFlight groups and App Review.
Before you upload
Every method needs the same things:
- An Apple Developer Program membership and an app record in App Store Connect with a matching bundle ID.
- A build number (
CFBundleVersion) higher than any build you've already uploaded for that version. - Distribution signing: automatic signing in Xcode, or a distribution certificate and App Store provisioning profile.
- If your app uses no non-exempt encryption, set
ITSAppUsesNonExemptEncryptiontoNOin Info.plist to skip the export-compliance question for every build.
1. Xcode Organizer (easiest, one-off uploads)
- Choose a generic iOS device or Any iOS Device as the run destination.
- Product › Archive. The Organizer opens when the archive finishes.
- Select the archive and click Distribute App.
- Choose TestFlight & App Store (or TestFlight Internal Only for internal testers), and follow the prompts.
Good for occasional releases; not something you can hand to a teammate who doesn't have your Mac.
2. Transporter (upload an existing .ipa)
Apple's free Transporter app on the Mac App Store uploads an .ipa you already exported. Sign in with your Apple ID, drag the file in and click Deliver. Useful when someone else built the IPA.
3. xcodebuild with an App Store Connect API key (scriptable)
Archive, then export straight to App Store Connect. An API key avoids Apple ID passwords and two-factor prompts.
xcodebuild -workspace App.xcworkspace -scheme App -configuration Release \
-destination 'generic/platform=iOS' -archivePath build/App.xcarchive archive
ExportOptions.plist:
<?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>destination</key>
<string>upload</string>
</dict>
</plist>
xcodebuild -exportArchive -archivePath build/App.xcarchive \
-exportOptionsPlist ExportOptions.plist -exportPath build/export \
-allowProvisioningUpdates \
-authenticationKeyPath ~/keys/AuthKey_ABC123XYZ.p8 \
-authenticationKeyID ABC123XYZ \
-authenticationKeyIssuerID 00000000-0000-0000-0000-000000000000
On Xcode versions before 15.3 the method is named app-store. This is what most CI setups (and fastlane's pilot) wrap.
4. VenelX Studio (one click, from any browser)
VenelX Studio runs the build on your Mac and uploads it through the App Store Connect API, with the API key kept in the Mac's Keychain. From studio.venelx.com your team can then:
- add the build to TestFlight groups for internal and external testers,
- submit it for App Review with release notes checked against Apple's limits,
- turn on a 7-day phased release, with an approval step before production if you want one.
Nobody else needs a copy of the key, and nobody needs to sit at the Mac.
Which should you use?
| Method | Best for | Needs someone at the Mac? |
|---|---|---|
| Xcode Organizer | Occasional, manual releases | Yes |
| Transporter | Uploading an IPA someone else built | Yes |
| xcodebuild + API key | Scripts and CI pipelines | No, once scripted |
| VenelX Studio | Teams releasing from a shared Mac mini | No |
Common upload errors
- "The bundle version must be higher than the previously uploaded version": increase
CFBundleVersionand archive again. - "No profiles for ... were found": add
-allowProvisioningUpdateswith an API key, or install the App Store provisioning profile. - Build stuck in Processing: processing time varies; if it lasts hours, check your email for a rejection from App Store Connect, such as a missing privacy usage description.