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.
Netlify will migrate sites off the classic experience starting February 20
While you can manually migrate your sites now, Netlify will start to migrate all remaining sites to the new experience on February 20, 2023. Once all sites are migrated, the classic methods to update environment variables (including env with the /sites API endpoint) will no longer be available. Learn more in our blog post about the upcoming migration.
# 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.
If your site is using the classic experience, site environment variables are located under Site settings > Build & deploy > Environment > Environment variables.
# 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 |
| Edge functions - atomic deploys apply for environment variables | ✓ | |
| 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.
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.
Add or edit any environment variables as needed. Any environment variable changes made after migration require a build and deploy to take effect.
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 innetlify.tomloverride variables with the same key name set in the Netlify UI, CLI, or API.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
sitesAPI endpoints for sites in the new experience as the data returned in theenvproperty of thebuild_settingsobject 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 a site uses the classic experience, set the sensitive variable policy under Site settings > Build & deploy > Environment. If a site uses the new experience, set the sensitive variable policy under Site settings > Environment variables > Site policies.
- Edge Functions handle variable changes differently. The requirement to redeploy a site for environment variables changes to take affect in edge functions only applies to sites that use the new experience. If a site uses the classic environment variables experience, all edge functions and their previous deploys automatically use the most recent environment variables and values.
# Support for integration owners
If you manage an integration that relies on the Netlify API for environment variables and require assistance with this migration, please reach out to us through our technology partner program so we can help.
Did you find this doc useful?
Your feedback helps us improve our docs.