exori

Docs

Get iOS builds working

Bridge does not know how to build your app — Fastlane does. What Bridge does is hold your credentials, check that everything an App Store distribution actually needs is in place, and run the lane. This page is the one-time Apple setup, in the order that avoids the failures each missing piece causes.

About 30 minutes

1. Apple Developer Program

  1. Enrol

    You need a paid Apple Developer Program membership ($99/yr) to distribute at all — a free Apple ID can run on your own device and nothing more.

  2. Record your Team ID

    It is on the Membership page of developer.apple.com. Paste it into Bridge under Credentials → Apple → Team ID.

2. App Store Connect API key

This is what lets Bridge and Fastlane talk to Apple without an interactive Apple ID login or 2FA prompts.

  1. Generate the key

    In App Store Connect, go to Users and Access → Integrations → App Store Connect API and generate a team key with the App Manager role.

  2. Save all three values

    You need the Issuer ID (shown above the key list), the Key ID, and the .p8 private key file. Apple lets you download the .p8 exactly once — if you lose it, revoke the key and make a new one.

  3. Paste them into Bridge

    Credentials → Apple, then Issuer ID, Key ID, and the contents of the .p8 file. They go into your Mac's Keychain.

3. Signing: team and distribution certificate

Two separate things go wrong here, and they fail at different stages, which makes them easy to confuse.

  1. A development team in the project file

    Archiving fails with Signing "YourApp" requires a development team when DEVELOPMENT_TEAM is not set in the Xcode project itself.

    For an XcodeGen project, add it to project.yml and re-run xcodegen generate. For a hand-managed .xcodeproj, set the team in Xcode's Signing & Capabilities tab. Filling in Team ID in Bridge's Credentials afterwards does not rewrite an already-generated project.

  2. An Apple Distribution certificate on this Mac

    Automatic signing can mint a *development* profile on the fly, which is why archiving can succeed and exportArchive still fails. An App Store export needs an Apple Distribution certificate to already exist in your Keychain.

    Create one in Xcode: Settings → Accounts → your team → Manage Certificates… → + → Apple Distribution. Archiving once through Xcode's own Organizer creates it too. Neither is something a headless Fastlane run can do for you.

    security find-identity -v -p codesigning

4. Register the bundle ID and create the app

  1. Register an explicit App ID

    Developer portal → Certificates, Identifiers & Profiles → Identifiers → + → App IDs → App, with your exact bundle identifier. If you have ever run the app on a device with automatic signing, Xcode has probably registered it already — check before creating a duplicate.

  2. Create the App Store Connect app record

    My Apps → + → New App: platform, name, primary language, the bundle ID from the previous step, and any unique SKU. This one genuinely has to be done in the web UI — Apple's public API can register a bundle ID but has no documented endpoint to create the app record, which is why Bridge only checks for it.

  3. Sign the Paid Apps agreement, if you sell anything

    In-app purchases do not function until Agreements, Tax, and Banking shows Active.

5. Fastlane

Bridge runs one lane per platform by convention: fastlane ios beta. If the project has no Fastfile, it stops immediately rather than guessing.

  1. Generate a starter setup

    In Check Setup, use the Set Up Fastlane button. It writes a fastlane/Fastfile and Appfile with beta lane skeletons and refuses to overwrite anything that already exists.

  2. Fill in the project specifics

    The generated lane is a skeleton, not a working build. The scheme name and export method are yours to set — Bridge does not know your project's internals and does not pretend to.

  3. Leave the provisioning flag alone

    build_app is generated with xcargs: "-allowProvisioningUpdates". Without it xcodebuild refuses to create a provisioning profile from the command line, so a project's very first distribution export fails with No profiles for '<bundle id>' were found even when everything else is correct.

  4. Note the build-number bump

    The generated iOS lane sets the build number from latest_testflight_build_number + 1, reading the real number already on TestFlight rather than trusting the local project file. TestFlight rejects a second upload at the same build number, so keep this — or do the equivalent in your own lane.

6. Run the build

  1. From Bridge

    Select the project and choose Build → iOS. The Build Status section streams the log and keeps the history.

  2. From your phone

    Open the project, tap Build & Publish, and you get the same Check Setup checklist above the Build button. The build still runs on your Mac, with your credentials, and the log comes back over the tunnel.

  3. Then TestFlight

    The beta lane convention is expected to end in upload_to_testflight. Processing on Apple's side takes a few minutes, after which the build appears in TestFlight for internal testers.