Scopes and Deploy Contexts for Environment Variables

Experimental Feature

This experimental feature is available to try out before it’s fully released or ready for production. We recommend using it in non-critical sites and non-production environments only. Learn more in our Netlify Labs doc.

Netlify’s new environment variables experience allows you to keep your secrets even more secure and provides more options to customize variables for different use cases.

You can now use the Netlify UI to set different values for the same environment variable depending on the deploy context — without committing secrets to your shared repository. Previously, you could only set contextual variable values using a netlify.toml stored in your project or using a separate build plugin.

The ability to set contextual variable values opens up more possibilities for how you can leverage environment variables on Netlify. For example:

  • Analytics or experiments you wish to run only on the live site in production
  • Modifying which CMS environment to use for production versus Deploy Previews
  • Adding new functionality that requires a specific token and testing the change in a Deploy Preview before it goes live

Teams on Pro plans and above can also take advantage of new functionality to limit variables to specific scopes. By making variables available only to the scopes that need them, such as builds only or functions only, you can more tightly control where Netlify uses your sensitive data.

# New environment variable options

With the new experience, the ability to add a value for each deploy context and to limit variables to specific scopes is now available in the Netlify UI.

For example, you may configure a variable API_KEY that should only be used by Functions and has a different value for Production and for Deploy Previews.

# Value per context

The default is to set one value for all deploy contexts or you can choose to set a different value for each of the following contexts:

  • Production: for the main site’s deployment.
  • Deploy Previews: for previews we build for your pull/merge requests.
  • Branch deploys: for all branch deploys. Soon you’ll be able to specify values for individual branch deploy contexts, such as staging or docs branches.
  • Local development: for local development using the Netlify CLI. Note that CLI support for getting and setting contextual values is coming soon.

# Scope

The default scope is all, but teams on a Pro plan or higher can limit the variable to the following scopes:

  • Builds: includes site builds
  • Functions: includes Functions, Edge Functions, and On-Demand Builders
  • Runtime: includes forms and signed proxy redirects
  • Post processing: includes snippet injection

# Getting started

To get started, opt in to the experience in Netlify Labs and then migrate a specific site’s environment variables.

To migrate your site, go to Site settings > Environment variables and select Migrate environment variables.

Existing site environment variables and a copy of your team’s shared variables will be migrated to the new secrets store. This allows your site to fully interact with the new experience and take advantage of enhanced encryption.

By default, migrated variables are set to all scopes and have the same value for all deploy contexts.

At this time, there isn’t an option to enable the experience for an entire account at once. We want you to have more granular control over what sites you use to try out this new experience.

Rolling back a site is possible but won’t include your new changes

During the beta, it’s possible to roll back individual sites to the old experience and to access the variables as they were set in your secrets store before the migration. However, any changes you make while trying out the new experience will be lost if you roll back.

# Create site environment variables

Once the new experience is enabled for a site, you can add new environment variables under Site settings > Environment variables.

The new environment variable creation form showing options for specific scopes, as well as the ability to add a different value for each deploy context

Site environment variables will override any shared variables with the same key name set on the team level, including the variable’s scope settings and contextual values.

Any environment variable changes made after migration require a build and deploy to take effect.

Remove variables from your configuration file

Variables set in the netlify.toml will override those with the same key set in the Netlify UI. We recommend that you remove individual variables from the configuration file as you create them in the UI, except for those that require values set for specific branch deploy contexts.

# Create shared environment variables

(This feature may not be available on all plans.)

Once you have enabled the new experience and migrated at least one site, team Owners can add new shared environment variables under Team settings > Environment variables.

Variables set at the team level are shared by all sites owned by the team. Only team Owners can read and access shared variables through the Netlify UI, CLI, and API. Shared variables can be overridden by variables set at the site level.

Any environment variable changes made after migration require a build and deploy to take effect.

Note that if you have not migrated all sites to the new experience, you will need to make changes to shared environment variables in both the old UI (under Team settings > Sites > Shared environment variables) and the new UI to keep them in sync.

# Filter by key and track changes in the audit log

The new environment variables UI shows the scope and contexts at a glance and allows you to filter the list by key to find a specific variable.

Plus, all environment variable changes are captured in the team audit log so you can keep track of any variables that are created, modified, or deleted.

# Known issues and limitations

The beta release includes the following limitations that you should consider before you enable the experience.

# Individual branch deploy contexts

Currently, you can only set one value to be used across all branch deploy contexts. Soon you’ll be able to specify values for individual branch deploy contexts, such as staging or docs branches.

# Netlify CLI support

Netlify CLI 10.7.0 adds beta support for accessing and setting environment variables for migrated sites.

  • The netlify dev and netlify env read commands (env:list and env:get) retrieve variables that have a value available for use with the CLI — either a value set for use across all deploy contexts or one specifically set for the local development context. If a variable only has values set for other deploy contexts excluding local development, the CLI indicates that a variable with that key doesn’t exist.
  • The netlify env write commands (env:set, env:import, and env:migrate) create variables set to all scopes and with the same value for all deploy contexts.
  • The netlify env delete command (env:unset) removes variables and their values from all deploy contexts.

Support for reading and setting scope and contextual values is coming soon. Access the full command reference to learn more.

# Netlify API support

The Netlify API doesn’t support the new experience at this time and can’t be used for migrated sites. However, you can preview the upcoming beta API endpoints now.

# Share your feedback

We have more planned for this new environment variables experience but we’d love to hear your thoughts on the updates so far. Please share your feedback and tell us what you think.