Verify custom build execution in logs
After a custom build completes, you can verify that your custom scripts were executed by checking the logs on the build's detail page.
Expo & React Native · all subjects
custom builds
64 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
Custom builds allow running commands before, during, or after build process
Custom builds allow customizing the build process for your project by running commands before, during, or after the build process. Customized builds can run from EAS CLI or when running builds in a React Native CI/CD pipeline, such as with EAS Workflows.
Custom build config file location and structure
Create a custom build config by making directories and a file named .eas/build/hello-world.yml at the same level as eas.json. The location and name of both directories are important for EAS Build to identify that a project contains a custom build config. The filename can be anything; the only requirement is that the file extension uses .yml.
Custom build config YAML structure
A custom build config YAML file contains a build section with a name property and a steps array. Each step can use the run key to execute commands. Built-in functions can also be called within steps.
Example custom build config with echo command
build: name: Hello World! steps: - run: echo "Hello, world!"
Separate custom build configs for iOS and Android
You can create separate YAML config files for each platform and specify them in eas.json using ios and android properties within a build profile. For example, you can use hello-ios.yml for iOS and hello-android.yml for Android.
Running a custom build from EAS CLI
To run a custom build, use the command: eas build -p android -e test (or other platform like ios). Replace 'test' with your build profile name.
steps[].run.name property
The `name` property under `steps[].run` is used in build logs to display the name of the step.
steps[].run.command is required
The `command` property is required for each step and defines a custom shell command to run. It can be a single-line or multiline shell command.
steps[].run.working_directory changes step directory
The `working_directory` property defines an existing directory path from the project's root. When specified, it changes the current directory for that step.
steps[].run.shell sets executable shell
The `shell` property defines the default executable shell for a step, for example `/bin/sh`. If not specified, the default shell is used.
steps[].run.inputs provides values to steps
The `inputs` property provides input values to a step. These values can be accessed using the syntax `${ inputs.name }` in the step's command.
steps[].run.outputs expects output values
The `outputs` property specifies an output value expected during a step. Outputs are produced using the `set-output` executable and can be accessed in other steps.
set-env shares environment variables across steps
Environment variables exported using `export` in one step are not automatically available in other steps. To share an environment variable across steps, use the `set-env` executable with two arguments: the variable name and value, e.g., `set-env NPM_TOKEN "abcdef"` exposes `$NPM_TOKEN` to other steps.
set-env does not export variables locally
Variables set with `set-env` are not automatically exported in the current shell context. To use a variable in the current step, you must call `export` yourself.
functions section defines reusable functions
The `functions` section is used to describe reusable functions that can be used in a build config's steps. Each function is defined with a key name used to identify it.
functions.[function_name].name display name
The `name` property under a function specifies the display name used in build logs.
functions.[function_name].inputs provides function inputs
The `inputs` property defines input values provided to a function. Each input can have properties including `name`, `required`, `type`, `default_value`, and `allowed_values`.
inputs[].name property
The `name` property in a function's input defines the input identifier used to access the value in bash command interpolation.
inputs[].required property
The `required` property is a boolean that indicates whether an input value is required or optional.
inputs[].type can be string, num, or json
The `type` property specifies the input value type. Valid types are `string` (default), `num` (number), or `json`. Input values, `default_value`, and `allowed_values` are validated against the specified type.
inputs[].default_value sets default input
The `default_value` property provides a default input value for a function.
inputs[].allowed_values restricts input options
The `allowed_values` property provides an array of allowed values for an input. The input must be one of these values.
functions.[function_name].outputs defines function output
The `outputs` property defines an output value expected from a function. Outputs can be specified as a simple list like `outputs: [value]` or as objects with `name` and `required` properties.
outputs[].name property
The `name` property in an output defines the output identifier used to access the value in other steps.
outputs[].required indicates if output is required
The `required` property is a boolean that indicates whether an output value is required or optional.
functions.[function_name].command or path is required
Each function must define either a `command` property (to run a simple shell script) or a `path` property (to reference a JavaScript/TypeScript module). One of these is required.
functions.[function_name].command defines shell command
The `command` property defines the shell command to run when a function is executed.
functions.[function_name].path references JS/TS module
The `path` property defines the path to a JavaScript or TypeScript module that implements the function.
functions.[function_name].shell sets function's executable shell
The `shell` property defines the default executable shell for a step where a function is executed, for example `/bin/sh`.
functions.[function_name].supported_platforms restricts platforms
The `supported_platforms` property defines the supported platforms for a function. It defaults to all platforms. Allowed platforms are `darwin` (macOS) and `linux`.
import section imports functions from other config files
The `import` section contains a list of config file paths to import functions from other files. Imported files cannot have the `build` section.
eas/build is all-in-one build function
The `eas/build` function is a built-in EAS function that encapsulates the entire EAS Build process. It resolves the best build configuration based on the build profile's settings from eas.json and is ideal for those who want the build done without manually altering the build process.
eas/build limitations
The `eas/build` function doesn't accept any inputs and the resolved build process is not configurable. If customization is needed, use the subset of functions that are executed behind the scenes instead.
eas/checkout checks out project source files
The `eas/checkout` function checks out the project source files. For Git-based project sources, it uses the build's recorded commit by default. The `ref` input can be used to check out a different branch, tag, or commit.
eas/checkout ref input options
The `ref` input in `eas/checkout` accepts a branch name (bare or qualified), a tag as a qualified ref like `refs/tags/v1.2.3`, or a full commit SHA. It only works with Git-based project sources.
eas/use_npm_token configures package managers
The `eas/use_npm_token` function configures Node package managers (bun, npm, pnpm, or Yarn) for use with private packages. It sets `NPM_TOKEN` from project secrets and creates a `.npmrc` file with the token.
eas/install_node_modules installs dependencies
The `eas/install_node_modules` function installs node_modules using the detected package manager (bun, npm, pnpm, or Yarn) based on the project. It works with monorepos.
eas/restore_build_cache restores cached artifacts
The `eas/restore_build_cache` function restores a previously saved build cache from a specified key to speed up builds by reusing cached artifacts. It accepts properties: `name` (optional, defaults to 'Restore build cache'), `inputs.key` (required, cache key to restore with optional dynamic expressions like `${{ hashFiles('package-lock.json') }}`), `inputs.restore_keys` (optional, fallback prefix if exact key not found), and `inputs.path` (required, path where cache should be restored).
eas/save_build_cache saves cached artifacts
The `eas/save_build_cache` function saves a build cache to a specified key for reuse in subsequent builds. It accepts properties: `name` (optional, defaults to 'Save build cache'), `inputs.key` (required, cache key with optional dynamic expressions like `${{ hashFiles('package-lock.json') }}`), and `inputs.path` (required, directory or files to cache).
eas/resolve_build_config resolves build configuration
The `eas/resolve_build_config` function resolves and prints the build configuration. For GitHub integration builds, it updates the current `job` and `metadata` context values. It should be called after installing dependencies because config may be influenced by config plugins.
eas/resolve_apple_team_id_from_credentials iOS only
The `eas/resolve_apple_team_id_from_credentials` function is only available for iOS builds. It resolves the Apple team ID from build credentials and stores it in the `outputs.apple_team_id` output value. It accepts properties: `name` (optional, defaults to 'Resolve Apple team ID from credentials'), `inputs.credentials` (optional, defaults to `${ eas.job.secrets.buildCredentials }`, must comply to iOS schema).
eas/prebuild runs expo prebuild command
The `eas/prebuild` function runs the `expo prebuild` command using the detected package manager (bun, npm, pnpm, or Yarn) with the command best suited for the build type and environment. It accepts properties: `name` (optional), `inputs.clean` (optional, boolean), `inputs.apple_team_id` (optional, for iOS builds).
eas/configure_eas_update configures runtime version and channel
The `eas/configure_eas_update` function configures runtime version and release channel for the build. It requires EAS Update to be configured for the project. It accepts properties: `name` (optional, defaults to 'Configure EAS Update'), `inputs.runtime_version` (optional, defaults to `${ eas.job.version.runtimeVersion }` or native runtime version), `inputs.channel` (optional, defaults to `${ eas.job.updates.channel }`).
eas/inject_android_credentials Android only
The `eas/inject_android_credentials` function is only available for Android builds. It configures Android keystore with credentials and injects app signing config into gradle config. It accepts properties: `name` (optional, defaults to 'Inject Android credentials'), `inputs.credentials` (optional, defaults to `${ eas.job.secrets.buildCredentials }`, must comply to Android schema).
eas/configure_ios_credentials iOS only
The `eas/configure_ios_credentials` function is only available for iOS builds. It configures iOS credentials and modifies the Xcode project by assigning provisioning profiles to targets. It accepts properties: `name` (optional, defaults to 'Configure iOS credentials'), `inputs.build_configuration` (optional, defaults to `${ eas.job.buildConfiguration }` or 'Debug'/'Release'), `inputs.credentials` (optional, defaults to `${ eas.job.secrets.buildCredentials }`).
eas/configure_android_version Android only
The `eas/configure_android_version` function is only available for Android builds. It configures the Android app version for remote app version management. It accepts properties: `name` (optional, defaults to 'Configure Android version'), `inputs.version_code` (optional, defaults to `${ eas.job.version.versionCode }`), `inputs.version_name` (optional, defaults to `${ eas.job.version.versionName }`).
eas/configure_ios_version iOS only
The `eas/configure_ios_version` function is only available for iOS builds. It configures the iOS app version for remote app version management. It accepts properties: `name` (optional, defaults to 'Configure iOS version'), `inputs.build_number` (optional, defaults to `${ eas.job.version.buildNumber }`), `inputs.app_version` (optional, defaults to `${ eas.job.version.appVersion }`), `inputs.build_configuration` (optional, defaults to `${ eas.job.buildConfiguration }` or 'Debug'/'Release'), `inputs.credentials` (optional, defaults to `${ eas.job.secrets.buildCredentials }`).
eas/run_gradle Android only
The `eas/run_gradle` function is only available for Android builds. It runs a Gradle command to build the Android app. It accepts properties: `name` (optional, defaults to 'Run gradle'), `inputs.command` (optional, resolved based on build configuration if not specified).
eas/generate_gymfile_from_template iOS only
The `eas/generate_gymfile_from_template` function is only available for iOS builds. It generates a Gymfile used by Fastlane to build the iOS app. It accepts properties: `name` (optional, defaults to 'Generate Gymfile from template'), `inputs.template` (optional, uses default template if not specified), `inputs.credentials` (optional, provides keychain/export method/profiles to template), `inputs.build_configuration` (optional, defaults to Debug/Release), `inputs.scheme` (optional, defaults to first scheme found), `inputs.clean` (optional boolean, defaults to true), `inputs.extra` (optional json, extra values for custom templates). Default templates include CLEAN, SCHEME, BUILD_CONFIGURATION, EXPORT_METHOD, PROFILES, ICLOUD_CONTAINER_ENVIRONMENT, KEYCHAIN_PATH, LOGS_DIRECTORY, OUTPUT_DIRECTORY, DERIVED_DATA_PATH, and SCHEME_SIMULATOR_DESTINATION variables.
eas/run_fastlane iOS only
The `eas/run_fastlane` function is only available for iOS builds. It runs `fastlane gym` command against the Gymfile in the ios project directory to build the iOS app.
eas/maestro_test all-in-one testing function
The `eas/maestro_test` function is an all-in-one function that installs Maestro, prepares a testing environment (Android Emulator or iOS Simulator), and runs app tests. It requires the project to use old Build Infrastructure to start Android Emulator. Behind the scenes it uses eas/install_maestro, eas/start_android_emulator (if needed), eas/start_ios_simulator (if needed), run steps to install app, run steps to execute maestro test, and eas/upload_artifact.
eas/maestro_test inputs specification
The `eas/maestro_test` function accepts inputs: `flow_path` (string, required, path or multiple paths to Maestro flows to run), `app_path` (string, optional, path or regex pattern to emulator/simulator app; defaults to android/app/build/outputs/**/\.apk for Android or ios/build/Build/Products/*simulator/*.app for iOS).
eas/maestro_test Xcode 15 warning
Maestro tests often time out if run on images with Xcode 15.0 or 15.2. Use the `latest` image to avoid timeout issues.
set-output produces step output
The `set-output` executable is used to produce output values from a step. It takes two arguments: the output name and value, e.g., `set-output value "Output from step"`.
Reference step output with steps context
Step outputs can be accessed in other steps using the syntax `${ steps.step_id.output_name }` where step_id is the id assigned to the step.
steps[].run.outputs.required controls if output is required
An output value can use a boolean `required` property to indicate if the output is required or optional. Outputs can be specified as a simple list like `outputs: [value]` or as objects with `name` and `required: false` properties.
Dash before run counts as indentation
In YAML syntax, the dash (-) before `run` in a step counts as indentation and must be properly positioned.
steps[].run.id enables step reference and reuse
Defining an `id` for a step allows calling the same function multiple times and using output from one step in another step. The id is used to reference the step in subsequent steps.
Custom build config file location and syntax
Custom build config files are stored inside the `.eas/build` directory and use YAML syntax with `.yml` or `.yaml` file extension.