pages/build-reference/variables.mdx

---
title: Environment variables and secrets in EAS Build
sidebar_title: Environment variables and secrets
description: Learn how to use environment variables and secrets in an EAS Build.
---

import { Collapsible } from '~/ui/components/Collapsible';
import { Step } from '~/ui/components/Step';
import { Terminal } from '~/ui/components/Snippet';

The [Environment variables in Expo guide](/guides/environment-variables) 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 (e.g.,`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 a 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](/guides/environment-variables), 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:

```bash .env
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:
```bash .gitignore
# ignores all .env files
.env*
```

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

```json 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. See notes for [SDK 48 and lower](/guides/environment-variables#environment-variables-in-sdk-48-and-lower).

### For use by your Expo config
You can use environment variables in a [dynamic config](/workflow/configuration/#dynamic-configuration) (**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:
```json eas.json
{
  "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:
```js app.config.js
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](/build-reference/npm-hooks/) and the environment variable `EXAMPLE_ENV` will be available until the end of the build job.

<Terminal cmd={[ 'set-env EXAMPLE_ENV "example value"' ]} />

## 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](local-builds)
- `EAS_BUILD_ID` - the build ID, e.g. `f51831f0-ea30-406a-8c5f-f8e1cc57d39c`
- `EAS_BUILD_PROFILE` - the name of the build profile from **eas.json**, e.g. `production`
- `EAS_BUILD_GIT_COMMIT_HASH` - the hash of the Git commit, e.g. `88f28ab5ea39108ade978de2d0d1adeedf0ece76`
- `EAS_BUILD_NPM_CACHE_URL` - the URL of npm cache ([learn more](/build-reference/private-npm-packages))
- `EAS_BUILD_MAVEN_CACHE_URL` - the URL of Maven cache ([learn more](/build-reference/caching/#android-dependencies))
- `EAS_BUILD_COCOAPODS_CACHE_URL` - the URL of CocoaPods cache ([learn more](/build-reference/caching/#ios-dependencies))
- `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.

> **warning** 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 [the "Secrets" tab in your account or organization settings](https://expo.dev/accounts/[account]/settings/secrets).

To create **app-specific secrets**, navigate to [the "Secrets" tab in your project dashboard](https://expo.dev/accounts/[account]/projects/[project]/secrets). If you haven't published your project yet and it isn't visible on the website, you can create it on the website from this link.

### Adding secrets with EAS CLI

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

<Terminal
  cmd={[
    '$ eas secret:create --scope project --name SECRET_NAME --value secretvalue --type string',
    '✔ ️Created a new secret SECRET_NAME on project @fiberjw/goodweebs.',
  ]}
/>

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

<Terminal
  cmd={[
    '$ eas secret:list',
    'Secrets for this account and project:',
    '┌────────────────┬────────┬─────────┬──────────────────────────────────────┬─────────────────┐',
    '│ Name           │ Type   │ Scope   │ ID                                   │ Updated at      │',
    '├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤',
    '│ APP_UPLOAD_KEY │ string │ account │ 366bd434-b538-4192-887c-036c0eddedec │ Oct 05 11:51:46 │',
    '├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤',
    '│ NPM_TOKEN      │ string │ project │ 03f4881f-88fd-4d94-9e35-a5c34d39c2f2 │ Oct 05 11:51:33 │',
    '├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤',
    '│ SECRET_FILE    │ file   │ project │ 72c7ac1e-78d0-4fa2-b105-229260cecc88 │ Oct 05 11:52:12 │',
    '├────────────────┼────────┼─────────┼──────────────────────────────────────┼─────────────────┤',
    '│ sentryApiKey   │ string │ project │ 88dd0296-9119-4d50-a91b-1f646733f569 │ Oct 05 11:51:40 │',
    '└────────────────┴────────┴─────────┴──────────────────────────────────────┴─────────────────┘',
  ]}
/>

### 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:

<Terminal
  cmd={[
    '$ eas secret:push --scope project --env-file ./eas/.env',
    '✔ Creating secrets on account johndoe...',
    '✔ Created the following secrets on account johndoe:',
    '- ABC',
    '- DEF',
    '- GHI',
  ]}
/>

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](https://doppler.com/) project:

<Terminal
  cmd={[
    '$ doppler run --mount ./eas/.env -- eas secret:push --scope project --env-file ./eas/.env',
  ]}
/>

### 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](eas-update/environment-variables/#sharing-environment-variables-between-local-development-eas-update-and-eas-build) 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](/build/building-on-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:

<Step label="1">

Upload the file to EAS.

<Terminal
  cmd={[
    '$ eas secret:create --scope project --name GOOGLE_SERVICES_JSON --type file --value ./path/to/google-services.json',
    '✔ ️Created a new secret GOOGLE_SERVICES_JSON on project @user/myproject.',
  ]}
/>

</Step>

<Step label="2">

Use **app.config.js** to read the path to **google-services.json**.

```js app.config.js
export default {
  // ...
  android: {
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON,
    // ...
  },
};
```

</Step>