Classic environment variables

There is a new and updated environment variable experience available that provides more options to customize variables for different use cases. If your team was created after November 2, 2022 at 16:00 UTC, all of your sites already use the new experience.

This page outlines the difference between the new and classic environment variables experiences, provides instructions for how to migrate your sites to use the new experience, and covers known issues for teams with sites in each experience.

The classic experience will no longer be available in 2023

While you have the option to manually migrate your sites now, Netlify will migrate all remaining sites to the new experience in early 2023. At that time, the classic methods to update environment variables (including env with the /sites API endpoint) will no longer be available.

# Two different environment variable experiences

Currently, teams created before November 2, 2022 at 16:00 UTC have the option to migrate sites one at a time to use the new experience. As a result, some sites that you own might be using the new experience, while others might be using the classic experience.

# Determine which experience your site is using

To confirm which experience your site is using, check where site environment variables are located in the Netlify UI.

If your site is using the new experience, site environment variables are located under Site settings > Environment variables.

UI for the new environment variables experience

If your site is using the classic experience, site environment variables are located under Site settings > Build & deploy > Environment > Environment variables.

UI for the classic environment variables experience

# Compare the two experiences

The new environment variable experience offers more customizable options and workflows for your use.

Feature New experience Classic experience
Site environment variables
Shared environment variables
Set specific scopes for variables
Set a different value for each deploy context using the Netlify UI, CLI, or API
Set a different value for each deploy context using netlify.toml in your repository
CLI - add, edit, delete variables with netlify env
CLI - get or modify scopes and individual contextual values with netlify env
CLI - specify a deploy context for use with netlify build and netlify dev
API support for environment variables full partial
Audit log entries
Filter and review environment variables at a glance
Variables maintained after unlinking repository

# Migrate your site

To get started with the new experience, use the Netlify UI to update your site to use the new store and migrate any existing environment variables.

  1. Go to Site settings > Environment variables.

    • If you have site or shared environment variables set, select Migrate environment variables to switch to the new store and migrate your environment variables.
    • If you don’t have any environment variables set, select Opt in to the new experience to switch to the new store.

    All 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 available to all scopes and have the same value for all deploy contexts.

  2. Add or edit any environment variables as needed. Any environment variable changes made after migration require a build and deploy to take effect.

  3. If you previously set environment variables in a Netlify configuration file (netlify.toml), we recommend you remove individual variables from the file as you create them with the new experience. This will help avoid unexpected behavior as environment variables declared in netlify.toml override variables with the same key name set in the Netlify UI, CLI, or API.

  4. Once you add or update environment variables to use a specific value in each deploy context as needed, you can also uninstall any build plugins that were used solely to configure values for different 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.

Site migration can’t be reversed

Once you migrate a site to use the new experience, it is not possible to revert that change to use the classic experience again.

# Known issues for teams using both experiences

If you have some sites using the new experience and some sites using the classic experience, you should be aware of some unique challenges that you might face.

  • There are two sets of shared environment variables. Only sites that use the new store have access to shared environment variables set or updated in the Netlify UI under Team settings > Environment variables or through the API endpoints. Sites that use the classic experience only have access to shared variables set in the Netlify UI under Team settings > Sites > Shared environment variables. To keep all of your sites in sync, we recommend that you duplicate any changes or additions you make in both sections of the Netlify UI. The classic experience section will remain available until early 2023, but you should stop using it once you migrate all of your sites.
  • Workflows using the CLI or API require an update to access environment variables for sites in the new experience. If you currently use the CLI or API to access environment variables for your site, you will need to update your workflow to use the new environment variables endpoints or the latest version of the Netlify CLI for any sites using the new experience. We do not recommend using the classic sites API endpoints for sites in the new experience as the data returned in the env property of the build_settings object may be outdated. This might require the use of two API workflows if you have some sites using the classic experience and others using the new experience.
  • The location of the sensitive variable policy settings differs. If the site is still on the classic experience, set the sensitive variable policy under Site settings > Build & deploy > Environment. If the site is on the new experience, set the sensitive variable policy under Site settings > Environment variables > Site policies.