iOS build process
Edit this page
Learn how an iOS project is built on EAS Build.
This page describes the process of building iOS projects with EAS Build. You may want to read this if you are interested in the implementation details of the build service.
Build process
Let's take a closer look at the steps for building iOS projects with EAS Build. We'll first run some steps on your local machine to prepare the project, and then we'll build the project on a remote service.
Local steps
The first phase happens on your computer. EAS CLI is in charge of completing the following steps:
-
If
cli.requireCommit
is set totrue
in eas.json, check if the git index is clean - this means that there aren't any uncommitted changes. If it's not clean, EAS CLI will provide an option to commit local changes for you or abort the build process. -
Prepare the credentials needed for the build.
- Depending on the value of
builds.ios.PROFILE_NAME.credentialsSource
, the credentials are obtained from either the local credentials.json file or from the EAS servers. If theremote
mode is selected but no credentials exist yet, you're offered to generate them.
- Depending on the value of
-
Bare projects require an additional step: check whether the Xcode project is configured to be buildable on the EAS servers (to ensure the correct bundle identifier and Apple Team ID are set).
-
Create the tarball containing a copy of the repository. Actual behavior depends on the VCS workflow you are using.
-
Upload the project tarball to a private AWS S3 bucket and send the build request to EAS Build.
Remote steps
In this next phase, this is what happens when EAS Build picks up your request:
-
Create a new macOS VM for the build.
- Every build gets its own fresh macOS VM with all build tools installed there (Xcode, Fastlane, and so on).
-
Download the project tarball from a private AWS S3 bucket and unpack it.
-
Create .npmrc if
NPM_TOKEN
is set. -
Run the
eas-build-pre-install
script from package.json if defined. -
Run
npm install
in the project root (oryarn install
if yarn.lock exists). -
Run
npx expo-doctor
to diagnose potential issues with your project configuration. -
Restore the credentials
- Create a new keychain.
- Import the Distribution Certificate into the keychain.
- Write the Provisioning Profile to the ~/Library/MobileDevice/Provisioning Profiles directory.
- Verify that the Distribution Certificate and Provisioning Profile match (every Provisioning Profile is assigned to a particular Distribution Certificate and cannot be used for building the iOS with any other certificate).
-
Additional step for managed projects: Run
npx expo prebuild
to convert the project to a bare one. This step will use the versioned Expo CLI. -
Restore a previously saved cache identified by the
cache.key
value in the build profile. -
Run
pod install
in the ios directory inside your project. -
Run the
eas-build-post-install
script from package.json if defined. -
Update the Xcode project with the ID of the Provisioning Profile.
-
Create Gymfile in the ios directory if it does not already exist (check out the Default Gymfile section).
-
Run
fastlane gym
in the ios directory. -
Deprecated: Run the
eas-build-pre-upload-artifacts
script from package.json if defined. -
Store a cache of files and directories defined in the build profile. Podfile.lock is cached by default. Subsequent builds will restore this cache.
-
Upload the application archive to a private AWS S3 bucket.
- The artifact path can be configured in eas.json at
builds.ios.PROFILE_NAME.applicationArchivePath
. It defaults to ios/build/App.ipa. You can specify a glob-like pattern forapplicationArchivePath
. We're using the fast-glob package under the hood.
- The artifact path can be configured in eas.json at
-
If the build was successful: run the
eas-build-on-success
script from package.json if defined. -
If the build failed: run the
eas-build-on-error
script from package.json if defined. -
Run the
eas-build-on-complete
script from package.json if defined. TheEAS_BUILD_STATUS
env variable is set to eitherfinished
orerrored
. -
Upload the build artifacts archive to a private AWS S3 bucket if
buildArtifactPaths
is specified in the build profile.
Building iOS projects with Fastlane
We're using Fastlane for building iOS projects. To be more precise, we're using the fastlane gym
command (see the Fastlane docs to learn more). This command allows you to declare the build configuration in Gymfile.
EAS Build can use your own Gymfile. All you need to do is to place this file in the ios directory.
Default Gymfile
If the ios/Gymfile file doesn't exist, the iOS builder creates a default one which looks similar to the following:
suppress_xcode_output(true)
clean(true)
scheme("app")
export_options({
method: "app-store",
provisioningProfiles: {
"com.expo.eas.builds.test.application" => "dd83ed9c-4f89-462e-b901-60ae7fe6d737"
}
})
export_xcargs "OTHER_CODE_SIGN_FLAGS=\"--keychain /tmp/path/to/keychain\""
disable_xcpretty(true)
output_directory("./build")
output_name("App")