Runbook: iOS native-build toolchain — Runbooks

Owner: mobile team Last reviewed: 2026-05-28

Audit #58 called out missing host-environment setup for iOS builds. This runbook lists the prerequisites and the one-shot check script that verifies them.

Required tooling#

Tool	Required version	Why
macOS	13+	Xcode 15 requires Ventura or later
Xcode.app	15.0+	iOS 17+ SDK; AGP 8.x / RN 0.85 toolchain
Command Line Tools	any current	required by `xcrun simctl`, `xcodebuild`
Ruby	3.0+	CocoaPods 1.15 dropped Ruby 2.6 (macOS default)
CocoaPods	1.15+	Required by RN 0.85 / Expo SDK 55+ podfile syntax
iOS simulator runtime	iOS 17 SDK or later	Detox / e2e runs

scripts/check-ios-toolchain.sh reports each of the above and exits non-zero on any missing piece — run it before opening a "my iOS build broke" Linear ticket.

Step-by-step setup#

Install Xcode.app from the Mac App Store (free, ~12 GB). Command Line Tools alone are NOT sufficient — they ship a stripped toolchain that cannot build iOS apps.
Switch active developer dir to Xcode.app:
bash
```
sudo xcode-select -s /Applications/Xcode.app
```
Accept the Xcode license (required for xcodebuild):
bash
```
sudo xcodebuild -license accept
```

Install Ruby 3.x via Homebrew. macOS ships 2.6.10 which CocoaPods has dropped:

bash

brew install ruby
echo 'export PATH="$(brew --prefix)/opt/ruby/bin:$PATH"' >> ~/.zshrc
exec zsh
ruby --version  # → ruby 3.x

Install CocoaPods:

bash

gem install cocoapods
pod --version  # → 1.15+

Install at least one iOS simulator runtime:
bash
```
xcodebuild -downloadPlatform iOS
```
Verify the whole stack:
bash
```
scripts/check-ios-toolchain.sh
```

CI runners#

CI uses macos-14 (Sonoma) runners — Xcode 15.4 is preinstalled. The mobile-e2e.yml workflow pins this via sudo xcode-select -s /Applications/Xcode_15.4.app early in each iOS job. The mobile-build-smoke.yml workflow added in #83 does the same.

If a build fails on CI with "xcodebuild: command not found", first check the runner image (a deprecated macos-12 would mean Xcode 14 is the default). Bump to macos-14 in the workflow file.

Common failures#

error: Could not find ... during pod install → Ruby version drift. Re-run the toolchain check; CocoaPods loads .gemspec files that pin Ruby ≥3.
xcrun: error: invalid active developer path → step 2 above wasn't run, or Xcode.app was moved. Re-run sudo xcode-select -s /Applications/Xcode.app.
xcodebuild requires Xcode, but active developer directory ... is Command Line Tools → same as above.
iOS simulator boot hangs in CI → the runner is on a stale image. In CI, the iPhone 15 simulator that mobile-e2e.yml expects requires iOS 17 SDK; xcodebuild -downloadPlatform iOS is preinstalled on macos-14 but missing on macos-12.