How to Setup Apple

Upload an .ipa to App Store Connect / TestFlight, and optionally add that build to your TestFlight beta groups.

!NOTE: The Apple service is marked Experimental. It works, but expect rough edges.

!IMPORTANT: Uploading requires macOS. The upload runs through Xcode's xcrun altool, which only exists on a Mac. You can fill everything in on Windows and Linux, and the Add To TestFlight Group action works anywhere because it uses the web API - but the upload itself will not run.

---

Where things get saved

• Edit->Preferences->Build Uploader->Services->Apple holds the path to your .p8 private key file. Saved to your own PC only and never written into your project. Every person on your team points at their own copy.
• Project Settings->Build Uploader->Services->Apple holds app names, bundle IDs, key IDs and beta group IDs. Saved to <YourProjectPath>/BuildUploader/ and safe to commit so your team shares them.

Create the entry in Project Settings, then point at the key file in Preferences. The Name is what links the two - it must match exactly.

---

1. Create an App Store Connect API key

• Go to App Store Connect->Users and Access
  • (Or press the App Store Connect button at the top of the Preferences page)
• Go to the Integrations tab -> App Store Connect API
• Press + to generate a new key
  • Give it a name (eg: Build Uploader)
  • Access: App Manager is enough to upload and manage TestFlight
• Press Generate
• Note down three things:
  • The Issuer ID, shown above the list of keys
  • The Key ID, shown in the row for your new key
  • The private key file - press Download API Key in that row

!IMPORTANT: The .p8 file can only be downloaded once. Save it somewhere safe and back it up.

!IMPORTANT: Do not rename the file. It must keep Apple's naming convention AuthKey_<KeyID>.p8 - eg: AuthKey_ABC123DEF4.p8. altool finds the key by filename, and the Build Uploader will refuse to start if the name doesn't match.

Store the .p8 somewhere outside your Unity project so it never gets committed.

---

2. Setup Preferences: Edit->Preferences->Build Uploader->Services->Apple

• Turn on Enabled
• Under API Keys press + to create a key entry
  • Name: anything you like. This is just a label so you can pick it in a dropdown later. eg: Release Key
  • Issuer: the Issuer ID from step 1
  • Key ID: the Key ID from step 1
  • Press Browse and select your AuthKey_<KeyID>.p8 file

If you are not on a Mac you'll see a warning here. That's expected - see the note at the top of this page.

---

3. Setup Project Settings: Project Settings->Build Uploader->Services->Apple

Add the API key

• Under API Keys press +
  • Name: the exact same Name you used in Preferences
  • Issuer and Key ID: the same values again. These are safe to commit - only the .p8 file is secret

Add your app

• Press Add App at the top
  • Name: anything you like. eg: My Game
  • Bundle ID: your CFBundleIdentifier. eg: com.example.MyGame
    • This must match what Unity builds. Check Project Settings->Player->Identification
  • App Store Connect ID: the numeric app ID
    • Open your app in App Store Connect and read it out of the URL - it's the long number
  • Platform: iOS, tvOS, macOS or visionOS

Add beta groups (only if using the TestFlight action)

• Under Beta Groups press +
  • Name: anything you like. eg: External Testers
  • Group ID: the group's ID from App Store Connect. It looks like 12a3b4c5-6789-0abc-def0-1234567890ab
    • Open TestFlight->your group in App Store Connect and read it out of the URL

---

4. Use it in an Upload Config

Your source needs to produce a signed .ipa. The Build Uploader uploads what you give it - it does not sign anything for you.

Uploading to TestFlight

• Go to Window->Build Uploader->Open Window
• Add an Apple TestFlight destination to your Upload Config
  • API Key: the key you made
  • App: the app you made
  • Platform and Bundle ID are filled in from the app you picked
  • Build Version: the CFBundleShortVersionString to look for. Comes pre-filled with a sensible default
  • Build Number: the CFBundleVersion to look for. Comes pre-filled with a sensible default
    • Both support {keys} - see String Formatter
    • These are used to find your build again after the upload, so they must match what's actually inside the .ipa
  • Find Build Timeout (s): how long to wait for Apple to finish processing. Defaults to 600 (10 minutes)
    • Apple's processing pipeline is slow. Do not lower this unless you know it's fast for your app

Adding it to a beta group

• Add an Apple Add To TestFlight Group action
  • API Key: the same key
  • App: the same app
  • Beta Groups: tick the groups the build should go to
  • Build ID Format: comes pre-filled with the key produced by the upload destination. Leave it alone unless you know why you're changing it
• Set Triggers to OnTaskFinished and When To Execute to IfSuccessful so it only runs when the upload worked

!NOTE: The action needs the destination above to have run first - that's what supplies the build ID.