Why does a React Native app's iOS release build need a macOS CI runner, and what must that runner have installed?
answer
- Apple's build tools, Apple's operating system
- Xcode 16.1 minimum for 0.87
- CocoaPods pinned by Gemfile, run through Bundler
- Node for the bundle build phase
- .xcode.env sets NODE_BINARY
basics
~20 sThe iOS app is compiled, linked, signed and archived by Xcode's tools, which run only on macOS. The runner needs Xcode (16.1 or newer for React Native 0.87), Ruby with CocoaPods, and Node for the JavaScript bundle step.
solid answer
~50 sA React Native iOS binary is an Xcode project: `xcodebuild` compiles the native code, signs it and produces the archive, and Apple ships that toolchain only for macOS, so the iOS job needs a macOS runner (or a hosted builder such as EAS that runs macOS for you). The runner must carry Xcode at or above the minimum React Native declares (16.1 for 0.87), Ruby plus the CocoaPods version pinned in the project's `Gemfile` (installed with `bundle install`, run as `bundle exec pod install`), and a Node version that matches the `engines` range. Node matters inside the Xcode build too: the Release configuration runs the *Bundle React Native code and images* phase, which finds Node through `NODE_BINARY` in `ios/.xcode.env`. The Android half builds on Linux, so most teams split the two platforms into separate jobs.
code
bash · 8 lines# iOS job on a macOS runner
npm ci
cd ios
bundle install
bundle exec pod install
xcodebuild -workspace GymBooking.xcworkspace -scheme GymBooking \
-configuration Release -destination 'generic/platform=iOS' \
-archivePath build/GymBooking.xcarchive archivego deeper
Recall that Xcode only runs on macOS, so the iOS build needs a macOS machine, and that the runner needs Xcode, CocoaPods and Node.
Explain where each tool enters the build: pod install running autolinking and codegen, and the bundle phase finding Node through NODE_BINARY in .xcode.env.
Show how you pin Xcode, Ruby, CocoaPods and Node on the image, and how you diagnose a runner image update that breaks a build with no code change.
Weigh owning a macOS runner fleet against a hosted builder: cost per minute, image maintenance, signing custody and how many apps share the pipeline.
## Why the iOS half needs macOS A React Native app is two native projects plus one JavaScript bundle. The **iOS project** is an ordinary Xcode workspace: CocoaPods installs the native dependencies, `xcodebuild` compiles Objective-C, C++ and Swift, links the React Native core, embeds the JavaScript bundle, signs the result and writes an archive. Apple publishes Xcode, its compilers, its SDKs and its signing tools **only for macOS**, so there is no supported way to produce a signed iOS build on a Linux machine. That gives a CI pipeline two options for iOS: - run the build on a **macOS runner** you control or rent, or - hand the build to a **hosted builder** that runs macOS for you, such as EAS Build for Expo projects. The **Android half** has no such constraint. Gradle, the Android SDK and the NDK run on Linux, so the Android job normally runs on a cheaper Linux runner. Splitting the platforms into two jobs keeps the expensive macOS minutes for the work that actually needs them. ## What the runner must carry | Tool | Why a React Native iOS build needs it | How the project pins it | |---|---|---| | **Xcode** | compiles, signs and archives the app | React Native 0.87 declares a minimum of Xcode 16.1; pick the image explicitly | | **Ruby + Bundler** | runs CocoaPods | the Ruby version on the image; the template's `Gemfile` | | **CocoaPods** | installs native pods, runs autolinking and codegen | `Gemfile` / `Gemfile.lock`, invoked as `bundle exec pod install` | | **Node** | runs Metro's bundler and codegen | `engines` in `package.json` (`^22.13.0 \|\| ^24.3.0 \|\| >= 26.0.0` for 0.87.1) | | **JS package manager** | installs `node_modules` from the lockfile | the committed lockfile | Pinning matters more on CI than on a laptop. A runner image that silently moves to a newer Xcode or CocoaPods can change the build without a single commit in the repository. ## How the pieces meet during one build 1. Install JavaScript dependencies from the lockfile. 2. `bundle install`, then `bundle exec pod install` inside `ios/`. The Podfile's `use_react_native!` runs **autolinking** and **codegen** here, so the generated New Architecture code is produced on the runner. 3. `xcodebuild` builds the workspace in the **Release** configuration. 4. The **Bundle React Native code and images** build phase sources `ios/.xcode.env` (then `.xcode.env.local` if present), reads `NODE_BINARY`, runs the bundler and compiles the bundle to Hermes bytecode. 5. The archive is signed and exported for upload. Step 4 is why Node is not only a pre-build dependency: Xcode itself starts Node during the build. ## First-run failures on a fresh macOS runner - **"Can't find the node binary to build the React Native bundle"**: the build phase could not resolve `NODE_BINARY`. The committed `.xcode.env` should use `export NODE_BINARY=$(command -v node)`, not a path from one developer's machine; `.xcode.env.local` is gitignored and machine-specific. - **CocoaPods version drift**: a global `pod` on the image differs from the one the lockfile was written with. Running through `bundle exec` uses the pinned gem. - **Xcode older than the React Native minimum**: native compile errors that look unrelated to the upgrade that caused them. - **Missing Ruby gems on newer Ruby**: the template's `Gemfile` already lists gems that Ruby 3.4 removed from its standard library; keep it in sync with the template when upgrading. ## Keeping the runner reproducible A laptop drifts slowly; a hosted runner image can change overnight. A few habits keep iOS builds of a React Native app repeatable: - **Select the Xcode version explicitly** at the start of the job rather than trusting the image default, and upgrade it in a commit you can revert. - **Print the toolchain** (`xcodebuild -version`, `node --version`, `bundle exec pod --version`) at the top of the log, so a broken build can be compared with the last green one. - **Install from lockfiles only**: a clean, lockfile-exact JavaScript install, `bundle install` against `Gemfile.lock`, and a committed `ios/Podfile.lock`. - **Build the Release configuration in CI at least daily**, even when developers only run Debug locally, because only Release embeds the bundle and exercises the bundle phase. ## Framework-built projects An Expo project that uses Continuous Native Generation has no committed `ios/` folder; the native project is generated before the build. The runner requirements are the same once it exists, which is why many Expo teams hand the iOS build to EAS Build rather than maintain a macOS image themselves.
- Why should the committed ios/.xcode.env not contain an absolute path to Node?The file is versioned and shared by every machine, including CI. An absolute path from one developer's version manager does not exist on the runner, so the bundle phase fails. The template uses `export NODE_BINARY=$(command -v node)`, and machine-specific overrides belong in `.xcode.env.local`, which is gitignored.
- Can the Android job run on the same macOS runner to keep one pipeline?It can, since Gradle runs on macOS, but it spends the most expensive minutes on work that runs fine on Linux. Most teams run Android on a Linux runner in parallel and keep macOS for the iOS job only.
It is like a document that can be written on any computer but must be notarised at one specific office: the JavaScript can be bundled anywhere, but the signed iOS binary has to pass through Apple's tools, and those only open for business on macOS.
saying these in an interview costs you the question
- You can cross-compile a signed iOS build on a Linux runner
- Node is only needed to install packages, not during the Xcode build
- Any CocoaPods installed on the image is fine; the version does not matter
- Put your own absolute Node path in the committed .xcode.env
- Both platforms must build on the same macOS machine