Build environment variables

Netlify environment variables are accessible during your build. This allows you to change behaviors based on deploy parameters or to include information you don’t want to save in your repository, such as API keys.

This page describes specific variables available in the Netlify build environment, how to set your own environment variables, and how to use environment variables during the build process.

# Declare variables

You can create your own environment variables in the following ways:

  • In the Netlify configuration file. File-based configuration allows you to set different environment variables for different deploy contexts. Variable values set in the configuration file will override values set in the UI. Because the configuration file is stored in your repository, we recommend setting sensitive values in the Netlify UI, where possible.
  • In the Netlify UI, under Site settings > Build & deploy > Environment > Environment variables. You can also use the Netlify CLI and API for site environment variables. Variable values set at the site level will override variables at the team level.
  • In the Netlify UI, under Team settings > Sites > Global site settings > Shared environment variables. Variables set at the team level are shared by all sites owned by the team and can be read or accessed by team Owners only. These can be overridden by settings at the site level. (This feature may not be available on all plans.)

Environment variables stored on Netlify (using the UI, CLI, or API) are also accessible in other environments associated with your site, including serverless functions at execution time, snippet injection during post processing, and more.

Deploy to apply changes

Environment variable changes are applied at deploy time and require a re-deploy to take effect.

# Sensitive variable policy

Some environment variables you may want to keep private. This can pose a challenge for sites connected to public repositories, where anyone can trigger a Deploy Preview by making a pull/merge request from a fork. We call these deploys untrusted deploys.

Site members’ deploys are trusted

Git provider accounts connected to a site member can trigger deploys without restrictions, even from forks. If a site member’s deploys are being treated as untrusted, make sure they connect their Git provider account to their Netlify user.

Netlify allows you to control whether untrusted deploys can access sensitive environment variables by choosing a sensitive variable policy. The policy is only available for sites connected to public repositories, and it includes the following options:

  • Require approval (default): policy that requires all untrusted deploys to be approved by a site member before the build can start. Deploys awaiting approval can be found at the top of the deploy list on the site Deploys tab. Accepting or rejecting a deploy request does not affect the status of the originating pull/merge request.

    deploy list entry for an untrusted deploy request, including the Deploy Preview number, Git author username, link to review changes, and buttons to accept or reject.

  • Deploy without sensitive variables: policy that lets untrusted deploys build automatically, but variables identified as sensitive will not be passed to the deploy environment. You can adjust your site code to accommodate builds without sensitive variables present, or you can assign “public” versions of your variables under the deploy-preview context in your Netlify configuration file.

  • Deploy without restrictions: policy that treats untrusted deploys like any other Deploy Preview, building automatically with all variables present. Use this option only if you are not concerned about the potential exposure of any of your site’s environment variables.

By default, when Netlify detects potentially sensitive environment variables in your site settings, we automatically apply the default setting above, requiring approval for all untrusted deploys. You can change this policy at any time in Site settings > Build & deploy > Environment > Sensitive variable policy.

Self-hosted repositories are considered private

Because self-hosted GitHub/GitLab instances enable a higher degree of access control, we treat all self-hosted repositories as private. This means you won’t be able to set a sensitive variable policy for a site linked to a repo on GitHub Enterprise Server or GitLab self-managed.

# Deploy request notifications

When your sensitive variable policy is set to require approval for all untrusted deploys, you can add deploy notifications to trigger when a deploy request is pending, approved, or rejected. Visit the deploy notifications doc to learn more about the types of notifications available and how to configure them.

# Netlify configuration variables

By setting custom values for certain reserved environment variables, you can change some aspects of your build, such as language and dependency versions. Links in the variable descriptions below provide more information about requirements, defaults, and accepted values.

The following variables should be set in the Netlify UI rather than in netlify.toml. This is because the Netlify configuration file is read after your repository has been cloned.

  • GIT_LFS_ENABLED: value that is undefined by default. If set, we’ll use git lfs clone to check out your repository — otherwise we use git clone.
  • GIT_LFS_FETCH_INCLUDE: if GIT_LFS_ENABLED is set, this specifies by file extension which Git LFS files will be downloaded when cloning your repository. Any other file extensions will have only text pointer files downloaded instead of the original media files. The default file extensions are determined by the site build-image.
  • NETLIFY_BUILD_DEBUG: set this to true to print additional debugging information in the build logs. The output does not contain sensitive information. To disable debugging, delete the variable. Alternatively, delete everything in the variable’s Value field.

# Read-only variables

In addition to the variables you choose to declare, Netlify has a number of pre-defined variables built in. The following variables are automatically set for your builds, and their values are not changeable.

# Build metadata

  • NETLIFY: always true. Can be used to check if the build is running on Netlify.
  • BUILD_ID: unique ID for the build; for example: 5d4aeac2ccabf517d2f219b8.
  • CONTEXT: name of the build’s deploy context. It can be production, deploy-preview or branch-deploy.

# Git metadata

  • REPOSITORY_URL: URL for the linked Git repository.
  • BRANCH: reference to check out after fetching changes from the Git repository. Can be useful for split testing.
  • HEAD: name of the head branch received from a Git provider.
  • COMMIT_REF: reference ID (also known as “SHA” or “hash”) of the commit we’re building.
  • CACHED_COMMIT_REF: reference ID (also known as “SHA” or “hash”) of the last commit that we built before the current build.
  • PULL_REQUEST: whether the build is from a pull/merge request (true) or not (false).
  • REVIEW_ID: ID of the request and the Deploy Preview it generated (for example, 1211) if from a pull/merge request. These two numbers will always match. (For example, deploy-preview-12 is for PR #12 in your repository.)

# Deploy URLs and metadata

  • URL: URL representing the main address to your site. It can be either a Netlify subdomain or your own custom domain if you set one; for example, https://petsof.netlify.app or https://www.petsofnetlify.com.
  • DEPLOY_URL: URL representing the unique URL for an individual deploy. It starts with a unique ID that identifies the deploy; for example, https://5b243e66dd6a547b4fee73ae--petsof.netlify.app.
  • DEPLOY_PRIME_URL: URL representing the primary URL for an individual deploy, or a group of them, like branch deploys and Deploy Previews; for example, https://feature-branch--petsof.netlify.app or https://deploy-preview-1--petsof.netlify.app.
  • DEPLOY_ID: unique ID for the deploy; for example, 578ab634d6865d5cf960d620. Matches the beginning of DEPLOY_URL.
  • SITE_NAME: name of the site, its Netlify subdomain; for example, petsof.
  • SITE_ID: unique ID for the site; for example, 1d01c0c0-4554-4747-93b8-34ce3448ab95.
  • NETLIFY_IMAGES_CDN_DOMAIN: if image compression post processing is enabled, the base URL used for all processed images; for example, d33wubrfki0l68.cloudfront.net.

# Build hook metadata and payload

If your build is triggered from a custom build hook, Netlify also has three build-hook-specific variables:

  • INCOMING_HOOK_TITLE: title of the build hook.
  • INCOMING_HOOK_URL: URL of the build hook.
  • INCOMING_HOOK_BODY: payload of the request sent to the build hook URL.

# Access variables

Build environment variables are available in the build system they’re set in and are available for use by build plugins and scripts run during the build step for a site. This section outlines how to access these variables during the build process.

Note that, as these are build variables specifically, you will need to take extra steps if you want your site to have access to these values after the build is complete.

# Prepare your build environment

To use these environment variables, you need to ensure they’re set in the environment where the build will run - on Netlify through continuous deployment or in your local development environment.

# Build on Netlify

If you have continuous deployment set up, Netlify will automatically start a build and deploy whenever you push code to your Git repo. While the build runs on Netlify, the build system already has access to all of the variables set in the Netlify build environment and can use them during the build process.

Note that when you build on Netlify, the build system doesn’t read .env files. To use variables declared in a .env file, we recommend you import the variables into Netlify using the CLI’s env:import command before you build. This way the variables in your .env file remain secure and out of your shared repository.

# Build locally

When you build in your local development environment, you need to ensure these environment variables are set in the local environment before you run the build command.

The best way to build locally is to use the Netlify CLI. Building locally with the CLI mimics the behavior of running a build on Netlify and will give you access to the environment variables you’ve already set there.

netlify build

You can also take advantage of Netlify Dev to run a local development environment that mimics the Netlify production environment. Netlify Dev will automatically pull down environment variables stored on Netlify and read any variables stored in a .env or .env.development file on your machine.

If you don’t want to use the Netlify CLI or Netlify Dev, you need to set the variables in your local development environment yourself.

There are a few different ways to do this, including declaring variables directly in the command line or using a .env file and dotenv. Read more about both options in the Node.js docs. Just remember not to commit any sensitive values to your repository.

Visit our Forums for a verified Support Guide on how to access environment variables during your site build for more tips.

# Use variables during the build

Once the variables are set correctly in the environment you want to build in, you can access them in a few different ways depending on the context.

# Use variables in the netlify.toml or Netlify UI

Netlify commands use the Bash shell, so you can use Bash syntax to select the environment variable: $VARIABLE_NAME.

You can use this format in the Netlify UI and in the netlify.toml with the build.command and ignore.command.

For example, to print a not-sensitive variable (GREETING = "hi there") to the deploy log at the end of the build step, set the build command in the Netlify UI to npm run build && echo $GREETING.

The next time you build and deploy the site, the build process will print the variable to the deploy log at the end of the build step.

Note that if you would like to use environment variable values in the [[headers]] and [[redirects]] sections of the netlify.toml, you need to inject the values as part of your build command.

# Use variables to install private npm modules

To use an environment variable for private npm module installs, you can set an NPM_TOKEN value in your build environment. Whenever Netlify runs an install and build, npm will automatically check the environment for an NPM_TOKEN to use for authentication. This way, you can avoid declaring or accessing this sensitive variable value directly in your package.json.

# Use variables in Node.js script files

To access environment variables in script files that Node.js runs during the build process, you need to use the format process.env.VARIABLE_NAME.

For example, create a JavaScript file sayHello.js that will log your non-sensitive variable (GREETING = "hi there") to the console when run:

  const greetPerson = process.env.GREETING;
  console.log(`Say hello: ${greetPerson}`);

Then, update the build command in the package.json or in the netlify.toml to include the instruction to run the script file. Here’s an updated netlify.toml file:

[build]
  command = "npm run build && node ./sayHello.js"

The next time you build and deploy the site, the build process will print the variable to the deploy log at the end of the build step.

# Use variables in build plugins

There are two ways to access environment variables in build plugins: using process.env.VARIABLE_NAME or using netlifyConfig.

# Use variables in a site after it’s built

If you want to use environment variable values in a site after it’s built, you need to take further action to provide access. Here are a few options:

  • Use a function to access values during runtime. This is the best option to avoid revealing sensitive values.
  • Use snippet injection to access values during post-processing.
  • Use a custom script or framework-specific variables to copy values into the site code during the build process.

If you inject values into the site using a build script or snippet injection, make sure to only include non-sensitive values.

More details are available in our verified Support Guide on how to access environment variables.

# More environment variables resources