Re-upload an iOS build to TestFlight

First-time setup. Skip whichever you already have.

• A Mac — required. iOS apps can only be built on macOS. Sorry, Windows/Linux users.
• Xcode — Apple's IDE; required to archive and upload. Free.
  • Xcode on the Mac App Store ↗ (recommended — auto-updates)
  • Direct downloads on developer.apple.com ↗ (lets you pick a specific version; requires sign-in)
• Apple Developer Program — $99/year. Required to ship to TestFlight or the App Store (free signing only lets you run on your own device).
  • Enroll in the Developer Program ↗
• App Store Connect record — the listing for your app. Create one at App Store Connect → My Apps → + ↗. You need a Bundle ID (e.g., com.yourname.appname) and an app name.
• Optional but useful: Transporter app — Apple's standalone uploader. Transporter on Mac App Store ↗. Useful when Xcode's built-in upload UI is flaky.
• Optional: App Store Connect API key — for command-line / CI uploads. See Set up an App Store Connect API key.

Apple rejects re-uploads with the same CFBundleVersion. Bump it before archiving.

In Xcode: click your project at the top of the file navigator → select the target → General → Identity. Two fields:

• Version (CFBundleShortVersionString) — the user-visible version. Keep the same for a patch; bump it (e.g., 1.2.0 → 1.2.1) when shipping real changes.
• Build (CFBundleVersion) — increase by 1. Must always increase, even within the same Version.

Or via terminal at the project root:

agvtool next-version -all

CFBundleVersion docs ↗.

In the toolbar (top of Xcode), the device picker must say Any iOS Device (arm64) — not a simulator. Archiving only works against a generic device target.

Menu: Product → Destination → Any iOS Device (arm64).

In Xcode: menu Product → Archive. Xcode builds in Release mode (this takes a minute or two on a typical project), then opens the Organizer window with your archive listed.

Or via terminal:

xcodebuild -scheme YourAppScheme -configuration Release archive \
  -archivePath ~/Desktop/YourApp.xcarchive

Distribution docs ↗.

In Organizer (it opens automatically after Archive), select your archive on the left → click Validate App on the right.

This catches signing problems, entitlement mismatches, and bundle issues before you waste time on a failed upload. Validation takes ~1 minute. Fix anything it flags before continuing.

Option A — Xcode Organizer (easiest).

In Organizer: Distribute App → App Store Connect → Upload. The wizard signs and uploads. Typical time: 2–5 minutes.

Option B — Transporter app (most reliable).

Export an IPA first: in Organizer, Distribute App → App Store Connect → Export. Save the IPA file. Then open Transporter ↗, drag the IPA in, click Deliver.

Useful when Xcode's upload UI hangs (more common than it should be).

Option C — command line (for scripts / CI).

Needs an App Store Connect API key. Then:

xcrun altool --upload-app \
  -f ~/Desktop/YourApp.ipa \
  -t ios \
  --apiKey "$ASC_KEY_ID" \
  --apiIssuer "$ASC_ISSUER_ID"

App Store Connect API docs ↗ · altool reference ↗.

Upload finishes fast (a few minutes). Apple's server-side processing takes longer:

• 5–15 min typical
• 30 min – 2 hr during busy periods (WWDC week, holiday season)
• You'll get an email when it's ready (sometimes spam folder — check)

Watch in App Store Connect ↗ → My Apps → your app → TestFlight tab. Build status flows: Uploading → Processing → Ready to Submit.

When status is Ready to Submit, you have two tester options:

• Internal testing — auto-available to up to 100 users from your App Store Connect team. No review needed; they get it immediately. Right for your own team and tight collaborators.
• External testing — anyone with a link, up to 10,000 testers. First build per group needs Beta App Review (24–48 hours). Subsequent builds usually skip review unless something major changed.

In App Store Connect: TestFlight tab → click your build → toggle which groups can access it. Testers get a push notification in the TestFlight app.

Your testers also need the TestFlight app — TestFlight on the App Store ↗. Send them the link if they don't have it yet.

By default, testers see your build with no notes. You can add release notes in App Store Connect → TestFlight → your build → Test Details → What to Test. Testers see these in the TestFlight app when they update.

Keep notes short and concrete: "Fixed the crash on the settings screen. Try toggling dark mode." Vague notes get vague feedback.

• "No signing certificate found" — Xcode → Settings → Accounts → your Apple ID → Download Manual Profiles. Or enable Automatically manage signing in the target's Signing & Capabilities tab.
• "This bundle version is already in use" — you didn't bump the build number. Go back to Step 1.
• "Missing required icon" — your app icon isn't filled in for all required sizes. Use Apple's icon spec ↗; an asset like appicon.co ↗ generates all sizes from one image.
• "Invalid entitlements" — a capability in your .entitlements file isn't enabled on your provisioning profile. In developer.apple.com → Identifiers ↗, enable the capability on your App ID, then regenerate the profile.
• "ITMS-9000: Bad URL" — Apple's servers are flaky. Retry in 10 minutes. If it persists, switch to Transporter (Option B).