Learn how to Visually Build at Scale with Builder.io and Netlify Register now!

News & Announcements

Now generally available: Scopes and contextual values for environment variables

News & Announcements

Now generally available: Scopes and contextual values for environment variables

Scopes and contextual values for environment variables are now generally available! These features are production-ready and can be used in all your sites today.

Scopes and contextual values are part of a new experience for environment variables. Netlify teams created after November 2, 2022 will get the new environment variables experience by default for all sites across their team. Existing teams can opt into the new experience on a site-by-site basis.

Starting in early 2023, Netlify will automatically migrate your sites and teams to the new environment variable experience if you haven't done so already.

Find environment variables under your site settings.

What’s new?

While there are some UI updates in the new environment variables experience, the biggest functional changes include these abilities:

  • Scope the features where environment variables are available
  • Set different values for the same key on different deploy contexts

New environment variable scoped to builds only.

Scopes enable you to limit environment variables so that they can only be accessed by builds, functions, other runtime features, and/or post processing. This can be handy if you want to limit where data is accessed, or need to avoid exceeding limits on environment variables set by Lambda functions. Scopes are available for teams on our Pro plan or above.

Unique values are set for production, deploy previews, branch deploys, and the local development CLI.

You can now also set different values for the same key on different deploy contexts. This includes built-in deploy contexts: production, Deploy Previews, branch deploys, and local development on the Netlify CLI. You can also change the value for specific branches. For example, a long-lived staging branch might need to reference a token for your headless CMS’s staging environment.

Scopes and contextual values are available on the Netlify app UI, CLI, or API. They can be used on site variables, as well as shared environment variables which are available to all sites on your team. You do not need an additional build plugin or netlify.toml configuration for this functionality in the new experience.

Learn more about these new features in the Netlify docs.

How to get the new env var experience

If your team was created on or after time of writing (November 2, 2022), your account already has the new experience. The Netlify docs describe how to confirm which environment variables experience is active for your team.

Otherwise, you can opt in to the new experience on a site-by-site basis, before Netlify moves your variables to the new experience in early 2023.

Here’s how to opt in

Go to Site Settings > Environment Variables and choose “Migrate environment variables."

A banner in the Netlify app guides you to migrate your environment variables when ready.

This will move your site environment variables to a new, better-encrypted service. The first time you migrate a site’s variables, shared environment variables (accessed from Team Settings) will also be copied to the new service.

Because scopes and contextual values are now generally available, you will no longer have the option to roll back to the old experience.

You can find the new environment variable settings at Site Settings > Environment Variables, and Team Settings > Environment Variables.

Changes to API endpoints

Using Site endpoints on the Netlify API to manage environment variables? You will need to switch to new environment variable endpoints when interacting with environment variables on the new experience. Learn more about the new endpoints in the docs.

Try it out today!

We’re excited to extend what environment variables can do on Netlify. If you’d like to use the new experience and want to know more, you can find details in the docs.

We’re always keen to know what you think, so please do share any feedback on the experience or environment variables in general in the Netlify forums. Thank you as always for your feedback!

Keep reading

Recent posts

Book cover with the title Deliver web project 10 times faster with Jamstack enterprise

Deliver web projects 10× faster

Get the whitepaper