Environment variables and secrets in EAS Build

Learn how to use environment variables and secrets in an EAS Build.

Environment variables in Expo describes how to use .env files to set environment variables that can be inlined in your JavaScript code. The Expo CLI will substitute properly 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.

Because your EAS Build job runs on a remote server, these .env files might not be available. For instance, .env files are excluded from your uploaded project if 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 JavaScript code to customize your app binary at build time, such as setting a bundle identifier or a private key for an error reporting service. Therefore, EAS Build lets you set per-build-profile environment variables within eas.json as well as sensitive values that should not be committed to source control via EAS Secrets.

Setting plaintext environment variables in eas.json

For use in application code

If you set variables in a .env file for local development as described in the environment variables guide, you can set those same variables in a build profile in eas.json. For instance, you might set an API URL variable to a local backend server when developing locally, a test server for testing, and a production server for production builds.

In this case, your .env file might look like this:

EXPO_PUBLIC_API_URL=http://api.local

Add any applicable .env files to your .gitignore (and .easignore, if your project has one) file so they are not uploaded with your EAS Build job:

# ignores all .env files
.env*

Then you can set the same environment variable for each build profile in eas.json:

{
  "build": {
    "production": {
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api.production.com"
      }
    },
    "test": {
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api.test.com"
      }
    }
  }
}

Any reference to process.env.EXPO_PUBLIC_API_URL will be substituted for the applicable value depending on the environment.

EXPO_PUBLIC_ variable replacement is available in SDK 49 and higher.

For use by your Expo config

You can use environment variables in a dynamic config (app.config.js) to change how your app is built. For instance, you might want to change your app icon or short name for a test build.

Set the variable in your build profile:

{
  "build": {
    "test": {
      "env": {
        "APP_ICON": "./assets/icon-test.png",
        "APP_NAME": "My App (Test)"
      }
    }
  }
}

Then reference that variable in your app.config.js, providing fallbacks for local development:

module.exports = {
  // use the variable if it's defined, otherwise use the fallback
  icon: process.env.APP_ICON || './assets/icon.png',
  name: process.env.APP_NAME || 'My App',
};

All environment variables in your eas.json build profile are available when evaluating app.config.js. It's a good practice to only use the EXPO_PUBLIC_ prefix for variables used within your application code.

For use by other build steps

Any environment variables set in your eas.json build profile are also available to other build steps.

You can also set environment variables dynamically during the build process. 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.

Built-in environment variables

The following environment variables are exposed to each build job and can be used within any build step. They are not set when evaluating app.config.js 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

Using secrets in environment variables

To provide your build jobs with access to values that are too sensitive to include in your source code and Git repository, you can use "Secrets".

A secret is made up of a name and a value. The name can only contain alphanumeric characters and underscores. The value is limited to 32 KiB.

The value can be either a file or a string value. For a file, its contents are saved to a temporary file on EAS Build servers. The file path is available via the environment variable. For example, if you created a file secret named SECRET_FILE, EAS Build will create a file at /Users/expo/workingdir/environment-secrets/__UNIQUE_RANDOM_UUID__, and SECRET_FILE will be set to that path.

The secret values are encrypted at rest and in transit and are only decrypted in a secure environment by EAS servers.

You can create up to 100 account-wide secrets for each Expo account and 100 app-specific secrets for each app. Account-wide secrets will be exposed to every build environment across all of your apps. App-specific secrets only apply to the app they're defined for and will override any account-wide secrets with the same name.

You can manage secrets through the Expo website and EAS CLI.

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. EAS Secrets are intended to be used to provide values to an EAS Build job so that they may be used during the build process. Examples of correct usage include setting the NPM_TOKEN for installing private packages from npm, or a Sentry API key to create a release and upload your sourcemaps to their service. EAS Secrets do not provide any additional security for values that you end up embedding in your application itself, such as an AWS access key or other private keys.

Secrets on the Expo website

To create account-wide secrets, navigate to Secrets tab in your account's settings.

To create app-specific secrets, navigate to the Secrets tab in your project's dashboard.

Adding secrets with EAS CLI

To create a new secret, run eas secret:create:

To view any existing secrets for this project, run eas secret:list:

Importing secrets from a dotenv file

If you're using a .env file for storing your secrets locally, you can use the eas secret:push command to import all of them to EAS:

Beware that EAS CLI will fail if some of the secrets defined in the dotenv file already exist on the server. To force override those secrets, pass the --force flag to the command.

Doppler integration

You can use the eas secret:push command to integrate EAS with your Doppler project:

Accessing secrets in EAS Build

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

Common questions

Can EAS Build use .env files?

Environment variables defined in a .env file are only considered by the Expo CLI. Therefore, if you upload a .env file to EAS Build, it can be used to inline EXPO_PUBLIC_ variables into your application code.

However, the recommended practice is to use .env files in your local environment, while defining environment variables for EAS Build in eas.json. Environment variables defined in your eas.json build profile will be used when evaluating your app.config.js when running eas build and will be available to all steps of the build process on the EAS Build server.

This may result in some duplication of variables between .env files and eas.json build profiles, but makes it easier to see what variables will be applied across all environments.

How do I share environment variables between my local development environment, EAS Update, and EAS Build?

Environment variables defined in eas.json are only available when running an EAS Build job. However, you may wish to change variables used within your application code based on the build profile while minimizing duplicating values you might keep in an .env file for local development or for when publishing to EAS Update.

Our Environment variables in EAS Update guide describes a few approaches for sharing environment variables between all of these contexts.

How are naming collisions between secrets, the env field in eas.json, and .env files handled?

Environment variables are applied in the following order:

1. eas.json build profile env field
2. Environment variables defined in EAS Secrets
3. .env files committed to source control and are not in .easignore

Variable sources applied last will overwrite the previously loaded source for variables with the same name. So, a secret created on the Expo website or with eas secret:create will take precedence over an environment variable of the same name that is set through the env field in eas.json.

For example, if you create a secret with the name MY_TOKEN and value secret and also set "env": { "MY_TOKEN": "public" } in your eas.json, then process.env.MY_TOKEN on EAS Build will evaluate to secret.

How do environment variables work for my Expo Development Client 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.

Can I just set my environment variables on a CI provider?

Environment variables must be defined in eas.json to be made available to EAS Build builders. If you are triggering builds from CI this 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 in eas.json.

How to upload a secret file and use it in my app config?

A common use case for uploading file secrets to EAS is when you want to supply your build with the google-services.json and GoogleService-Info.plist files. Usually, those files should not be checked into the repository.

Here's an example of how to upload google-services.json to EAS and use it in your app config:

export default {
  %%placeholder-start%%...%%placeholder-end%%
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON,
    %%placeholder-start%%...%%placeholder-end%%
  },
};