Environment variables in EAS

Learn basic concepts about using environment variables in EAS and how to manage them.

Environment variables in Expo describe how to use environment variables with the Expo framework and .env files to set environment variables that can be inlined in your JavaScript code. Expo CLI will substitute prefixed variables in your code (for example,process.env.EXPO_PUBLIC_VARNAME) with the corresponding environment variable values in .env files on your development machine.

Because EAS Build and Workflows jobs run on a remote server, .env files may not be available. For instance, if .env files are excluded from your project because they are listed in .gitignore or not committed to your local version control system. Additionally, you may want to use environment variables outside of your project code to customize your app binary at build time, like setting a bundle identifier or a private key for an error reporting service. To accommodate for those needs we have a separate (but compatible) mechanism for managing environment variables in EAS, which is focused on storing and managing environment variables on EAS' servers and synchronizing them for local development.

Project-wide environment variables

Project-wide environment variables are specific to a single EAS project. You can view and manage them by navigating to the Environment Variables page on your project. These environment variables are available to any jobs run on EAS' servers and updates for this project. They can also be pulled locally for development if their visibility setting allows it.

Account-wide environment variables

Account-wide environment variables are available across all of your projects in your EAS account. You can view and manage them by navigating to Environment Variables page on your account. They are available to jobs run on EAS' servers and updates, together with project-wide variables for a project. You can pull them locally or read outside of EAS servers if their visibility setting allows it.

Environments

Currently EAS supports three environments for environment variables: development, preview and production. Environments are independent sets of environment variables that can be used to customize your app in different contexts. For example, you might want to use different API keys for development and production, or different bundle identifiers for different App Store releases. Environments allows you to do so. Every EAS Build and Workflows job runs using environment variables from one of the available environments. You can also use environments for updates, allowing you to use the same set of environment variables for your build jobs. You can do this when publishing an update by providing the --environment flag.

Environment variables can be assigned to multiple environments and have the same value across all of them, or be created for a single environment, so that you can set a specific value for a single environment.

Visibility

There are three different visibility settings:

Always remember that anything that is included in your client side code should be considered public and readable to any individual that can run the application. Secret type environment variables are intended to be used to provide values to an EAS Build or Workflows job so that they may be used to alter how a job runs. For example: a good use case is setting an NPM_TOKEN to install private packages from npm, or a setting a Sentry API key to create a release and upload your source maps. Secrets do not provide any additional security for values that you end up embedding in your application itself.

File environment variables

In addition to setting strings as values, you can also upload files as the value of an environment variable.

One common use case of using file environment variable is passing a git ignored google-services.json configuration file to a build job. During the job run, the file will be created in a location outside of the project directory and the path to the file will be assigned to the environment variable (GOOGLE_SERVICES_JSON=/path/to/google-services.json). For example: you can then set android.googleServicesFile in your app config to the value of the GOOGLE_SERVICES_JSON environment variable to use this file when executing the build or Workflows job.

export default {
  %%placeholder-start%%...%%placeholder-end%%
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? '/local/path/to/google-services.json',
    %%placeholder-start%%...%%placeholder-end%%
  },
};

Recommended workflow

One possible way to efficiently work with environment variables in your EAS projects is to:

Use correct visibility settings

Make sure to set the visibility of your environment variables to the appropriate level. Avoid setting excessive secret visibility to EXPO_PUBLIC_ variables that are used in your app's JavaScript code or are used to resolve your app's configuration. Be aware that environment variables with secret visibility are not readable outside of EAS servers, and can't be pulled locally for development or to bundle your app's JavaScript code for updates.

Add .env files to .gitignore

To avoid confusing overrides during cloud jobs and leaking sensitive information, add .env files to your .gitignore file.

Use the --environment flag with eas update

When publishing updates, use the --environment flag with the eas update command to ensure that the same environment variables are used for your updates as your build jobs. When the --environment flag is provided, eas update will use the environment variables on EAS' servers for the update job and won't use the .env files present in your project often used for local development.

Sync the environment variables for local development using eas env:pull

You can use the eas env:pull command to pull environment variables from EAS servers to your local .env file for development. The ideal environment that can be used for this purpose is the development environment, as it's the default environment used for development builds.

Explicitly specify the environment for your builds

Explicitly set the environment value in eas.json for your build profiles to ensure that the correct environment variables are always used for your build jobs and you have full control over this process.

Tutorial

See the Using EAS environment variables for a step-by-step guide on how to use EAS environment variables in a real world scenario.

Differences between handling environment variables in EAS CLI and Expo CLI

One of the differences between using environment variables with the Expo framework and EAS is that EAS CLI itself does not support loading .env files to set environment variables when resolving the expo config. Instead, it's recommended to use the EAS environment variables management system with EAS CLI commands to set environment variables for your build jobs and updates to avoid confusion, and ensure that exactly the same environment variables are used both for:

• Local app config resolution, done by EAS CLI when preparing the expo config
• Remote jobs happening on EAS servers, which often don't have access to your local .env files that are git ignored

Using eas update is the one exception to this rule. By default, for backward compatibility reasons, it uses .env files present in your project directory to set environment variables for the update job, the same way Expo CLI does (it executes the npx expo export command under the hood). To ensure that you can use the same environment variables in your updates as your build jobs, you can use the --environment flag with the eas update command to force it to use only the environment variables set on the EAS' servers instead of the .env files present in your project directory. It will ignore environment variables from .env.

EAS Build and Workflows job runs

Setting the environment for your builds

To set the environment for your EAS Build jobs, you can use the environment option in eas.json and set it to one of the available environments: development, preview or production.

{
  "build": {
    "production": {
      "environment": "production"
    },
    "preview": {
      "environment": "preview"
    },
    "development": {
      "environment": "development"
    },
    "my-profile": {
      "environment": "production"
    }
  }
}

If you don't set the environment option, we will set the environment automatically based on your build's configuration:

• production: for app store build
• development: for development client build
• preview: for other configurations

This resolution logic is only available for EAS CLI in version 13.3.0 and higher. For older CLI versions, we always assume the production environment for all builds.

Built-in environment variables

The following environment variables are additonal system environment variables exposed to each job and can be used within any build step. They are not a part of any project environment and are not available when evaluating app.config.ts locally:

• CI=1: indicates this is a CI environment
• EAS_BUILD=true: indicates this is an EAS Build environment
• EAS_BUILD_PLATFORM: either android or ios
• EAS_BUILD_RUNNER: either eas-build for EAS Build cloud builds or local-build-plugin for local builds
• EAS_BUILD_ID: the build ID, for example, f51831f0-ea30-406a-8c5f-f8e1cc57d39c
• EAS_BUILD_PROFILE: the name of the build profile from eas.json, for example, production
• EAS_BUILD_GIT_COMMIT_HASH: the hash of the Git commit, for example, 88f28ab5ea39108ade978de2d0d1adeedf0ece76
• EAS_BUILD_NPM_CACHE_URL: the URL of npm cache (learn more)
• EAS_BUILD_MAVEN_CACHE_URL: the URL of Maven cache (learn more)
• EAS_BUILD_COCOAPODS_CACHE_URL: the URL of CocoaPods cache (learn more)
• EAS_BUILD_USERNAME: the username of the user initiating the build (it's undefined for bot users)
• EAS_BUILD_WORKINGDIR: the remote directory path with your project

Dynamically setting environment variables during the job execution

You can also set environment variables dynamically during the job execution using the set-env command. The set-env executable is available in the PATH on EAS Build workers, and can be used to set environment variables that will be visible in the next build phases.

For example, you can add the following in one of the EAS Build hooks and the environment variable EXAMPLE_ENV will be available until the end of the build job.

Accessing environment variables

After creating an environment variable, you can read it on subsequent EAS Build jobs with process.env.VARIABLE_NAME from Node.js or in shell scripts as $VARIABLE_NAME.

FAQ

Can I just set my environment variables on a CI provider when triggering the build using eas build command?

Environment variables must be defined on EAS servers to be made available to EAS Build builders. If you are triggering builds from CI the same rule applies, and you should be careful to not confuse setting environment variables on GitHub Actions (or the provider of your choice) with setting environment variables and secrets on EAS servers.

How do environment variables work for my development builds?

Environment variables set in your build profile that impact app.config.js will be used for configuring the development build. When you run npx expo start to load your app inside of your development build, only environment variables that are available on your development machine will be used.

EAS Update

Using .env files with EAS Update

When the --environment flag is not provided, eas update will use the .env files present in your project directory for the update job and won't use the environment variables set on the EAS servers.

Environment variables in Expo describes how to use .env files to set and use environment variables within your JavaScript code. Expo CLI will substitute prefixed variables in your code (for example,process.env.EXPO_PUBLIC_VARNAME) with the corresponding environment variable values in .env files present on your development machine.

When you run eas update, all .env files will be evaluated when your JavaScript is bundled. Any EXPO_PUBLIC_ variables in your application code will be replaced inline with the corresponding values from your .env files that are present on the machine from which the update is published, whether that is your local machine or your CI/CD server.

When using .env files with EAS Update, EXPO_PUBLIC_ variables in .env files will only be used when bundling your app's JavaScript. They will not be available when evaluating app.config.js.

Using the --environment flag with EAS Update

When the --environment flag is provided, eas update will use the environment variables on EAS' servers for and won't use the .env files present in your project. Expo CLI will substitute prefixed variables in your code (for example,process.env.EXPO_PUBLIC_VARNAME) with the corresponding plain text and sensitive environment variable values set on EAS' servers for the environment specified with the --environment flag.

Any EXPO_PUBLIC_ variables in your application code will be replaced inline with the corresponding values from your EAS environment whether that is your local machine or your CI/CD server.

We recommend using the --environment flag to ensure the same environment variables are used both for your update and build jobs.

Managing environment variables

Using Expo website

The easiest way to create, read, update, export and delete environment variables is to use the Expo website. Navigate to the Environment Variables page on your project or Environment Variables page on your account to manage your environment variables.

Using EAS CLI

To manage environment variables using EAS CLI, you can use the eas env:create, eas env:update, eas env:list, and eas env:delete commands.

You can additionally use eas env:pull command to pull environment variables from EAS servers to your local .env file for development.

See the EAS CLI command reference for more detailed information about these commands.

Limitations

Environment variable value size is limited to 32 KiB for both string and file environment variables.

You can create up to 100 account-wide environment variables for each Expo account and 100 project-specific environment variables for each app