Environment variables overview

Netlify environment variables allow you to configure your site’s build and functionality based on different parameters and deploy contexts.

This page describes environment variable options, how to declare environment variables, and how you might use environment variables with Netlify.

# Overview

Netlify offers a few different options for how you can use and configure environment variables:

  • There are two types of environment variables: shared environment variables that are available to all sites in your team and site environment variables set for specific sites. Site environment variables can override shared environment variables.
  • Environment variables are available to builds, functions, injected snippets, and more depending on where you declare them.
  • Environment variables are available for use across different deploy contextsproduction, deploy preview, branch deploy, and dev.
  • Netlify provides a set of configuration variables and read-only variables for use during the build process.
  • There is a sensitive variable policy that you can configure to control access to sensitive variables.
  • You can use the Netlify CLI to access and modify environment variables stored on Netlify.

# Environment variable options

Netlify supports two ways of setting and storing environment variables — with the Netlify UI or CLI, or with a Netlify configuration file. Depending on which method you use, there are different environment variable options available.

We recommend using the Netlify UI or CLI, where possible, to avoid storing sensitive values in your repository.

Netlify UI or CLI Netlify configuration file
Stored on Netlify
Stored in your repository
Set site environment variables
Set shared environment variables
Set a single value that is available to all deploy contexts
Set a different value for each deploy context
Available to builds
Available to serverless functions
Available to snippet injection
Available to forms
Available to signed proxy redirects

New environment variable options with the Netlify UI, CLI, and API

If you’re looking for more customizable options, opt in to the new environment variables beta experience and migrate your site to the new secrets store. Once you migrate, you can use the Netlify UI, CLI, and API to create environment variables with specific scopes and a value for each deploy context.

# Overrides

There are a few overrides to be aware of:

  • Environment variables set in netlify.toml override environment variables set on Netlify using the Netlify UI or CLI.
  • Site environment variables override shared environment variables.
  • If you use the Netlify configuration file to set environment variables for different deploy contexts, the deploy context precedence rules apply.

# Limitations

The following limitations apply for environment variables:

  • Reserved variable names. Netlify offers some read-only build environment variables that are reserved key names. You can’t override these variables or their values.
  • Character and value limits. Keys can contain up to 128 characters. Values used by functions should fall within AWS’s environment property limits.
  • Shared variable access limitations. Only team Owners can read and edit shared environment variable values.
  • Unlinking repositories clears variables. When you unlink a Git repository, all site environment variables set in the Netlify UI are deleted.

# Create environment variables

You can create environment variables with the Netlify UI or CLI, or with a Netlify configuration file.

To apply environment variable changes, build and deploy.

Environment variable changes require a build and deploy to take effect.

# Create variables with the Netlify UI or CLI

When you create environment variables using the Netlify UI or CLI, they are set and securely stored on Netlify. This means you can avoid committing any sensitive values to your repository. The Netlify UI reflects any changes made using the CLI and vice versa.

You can create site environment variables and shared environment variables.

Be aware that variables set in a Netlify configuration file override variables set with the Netlify UI or CLI.

# Site environment variables

There are two ways to create site environment variables:

  • In the Netlify UI, create variables under Site settings > Build & deploy > Environment > Environment variables.
  • With the Netlify CLI, use env:set to create or update a site environment variable, and env:import to import from a env file. Review our Get Started with Netlify CLI guide to learn more.

Site environment variables override shared variables set at the team level.

# Shared environment variables

This feature may not be available on all plans.

Create shared environment variables 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. Only team Owners can read or access shared environment variables. Site environment variables override shared environment variables.

# Create variables with a Netlify configuration file

You can create site environment variables with a Netlify configuration file (netlify.toml) stored in your repository. This file-based configuration method allows you to set different environment variables for different deploy contexts.

Since netlify.toml is stored in your repository, we recommend setting sensitive values in the Netlify UI instead, where possible.

Variables set in a configuration file override variables set with the Netlify UI or CLI.

# 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. Deploys from people, automated services, or bots from outside your Netlify team (unrecognized authors) are always treated as 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.

Sensitive variable policy for GitHub Enterprise Server or GitLab self-managed

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

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

# Use environment variables

Once you’ve created environment variables, there are many different ways you can use them:

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

# Resources