Get started with scopes and deploy contexts

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.

Use the Netlify UI to opt in to the beta environment variables experience and update your site to use the new secrets store. Once your site is updated, you can create or update variables in the UI as outlined below or with the updated CLI and API.

# Opt in and migrate to the new experience

To get started with the beta, use the Netlify UI to opt in and update a site to use the new secrets store.

  1. Opt in to the experience in Netlify Labs.

  2. 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.
  3. 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.

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 you have updated your site to use the new secrets store, you can add new environment variables under Site settings > Environment variables in the Netlify UI.

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

If a shared environment variable and a site environment variable exist with the same key name, the site environment variable’s contextual values take precedence in each deploy context.

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.

# Create shared environment variables

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

Once you have updated at least one site to use the new secrets store, team Owners can add new shared environment variables under Team settings > Environment variables in the Netlify UI.

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.

If a shared environment variable and a site environment variable exist with the same key name, the site environment variable’s contextual values take precedence in each deploy context.

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

Note that if you have not updated all sites to use the new secrets store, 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.