Skip to main content

iOS Beta (Ad Hoc) Developer Setup

Purpose​

This guide explains how each developer gets the iOS beta app on a physical device using the beta ad hoc lane.

Use this when:

  • you need to test native changes before TestFlight promotion
  • you need quick internal device testing on the beta lane

Beta lane definition​

  • Branch lane: beta
  • EAS build profile: beta
  • iOS distribution type: ad hoc/internal (non-App Store)
  • Install target: registered developer/tester devices

Prerequisites​

Each developer needs:

  • access to the mobile repo
  • EAS CLI installed (npm i -g eas-cli or project-managed equivalent)
  • Expo account access to the ferda-tech project
  • an iPhone (ad hoc installs do not use iOS simulator)
  • device UDID registered with Apple via EAS device registration

One-time team setup (release owner)​

  1. Confirm beta profile is internal/ad hoc in eas.json.
  2. Make sure the signing owner account can manage iOS devices/certificates.
  3. Decide build ownership:
    • recommended: release owner queues beta builds
    • optional: any approved developer can queue beta builds
  4. Share the install URL process with the team (EAS build page link).

Per-developer onboarding (required once per device)​

Step 1: Login to Expo​

eas whoami

If not authenticated:

eas login

Step 2: Register iPhone device for ad hoc signing​

eas device:create

Notes:

  • Complete the browser/device profile flow when prompted.
  • This adds the device UDID so ad hoc provisioning can include that device.
  • If a developer changes phones, this step must be repeated.

Step 3: Verify the device is registered​

eas device:list

Confirm the new device appears and is enabled.

Step 4: Queue a beta iOS build​

From the mobile repo:

eas build --platform ios --profile beta

If your team uses build intent branches:

git push origin build/beta

The pre-push hook should queue:

eas build --profile beta --platform all --non-interactive --no-wait

Step 5: Install the build on device​

  1. Open the completed build page URL from EAS output.
  2. Open the install link on the target iPhone.
  3. Follow iOS prompts to install the ad hoc build.

If install is blocked, check troubleshooting below.

Day-to-day developer flow​

  1. Work on feature/*.
  2. Merge to beta through normal PR approvals.
  3. Pull latest beta.
  4. Ensure your device is registered (eas device:list).
  5. Install latest beta ad hoc build from EAS build link.
  6. Validate on real device and report issues before alpha promotion.

Troubleshooting​

"I cannot install the beta build on my phone"​

Check in this order:

  1. Device UDID is registered (eas device:list).
  2. Build was created after your device was registered.
  3. Correct profile was used (beta, not alpha or production).
  4. You opened install link on the same physical device.
  5. iOS network/security settings are not blocking install.

If device was added after build creation, queue a new beta build.

"Build succeeded but app still not updated"​

  • For JS changes, ensure latest OTA beta update was published.
  • For native-impacting changes, install a newly built binary (OTA alone is not enough).

"Pre-push did not queue the build"​

Check:

  • SKIP_EAS_PREPUSH is not set to 1
  • EAS CLI is installed
  • non-interactive auth works (eas whoami --non-interactive)
  • pushed branch matches build/*

Operational reminders​

  • Beta ad hoc is for internal device testing, not broad tester distribution.
  • TestFlight validation starts at alpha.
  • Production App Store release starts from main / production.