HomeGuidesReferenceLearn

Custom build configuration schema

A reference of configuration options for custom builds with EAS Build.


This functionality is in preview, under active development, and likely to change.

Creating custom workflows for EAS Build helps customize the build process for your project.

YAML syntax for workflows

Workflow files are stored inside the .eas/build directory path. They use YAML syntax and must have a .yml or .yaml file extension. If you are new to YAML or want to learn more about the syntax, see Learn YAML in Y minutes.

build

Defined to describe a custom workflow. All config options to create a workflow are specified under it.

name

The name of your workflow that is used to identify the workflow in the build logs. EAS Build uses this property to display the name of your workflow in the dashboard.

For example, the workflow's name is Run tests:

build:
  name: Run tests
  steps:
    - eas/checkout
    - run:
        name: Install dependencies
        command: npm install

steps

Steps are used to describe a list of actions either in the form of commands or function calls. These actions are executed when a workflow runs on EAS Build. You can define single or multiple steps in a workflow. However, it is required to define at least one step per workflow.

Each step is configured with the following properties:

steps[].run

The run key is used to trigger a set of instructions. For example, a run key is used to install dependencies using the npm install command:

build:
  name: Install npm dependencies
  steps:
    - eas/checkout
    - run:
        name: Install dependencies
        command: npm install

You can also use steps[].run to execute single or multiline shell commands:

build:
  name: Run inline shell commands
  steps:
    - run: echo "Hello world"
    - run: |
        echo "Multiline"
        echo "bash commands"

Use a single step

For example, a workflow with the following steps will print "Hello world":

build:
  name: Greeting
  steps:
    - run: echo "Hello world"

Note: - before run counts as indentation.

Use multiple steps

When multiple steps are defined, they are executed sequentially. For example, a workflow with the following steps will first check out the project, install npm dependencies, and then run a command to run tests:

build:
  name: Run tests
  steps:
    - eas/checkout
    - run:
        name: Install dependencies
        command: npm install
    - run:
        name: Run tests
        command: |
          echo "Running tests..."
          npm test

steps[].run.name

The name that is used in build logs to display the name of the step.

steps[].run.command

The command defines a custom shell command to run when a step is executed. It is required to define a command for each step. It can be a multiline shell command:

build:
  name: Run tests
  steps:
    - eas/checkout
    - run:
        name: Run tests
        command: |
          echo "Running tests..."
          npm test

steps[].run.working_directory

The working_directory is used to define an existing directory from the project's root directory. After an existing path is defined in a step, using it changes the current directory for that step. For example, a step is created to list all the assets inside the assets directory, which is a directory in your Expo project. The working_directory is set to assets:

build:
  name: Demo
  steps:
    - eas/checkout
    - run:
        name: List assets
        working_directory: assets
        command: ls -la

steps[].run.shell

Used to define the default executable shell for a step. For example, the step's shell is set to /bin/sh:

build:
  name: Demo
  steps:
    - run:
        shell: /bin/sh
        command: |
          echo "Steps can use another shell"
          ps -p $$

steps[].run.inputs

Input values are provided to a step. For example, you can use input to provide a value:

build:
  name: Demo
  steps:
    - run:
        name: Say Hi
        inputs:
          name: Expo
        command: echo "Hi, ${ inputs.name }!"

steps[].run.outputs

An output value is expected during a step. For example, a step has an output value of Hello world:

build:
  name: Demo
  steps:
    - run:
        name: Produce output
        outputs: [value]
        command: |
          echo "Producing output for another step"
          set-output value "Output from another step..."

steps[].run.outputs.required

An output value can use a boolean to indicate if the output value is required or not. For example, a function does not have a required output value:

build:
  name: Demo
  steps:
    - run:
        name: Produce another output
        id: id456
        outputs:
          - required_param
          - name: optional_param
            required: false
        command: |
          echo "Producing more output"
          set-output required_param "abc 123 456"

steps[].run.id

Defining an id for a step allows:

  • Calling the same function that produces one or more outputs multiple times
  • Using the output from one step to another

Call the same function one or more times

For example, the following function generates a random number:

functions:
  random:
    name: Generate random number
    outputs: [value]
    command: set-output value `random_number`

In a workflow, let's use the random function to generate two random numbers and print them:

build:
  name: Functions Demo
  steps:
    - random:
        id: random_1
    - random:
        id: random_2
    - run:
        name: Print random numbers
        inputs:
          random_1: ${ steps.random_1.value }
          random_2: ${ steps.random_2.value }
        command: |
          echo "${ inputs.random_1 }"
          echo "${ inputs.random_2 }"

Use output from one step to another

For example, the following workflow demonstrates how to use output from one step to another:

build:
  name: Outputs demo
  steps:
    - run:
        name: Produce output
        id: id123 # <---- !!!
        outputs: [foo]
        command: |
          echo "Producing output for another step"
          set-output foo bar
    - run:
        name: Use output from another step
        inputs:
          foo: ${ steps.id123.foo }
        command: |
          echo "foo = \"${ inputs.foo }\""

functions

Defined to describe a reusable function that can be used in a workflow. All config options to create a function are specified with the following properties:

functions.[function_name]

The [function_name] is the name of a function that you define to identify it in the build.steps. For example, you can define a function with the name greetings:

functions:
  greetings:
    name: Say Hi!

functions.[function_name].name

The name that is used in build logs to display the name of the function. For example, a function with the display name Say Hi!:

functions:
  greetings:
    name: Say Hi!

functions.[function_name].inputs

Input values are provided to a function.

inputs[].name

The name of the input value. It is used as an identifier to access the input value such as in bash command interpolation.

functions:
  greetings:
    name: Say Hi!
    inputs:
      - name: name
        default_value: Hello world
    command: echo "${ inputs.name }!"

inputs[].required

Boolean to indicate if the input value is required or not. For example, a function does not have a required value:

functions:
  greetings:
    name: Say Hi!
    inputs:
      - name: name
        required: false

inputs[].type

The type of the input value. It can be either string, num or json.

Input values set in the function call as well as default_value and allowed_values for the function are validated against the type.

The default input type is string.

For example, a function has an input value of type string:

functions:
  greetings:
    name: Say Hi!
    inputs:
      - name: name
        type: string
      - name: age
        type: num
      - name: other_data
        type: json

inputs[].default_value

You can use default_value to provide one default input. For example, a function has a default value of Hello world:

functions:
  greetings:
    name: Say Hi!
    inputs:
      - name: name
        default_value: Hello world

inputs[].allowed_values

You can use allowed_values to provide multiple values in an array. For example, a function has multiple allowed values:

functions:
  greetings:
    name: Say Hi!
    inputs:
      - name: name
        default_value: Hello world
        allowed_values: [Hi, Hello, Hey]
        type: string

Multiple input values

Multiple input values can be provided to a function.

functions:
  greetings:
    name: Say Hi!
    inputs:
      - name: name
        default_value: Expo
      - name: greeting
        default_value: Hi
        allowed_values: [Hi, Hello]
    command: echo "${ inputs.greeting }, ${ inputs.name }!"

functions.[function_name].outputs

An output value is expected from a function. For example, a function has an output value of Hello world:

functions:
  greetings:
    name: Say Hi!
    outputs: [value]
    command: set-output value "Hello world"

outputs[].name

The name of the output value. It is used as an identifier to access the output value in another step:

functions:
  greetings:
    name: Say Hi!
    outputs:
      - name: name

outputs[].required

Boolean to indicate if the output value is required or not. For example, a function does not have a required output value:

functions:
  greetings:
    name: Say Hi!
    outputs:
      - name: value
        required: false

functions.[function_name].command

Used to define the command to run when a function is executed, if you wish the function to be a simple shell script. Each function is required to define either a command or a path to JS/TS module implementing the function. For example, the command echo "Hello world" is used to print a message:

functions:
  greetings:
    name: Say Hi!
    command: echo "Hi!"

functions.[function_name].path

Used to define the path to a JavaScript/TypeScript module implementing the function. Each function is required to define either a command or a path property. For example, the path ./greetings is used to execute a greetings function declared in the greetings module:

functions:
  greetings:
    name: Say Hi!
    path: ./greetings

Learn more about building and using custom TypeScript/JavaScript functions here.

functions.[function_name].shell

Used to define the default executable shell for a step where a function is executed. For example, the step's shell is set to /bin/sh:

functions:
  greetings:
    name: Say Hi!
    shell: /bin/sh
    command: echo "Hi!"

functions.[function_name].supported_platforms

Used to define the supported platforms for a function. Defaults to all platforms. Allowed platforms: darwin, linux.

For example, the function's supported platform is darwin (macOS):

functions:
  greetings:
    name: Say Hi!
    supported_platforms: [darwin]
    command: echo "Hi!"

import

A config file path list used to import functions from other config files. Imported files cannot have the build section.

For example, the following workflow imports two files and calls two imported functions - say_hi and say_bye.

workflow.yml
import:
  - common-functions.yml
  - another-file.yml

build:
  steps:
    - say_hi
    - say_bye
common-functions.yml
functions:
  say_hi:
    name: Say Hi!
    command: echo "Hi!"
another-file.yml
functions:
  say_bye:
    name: Say bye :(
    command: echo "Bye!"

Functions

Built-in EAS functions

EAS provides a set of built-in reusable functions that you can use in a workflow without defining the function definition.

Tip: Any function that is built-in and provided by EAS must start with the eas/ prefix.

eas/build

The all-in-one function that encapsulates the entire EAS Build build process. It resolves the best build workflow configuration based on your build profile's settings from eas.json.

It's ideal for people who just want to have the build done without worrying about altering and configuring the build process manually. It can be a great starting point for your custom build configuration if you are interested in using other custom steps before or after the build process and you don't want to change the build process itself.

example.yml
build:
  name: Run a build using a single command
  steps:
    - eas/build

To have more control over the build process and customize it as per your requirements, see the following custom functions and steps that run in the background by eas/build. They are executed as a build process based on your build profile's configuration.

Android

When a build configuration is using withoutCredentials:

When a build configuration uses credentials (for both internal and store distribution builds):

iOS

When a build configuration is using withoutCredentials or simulator:

When a build configuration uses credentials (for both internal and store distribution builds):

You can replace the eas/build command call by using these steps in your YAML configuration file:

ios-simulator-build.yml

View the steps executed behind the scenes by the `eas/build` function for an iOS simulator build in our example repository.

ios-credentials-build.yml

View the steps executed behind the scenes by the `eas/build` function for an iOS build with credentials in our example repository.

android-build-without-credentials.yml

View the steps executed behind the scenes by the `eas/build` function for an Android build without credentials in our example repository.

android-build-with-credentials.yml

View the steps executed behind the scenes by the `eas/build` function for an Android build with credentials in our example repository.

Known limitations
  • This function doesn't configure legacy classic updates. If you are using classic updates, migrate to EAS Update before using this function.
  • It doesn't accept any inputs, and the resolved build process will be configured based on your build profile from eas.json.
  • The build process produced by eas/build is not configurable and you can't customize it. If you need to customize the build process, use the subset of functions and steps that are executed behind the scenes by this function and configure them manually in the YAML configuration file, as shown in the examples above.

eas/maestro_test

All-in-one function that installs Maestro, prepares a testing environment (Android Emulator or iOS Simulator), and tests the app.

InputDescription
flow_pathstring Path (or multiple paths, each in a separate line) to Maestro flows to run.
build-and-test.yml
build:
  name: Build and test
  steps:
    - eas/build
    - eas/maestro_test:
        inputs:
          flow_path: |
            maestro/sign_in.yaml
            maestro/create_post.yaml
            maestro/sign_out.yaml

Behind the scenes, it uses:

We have observed that Maestro tests often time out if run on images with Xcode 15.0 or 15.2. Xcode 15.1 and Xcode 14.3.1 seem to be unaffected.

If you need to customize the Maestro version, run a specific Android Emulator or iOS Simulator, or upload multiple build artifacts you will need to write this series of steps yourself.

An example Android workflow with eas/mastro_test expanded
build-and-test-android-expanded.yml
build:
  name: Build and test (Android, expanded)
  steps:
    - eas/build
    - eas/install_maestro
    - eas/start_android_emulator:
        inputs:
          system_package_name: system-images;android-34;default;x86_64
    - run:
        command: |
          # shopt -s globstar is necessary to add /**/ support
          shopt -s globstar
          # shopt -s nullglob is necessary not to try to install
          # SEARCH_PATH literally if there are no matching files.
          shopt -s nullglob

          SEARCH_PATH="android/app/build/outputs/**/*.apk"
          FILES_FOUND=false

          for APP_PATH in $SEARCH_PATH; do
            FILES_FOUND=true
            echo "Installing \\"$APP_PATH\\""
            adb install "$APP_PATH"
          done

          if ! $FILES_FOUND; then
            echo "No files found matching \\"$SEARCH_PATH\\". Are you sure you've built an Emulator app?"
            exit 1
          fi
    - run:
        command: |
          maestro test maestro/flow.yaml
    - eas/upload_artifact:
        name: Upload test artifact
        if: ${ always() }
        inputs:
          type: build-artifact
          path: ${ eas.env.HOME }/.maestro/tests

An example iOS workflow with eas/mastro_test expanded
build-and-test-ios-expanded.yml
build:
name: Build and test (iOS, expanded)
steps:
- eas/build
- eas/install_maestro
- eas/start_ios_simulator
- run:
    command: |
      # shopt -s nullglob is necessary not to try to install
      # SEARCH_PATH literally if there are no matching files.
      shopt -s nullglob

      SEARCH_PATH="ios/build/Build/Products/*simulator/*.app"
      FILES_FOUND=false

      for APP_PATH in $SEARCH_PATH; do
        FILES_FOUND=true
        echo "Installing \\"$APP_PATH\\""
        xcrun simctl install booted "$APP_PATH"
      done

      if ! $FILES_FOUND; then
        echo "No files found matching \\"$SEARCH_PATH\\". Are you sure you've built a Simulator app?"
        exit 1
      fi
- run:
    command: |
      maestro test maestro/flow.yaml
- eas/upload_artifact:
    name: Upload test artifact
    if: ${ always() }
    inputs:
      type: build-artifact
      path: ${ eas.env.HOME }/.maestro/tests
eas/maestro_test source code

View the source code for the eas/maestro_test function on GitHub.

eas/checkout

Checks out you project source files.

For example, a workflow with the following steps will check out the project and list the files in the assets directory:

upload.yml
build:
  name: List files
  steps:
    - eas/checkout
    - run:
        name: List assets
        run: ls assets
eas/checkout source code

View the source code for the eas/checkout function on GitHub.

eas/use_npm_token

Configures node package managers (npm, pnpm, or Yarn) for use with private packages, published either to npm or private registry. Set NPM_TOKEN in your project's secrets, and this function will configure the build environment by creating .npmrc with the token.

example.yml
build:
  name: Install private npm modules
  steps:
    - eas/checkout
    - eas/use_npm_token
    - run:
        name: Install dependencies
        run: npm install # <---- Can now install private packages
eas/use_npm_token source code

View the source code for the eas/use_npm_token function on GitHub.

eas/install_node_modules

Installs node modules using the package manager (npm, pnpm, or Yarn) detected based on your project. Works with monorepos.

example.yml
build:
  name: Install node modules
  steps:
    - eas/checkout
    - eas/install_node_modules
eas/install_node_modules source code

View the source code for the eas/install_node_modules function on GitHub.

eas/get_credentials_for_build_triggered_by_github_integration

Resolves the credentials for a build triggered by our GitHub integration. Call this function if you are using the GitHub integration and your custom build needs to use credentials.

This is a no-op if the build was not triggered by the GitHub integration. This function is automatically executed by eas/build function group.

example.yml
build:
  name: Example Android config for a build triggered by GitHub integration
  steps:
    - eas/checkout
    - eas/use_npm_token
    - eas/install_node_modules
    - eas/get_credentials_for_build_triggered_by_github_integration
    - eas/configure_eas_update:
        inputs:
          throw_if_not_configured: false
    - eas/inject_android_credentials
    - eas/configure_android_version
    - eas/run_gradle
    - eas/find_and_upload_build_artifacts
eas/get_credentials_for_build_triggered_by_github_integration source code

View the source code for the eas/get_credentials_for_build_triggered_by_github_integration function on GitHub.

eas/resolve_apple_team_id_from_credentials

This function is only available for iOS builds

Resolves the Apple team ID value based on build credentials provided in the inputs.credentials. The resolved Apple team ID is stored in the outputs.apple_team_id output value.

example.yml
build:
  name: Run prebuild script
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Resolve Apple team ID from credentials.
inputs.credentialsjson Optional input defining the app credentials for your iOS build. Defaults to ${ eas.job.secrets.buildCredentials }. Needs to comply to ${ eas.job.secrets.buildCredentials } schema for iOS.
eas/resolve_apple_team_id_from_credentials source code

View the source code for the eas/resolve_apple_team_id_from_credentials function on GitHub.

eas/prebuild

Runs the expo prebuild command using the package manager (npm, pnpm, or Yarn) detected based on your project with the command best suited for your build type and build environment.

example.yml
build:
  name: Run prebuild script
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
example.yml
build:
  name: Run prebuild script
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Prebuild.
inputs.cleanboolean Optional input defining whether the function should use --clean flag when running the command. Defaults to false
inputs.apple_team_idboolean Optional input defining Apple team ID which should be used when doing prebuild. It should be specified for iOS builds using credentials.
eas/prebuild source code

View the source code for the eas/resolve_apple_team_id_from_credentials function on GitHub.

eas/configure_eas_update

To use this function you need to have EAS Update configured for your project

Configures runtime version and release channel for your build.

example.yml
build:
  name: Configure EAS Update
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
example.yml
build:
  name: Configure EAS Update
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update:
        inputs:
          runtime_version: 1.0.0
          channel: mychannel
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Configure EAS Update.
inputs.runtime_versionstring Optional input defining runtime version which should be configured for the build. Defaults to ${ eas.job.version.runtimeVersion } or natively defined runtime version.
inputs.channelstring Optional input defining channel which should be configured for the build. Defaults to ${ eas.job.updates.channel }.
eas/configure_eas_update source code

View the source code for the eas/configure_eas_update function on GitHub.

eas/inject_android_credentials

This function is only available for Android builds

Configures Android keystore with credentials on the builder and injects app signing config using these credentials into gradle config.

example.yml
build:
  name: Android credentials
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/inject_android_credentials
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Inject Android credentials.
inputs.credentialsjson Optional input defining the app credentials for your Android build. Defaults to ${ eas.job.secrets.buildCredentials }. Needs to comply to ${ eas.job.secrets.buildCredentials } schema for Android.
eas/inject_android_credentials source code

View the source code for the eas/inject_android_credentials function on GitHub.

eas/configure_ios_credentials

This function is only available for iOS builds

Configures iOS credentials on the builder. Modifies the configuration of the Xcode project by assigning provisioning profiles to the targets.

example.yml
build:
  name: iOS credentials
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
    - eas/configure_ios_credentials
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Configure iOS credentials.
inputs.build_configurationstring Optional input defining the Xcode project's Build Configuration. Defaults to ${ eas.job.buildConfiguration } or if not specified is resolved to Debug for development client or Release for other builds.
inputs.credentialsjson Optional input defining the app credentials for your iOS build. Defaults to ${ eas.job.secrets.buildCredentials }. Needs to comply to ${ eas.job.secrets.buildCredentials } schema for iOS.
eas/configure_ios_credentials source code

View the source code for the eas/configure_ios_credentials function on GitHub.

eas/configure_android_version

This function is only available for Android builds

Configures the version of your Android app. It's used to set a version when using remote app version management.

It's not mandatory to use this function, if it's not used the version from native code generated during the prebuild phase will be used.

example.yml
build:
  name: Configure Android version
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
    - eas/inject_android_credentials
    - eas/configure_android_version
example.yml
build:
  name: Configure Android version
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
    - eas/inject_android_credentials
    - eas/configure_android_version:
        inputs:
          version_code: '123'
          version_name: '1.0.0'
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Configure Android version.
inputs.version_codestring Optional input defining versionCode of your Android build. Defaults to ${ eas.job.version.versionCode }
inputs.version_namestring Optional input defining versionName of your Android build. Defaults to ${ eas.job.version.versionName }.
eas/configure_android_version source code

View the source code for the eas/configure_android_version function on GitHub.

eas/configure_ios_version

This function is only available for iOS builds

Configures the version of your iOS app. It's used to set a version when using remote app version management.

It's not mandatory to use this function, if it's not used the version from native code generated during the prebuild phase will be used.

example.yml
build:
  name: Configure iOS version
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
    - eas/configure_eas_update
    - eas/configure_ios_credentials
    - eas/configure_ios_version
example.yml
build:
  name: Configure iOS version
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
    - eas/configure_eas_update
    - eas/configure_ios_credentials
    - eas/configure_ios_version:
        inputs:
          build_number: '123'
          app_version: '1.0.0'
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Configure iOS version.
inputs.build_numberstring Optional input defining the build number (CFBundleVersion) of your iOS build. Defaults to ${ eas.job.version.buildNumber }
inputs.app_versionstring Optional input defining the app version (CFBundleShortVersionString) of your iOS build. Defaults to ${ eas.job.version.appVersion }.
inputs.build_configurationstring Optional input defining the Xcode project's Build Configuration. Defaults to ${ eas.job.buildConfiguration } or if not specified is resolved to Debug for development client or Release for other builds.
inputs.credentialsjson Optional input defining the app credentials for your iOS build. Defaults to ${ eas.job.secrets.buildCredentials }. Needs to comply to ${ eas.job.secrets.buildCredentials } schema for iOS.
eas/configure_ios_version source code

View the source code for the eas/configure_ios_version function on GitHub.

eas/run_gradle

This function is only available for Android builds

Runs a Gradle command to build an Android app.

example.yml
build:
  name: Build Android app
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
    - eas/inject_android_credentials
    - eas/run_gradle
example.yml
build:
  name: Build Android app
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
    - eas/inject_android_credentials
    - eas/run_gradle:
        inputs:
          command: :app:bundleRelease
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Run gradle.
inputs.commandstring Optional input defining the Gradle command to run to build the Android app. If not specified it is resolved based on the build configuration and contents of the ${ eas.job } object.
eas/run_gradle source code

View the source code for the eas/run_gradle function on GitHub.

eas/generate_gymfile_from_template

This function is only available for iOS builds

Generates a Gymfile used to build the iOS app using Fastlane from a template.

Default template used when credentials are passed:

Gymfile
suppress_xcode_output(true)
clean(<%- CLEAN %>)

scheme("<%- SCHEME %>")
<% if (BUILD_CONFIGURATION) { %>
configuration("<%- BUILD_CONFIGURATION %>")
<% } %>

export_options({
method: "<%- EXPORT_METHOD %>",
provisioningProfiles: {<% _.forEach(PROFILES, function(profile) { %>
    "<%- profile.BUNDLE_ID %>" => "<%- profile.UUID %>",<% }); %>
}<% if (ICLOUD_CONTAINER_ENVIRONMENT) { %>,
iCloudContainerEnvironment: "<%- ICLOUD_CONTAINER_ENVIRONMENT %>"
<% } %>
})

export_xcargs "OTHER_CODE_SIGN_FLAGS=\\"--keychain <%- KEYCHAIN_PATH %>\\""

disable_xcpretty(true)
buildlog_path("<%- LOGS_DIRECTORY %>")

output_directory("<%- OUTPUT_DIRECTORY %>")

Default template used when credentials are not passed (simulator build):

Gymfile
suppress_xcode_output(true)
clean(<%- CLEAN %>)

scheme("<%- SCHEME %>")
<% if (BUILD_CONFIGURATION) { %>
configuration("<%- BUILD_CONFIGURATION %>")
<% } %>

derived_data_path("<%- DERIVED_DATA_PATH %>")
skip_package_ipa(true)
skip_archive(true)
destination("<%- SCHEME_SIMULATOR_DESTINATION %>")

disable_xcpretty(true)
buildlog_path("<%- LOGS_DIRECTORY %>")

CLEAN, SCHEME, BUILD_CONFIGURATION, EXPORT_METHOD, PROFILES, ICLOUD_CONTAINER_ENVIRONMENT, KEYCHAIN_PATH, LOGS_DIRECTORY, OUTPUT_DIRECTORY, DERIVED_DATA_PATHand SCHEME_SIMULATOR_DESTINATION values are provided to the template based on the inputs and default internal configuration of EAS Build.

example.yml
build:
  name: Generate Gymfile template
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
    - eas/configure_eas_update
    - eas/configure_ios_credentials
    - eas/generate_gymfile_template:
        inputs:
          credentials: ${ eas.job.secrets.buildCredentials }
example.yml
build:
  name: Generate Gymfile template
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/generate_gymfile_template

However, you can also use other custom properties in the template, by specifying your custom template in inputs.template and providing the values for the custom properties in the inputs.extra object.

example.yml
build:
  name: Generate Gymfile template
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
    - eas/configure_eas_update
    - eas/configure_ios_credentials
    - eas/generate_gymfile_template:
        inputs:
          credentials: ${ eas.job.secrets.buildCredentials }
          extra:
            MY_VALUE: my value
          template: |
            suppress_xcode_output(true)
            clean(<%- CLEAN %>)

            scheme("<%- SCHEME %>")
            <% if (BUILD_CONFIGURATION) { %>
            configuration("<%- BUILD_CONFIGURATION %>")
            <% } %>

            export_options({
            method: "<%- EXPORT_METHOD %>",
            provisioningProfiles: {<% _.forEach(PROFILES, function(profile) { %>
                "<%- profile.BUNDLE_ID %>" => "<%- profile.UUID %>",<% }); %>
            }<% if (ICLOUD_CONTAINER_ENVIRONMENT) { %>,
            iCloudContainerEnvironment: "<%- ICLOUD_CONTAINER_ENVIRONMENT %>"
            <% } %>
            })

            export_xcargs "OTHER_CODE_SIGN_FLAGS=\"--keychain <%- KEYCHAIN_PATH %>\""

            disable_xcpretty(true)
            buildlog_path("<%- LOGS_DIRECTORY %>")

            output_directory("<%- OUTPUT_DIRECTORY %>")

            sth_else("<%- MY_VALUE %>")
PropertyDescription
nameThe name of the step in the reusable function that shows in the build logs. Defaults to Generate Gymfile from template.
inputs.templatestring Optional input defining the Gymfile template which should be used. If not specified one out of two default templates will be used depending on whether the inputs.credentials value is specified.
inputs.credentialsjson Optional input defining the app credentials for your iOS build. If specified KEYCHAIN_PATH, EXPORT_METHOD, and PROFILES values will be provided to the template.
inputs.build_configurationstring Optional input defining the Xcode project's Build Configuration. Defaults to ${ eas.job.buildConfiguration } or if not specified is resolved to Debug for development client or Release for other builds. Corresponds to the BUILD_CONFIGURATION template value.
inputs.schemestring Optional input defining the Xcode project's scheme which should be used for the build. Defaults to ${ eas.job.scheme } or if not specified is resolved to the first scheme found in the Xcode project. Corresponds to the SCHEME template value.
inputs.cleanboolean Optional input defining whether the Xcode project should be cleaned before the build. Defaults to true. Corresponds to CLEAN template variable.
inputs.extrajson Optional input defining extra values which should be provided to the template.
eas/generate_gymfile_from_template source code

View the source code for the eas/generate_gymfile_template function on GitHub.

eas/run_fastlane

This function is only available for iOS builds

Runs fastlane gym command against the Gymfile located in the ios project directory to build the iOS app.

example.yml
build:
  name: Build iOS app
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
    - eas/configure_eas_update
    - eas/configure_ios_credentials
    - eas/generate_gymfile_template:
        inputs:
          credentials: ${ eas.job.secrets.buildCredentials }
    - eas/run_fastlane
example.yml
build:
  name: Build iOS app
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
    - eas/generate_gymfile_template
    - eas/run_fastlane
eas/run_fastlane source code

View the source code for the eas/run_fastlane function on GitHub.

eas/find_and_upload_build_artifacts

You can currently upload each artifact type only once per workflow.
If you use eas/find_and_upload_build_artifacts while having buildArtifactPaths configured in your build profile and the step finds and uploads some build artifacts, any following eas/upload_artifact step will fail.
To solve this, for now, we recommend removing buildArtifactPaths from custom build's profiles and uploading artifacts manually with eas/upload_artifact in the YAML workflow if you need to call it there.

Automatically finds and uploads application archive, additional build artifacts, and Xcode logs from the default locations and using the buildArtifactPaths configuration. Uploads found artifacts to the EAS servers.

example.yml
build:
  name: Build iOS app
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials
    - eas/prebuild:
        inputs:
          clean: false
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }
    - eas/configure_eas_update
    - eas/configure_ios_credentials
    - eas/generate_gymfile_template:
        inputs:
          credentials: ${ eas.job.secrets.buildCredentials }
    - eas/run_fastlane
    - eas/find_and_upload_build_artifacts
example.yml
build:
  name: Build iOS app
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
    - eas/generate_gymfile_template
    - eas/run_fastlane
    - eas/find_and_upload_build_artifacts
example.yml
build:
  name: Build Android app
  steps:
    - eas/checkout
    - eas/install_node_modules
    - eas/prebuild
    - eas/configure_eas_update
    - eas/inject_android_credentials
    - eas/run_gradle
    - eas/find_and_upload_build_artifacts
eas/find_and_upload_build_artifacts source code

View the source code for the eas/find_and_upload_build_artifacts function on GitHub.

eas/upload_artifact

Uploads build artifacts from provided paths.

You can currently upload each artifact type only once per workflow.
If you use eas/find_and_upload_build_artifacts while having buildArtifactPaths configured in your build profile and the step finds and uploads some build artifacts, any following eas/upload_artifact step will fail.
To solve this, for now, we recommend removing buildArtifactPaths from custom build's profiles and uploading artifacts manually with eas/upload_artifact in the YAML workflow if you need to call it there.

For example, a workflow with the following steps will upload an artifact to the EAS servers:

upload.yml
build:
  name: Upload artifacts
  steps:
    - eas/checkout
    # - ...
    - eas/upload_artifact:
        name: Upload application archive
        inputs:
          path: fixtures/app-debug.apk
    - eas/upload_artifact:
        name: Upload artifacts
        inputs:
          type: build-artifact
          path: |
            assets/*.jpg
            assets/*.png
InputDescription
pathstring Required. Path or newline-delimited list of paths to the artifacts to upload to EAS servers. You can use * wildcard and other glob patterns that fast-glob supports.
typestring The type of artifact that is uploaded to the EAS servers. Allowed values are application-archive and build-artifact. Defaults to application-archive.
eas/upload_artifact source code

View the source code for the eas/upload_artifact function on GitHub.

eas/install_maestro

Makes sure Maestro, the mobile UI testing framework, is installed along with all its dependencies.

build-and-test.yml
build:
  name: Build and test
  steps:
    - eas/build
    # ... simulator/emulator setup
    - eas/install_maestro:
        inputs:
          maestro_version: 1.35.0
    - run:
        command: maestro test flows/signin.yml
    - eas/upload_artifact:
        name: Upload Maestro artifacts
        inputs:
          type: build-artifact
          path: ${ eas.env.HOME }/.maestro/tests
InputDescription
maestro_versionstring Maestro version to install (for example, 1.35.0). If not provided, install_maestro will install the latest version.
eas/install_maestro source code

View the source code for the eas/install_maestro function on GitHub.

eas/start_android_emulator

Starts an Android Emulator you can use to test your apps on. Only available when running a build for Android.

build-and-test.yml
build:
  name: Build and test
  steps:
    - eas/build
    - eas/start_android_emulator:
        inputs:
          system_image_package: system-images;android-30;default;x86_64
    # ... Maestro setup and tests
InputDescription
device_namestring Name for the created device. You can customize it if starting multiple emulators.
system_image_packagestring Android package path to use for the emulator. For example, system-images;android-30;default;x86_64.
To get a list of available system images, run sdkmanager --list on a local computer. VMs run on x86_64 architecture, so always choose x86_64 package variants. The sdkmanager tool comes from Android SDK command-line tools.
eas/start_android_emulator source code

View the source code for the eas/start_android_emulator function on GitHub.

eas/start_ios_simulator

Starts an iOS Simulator you can use to test your apps on. Only available when running a build for iOS.

build-and-test.yml
build:
  name: Build and test
  steps:
    - eas/build
    - eas/start_ios_simulator
    # ... Maestro setup and tests
InputDescription
device_identifierstring Name or UDID of the Simulator you want to start. Examples include iPhone [XY] Pro, AEF997BB-222C-4379-89BA-D21070B1D787.
Note: Available Simulators are different for every image. If you change the image, the Simulator for a given name may become unavailable. For instance, an Xcode 14 image will have iPhone 14 Simulators, while an Xcode 15 image will have iPhone 15 simulators. In general, we encourage not providing this input. See runner images for more information.
eas/start_ios_simulator source code

View the source code for the eas/start_ios_simulator function on GitHub.

eas/send_slack_message

Sends a specified message to a configured Slack webhook URL, which then posts it in the related Slack channel.

send-slack-message.yml
build:
  name: Slack your team from custom build
  steps:
    - eas/send_slack_message:
        name: Send Slack message to a given webhook URL
        inputs:
          message: 'This is a message to plain input URL'
          slack_hook_url: 'https://hooks.slack.com/services/[rest_of_hook_url]'
    - eas/send_slack_message:
        name: Send Slack message to a default webhook URL from SLACK_HOOK_URL secret
        inputs:
          message: 'This is a test message to default URL from SLACK_HOOK_URL secret'
    - eas/send_slack_message:
        name: Send Slack message to a webhook URL from specified secret
        inputs:
          message: 'This is a test message to a URL from specified secret'
          slack_hook_url: ${ eas.env.ANOTHER_SLACK_HOOK_URL }

    - eas/build
    - eas/send_slack_message:
        if: ${ always() }
        name: Send Slack message when the build finishes (Android)
        inputs:
          message: |
            This is a test message when Android build finishes
            Status: `${ steps.run_gradle.status_text }`
            Link: `${ eas.job.expoBuildUrl }`
    - eas/send_slack_message:
        if: ${ always() }
        name: Send Slack message when the build finishes (iOS)
        inputs:
          message: |
            This is a test message when iOS build finishes
            Status: `${ steps.run_fastlane.status_text }`
            Link: `${ eas.job.expoBuildUrl }`
    - eas/send_slack_message:
        if: ${ failure() }
        name: Send Slack message when the build fails (Android)
        inputs:
          message: |
            This is a test message when Android build fails
            Error: `${ steps.run_gradle.error_text }`
    - eas/send_slack_message:
        if: ${ failure() }
        name: Send Slack message when the build fails (iOS)
        inputs:
          message: |
            This is a test message when iOS build fails
            Error: `${ steps.run_fastlane.error_text }`
    - eas/send_slack_message:
        if: ${ success() }
        name: Send Slack message when the build succeeds
        inputs:
          message: |
            This is a test message when build succeeds
InputDescription
messagestring The text of the message you want to send. For example, 'This is the content of the message'.

Note: You can reference build job properties and use other steps outputs in the message for dynamic evaluation. For example, 'Build URL: ${ eas.job.expoBuildUrl }', Build finished with status: ${ steps.run_fastlane.status_text }, Build failed with error: ${ steps.run_gradle.error_text }.
slack_hook_urlstring The URL of the previously configured Slack webhook URL, which will post your message to the specified channel. You can provide the plain URL like slack_hook_url: 'https://hooks.slack.com/services/[rest_of_hook_url]', use EAS secrets like slack_hook_url: ${ eas.env.ANOTHER_SLACK_HOOK_URL }, or set the SLACK_HOOK_URL secret, which will serve as a default webhook URL (in this last case, there is no need to provide slack_hook_url input).
eas/send_slack_message source code

View the source code for the eas/send_slack_message function on GitHub.

Using built-in EAS functions to build an app

Using the built-in EAS functions you can recreate the default EAS Build workflow for different build types.

For example, to trigger a build that creates internal distribution build for Android and a simulator build for iOS you can use the following configuration:

eas.json
{
  %%placeholder-start%%... %%placeholder-end%%
  "build": {
    %%placeholder-start%%... %%placeholder-end%%
    "developmentBuild": {
      "distribution": "internal",
      "android": {
        "config": "development-build-android.yml"
      },
      "ios": {
        "simulator": true,
        "config": "development-build-ios.yml"
      }
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}
.eas/build/development-build-android.yml
build:
  name: Simple internal distribution Android build
  steps:
    - eas/checkout

    - eas/install_node_modules

    - eas/prebuild

    - eas/inject_android_credentials

    - eas/run_gradle

    - eas/find_and_upload_build_artifacts
.eas/build/development-build-ios.yml
build:
  name: Simple simulator iOS build
  steps:
    - eas/checkout

    - eas/install_node_modules

    - eas/prebuild

    - run:
        name: Install pods
        working_directory: ./ios
        command: pod install

    - eas/generate_gymfile_from_template

    - eas/run_fastlane

    - eas/find_and_upload_build_artifacts

To create a Google Play Store build for Android and an Apple App Store build for iOS you can use the following configuration:

eas.json
{
  %%placeholder-start%%... %%placeholder-end%%
  "build": {
    %%placeholder-start%%... %%placeholder-end%%
    "productionBuild": {
      "android": {
        "config": "production-build-android.yml"
      },
      "ios": {
        "config": "production-build-ios.yml"
      }
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}
.eas/build/production-build-android.yml
build:
  name: Customized Android Play Store build example
  steps:
    - eas/checkout

    - eas/install_node_modules

    - eas/prebuild

    - eas/inject_android_credentials

    - eas/run_gradle

    - eas/find_and_upload_build_artifacts
.eas/build/production-build-ios.yml
build:
  name: Customized iOS App Store build example
  steps:
    - eas/checkout

    - eas/install_node_modules

    - eas/resolve_apple_team_id_from_credentials:
        id: resolve_apple_team_id_from_credentials

    - eas/prebuild:
        inputs:
          apple_team_id: ${ steps.resolve_apple_team_id_from_credentials.apple_team_id }

    - run:
        name: Install pods
        working_directory: ./ios
        command: pod install

    - eas/configure_ios_credentials

    - eas/generate_gymfile_from_template:
        inputs:
          credentials: ${ eas.job.secrets.buildCredentials }

    - eas/run_fastlane

    - eas/find_and_upload_build_artifacts

Check out the example repository for more detailed examples:

Custom build example repository

A custom EAS Build example that includes examples for workflows such as setting up functions, using environment variables, uploading artifacts, and more.

Use a reusable function in a build

For example, a workflow with the following reusable function contains a single command to print a message that is echoed.

functions:
  greetings:
    - name: name
      default_value: Hello world
    inputs: [value]
    command: echo "${ inputs.name }, { inputs.value }"

The above function can be used in a build as follows:

build:
  name: Functions Demo
  steps:
    - greetings:
        inputs:
          value: Expo
Tip: build.steps can execute multiple reusable functions sequentially.

Override values in a build

You can override values for following properties:

  • working_directory
  • name
  • shell

For example, a reusable function called list_files:

functions:
  list_files:
    name: List files
    command: ls -la

When list_files is called in a workflow, it lists all files in the root directory of a project:

build:
  name: List files
  steps:
    - eas/checkout
    - list_files

You can use the working_directory property to override the behavior in the function call to list the files in a different directory by specifying the path to that directory:

build:
  name: List files
    steps:
      - eas/checkout
      - list_files:
          working_directory: /a/b/c