What it does

Named key/value pairs that ship inside a solution so an app can point at different things in each environment without being edited. The definition travels with the solution; the value is supplied at import time or set in the target environment.

Key facts

• Data types are decimal number, text, JSON, two options, data source and secret.
• Definition and value are separate records. A definition can carry a default value; a current value overrides it. Microsoft's guidance is to ship the definition and leave the value out of the solution so the target environment supplies its own.
• Values are visible and editable in the modern solution import experience and in pipeline deployments, with a label showing whether the value came from the solution, the target environment or the default.
• Power Apps can create environment variables automatically when you add a data source, if you turn on the setting in Studio.
• Dataverse tables in the current environment don't need an environment variable. External Dataverse tables, SharePoint sites and lists, and Microsoft Entra SQL server and database references do.
• Don't use environment variables for basic SQL authentication. Server and database are part of the connection string there, so a connection reference is the right mechanism.
• Values are capped at 2,000 characters. There's no cap on the number of variables, but the 95 MB solution limit still applies.
• Value changes propagate asynchronously and can take up to an hour to be fully picked up by apps and flows.
• Secret-type variables reference an Azure Key Vault secret rather than storing it. Those secrets are usable from Power Automate flows, Copilot Studio agents and custom connectors — not from canvas app formulas or the general API.
• $authentication and $connection are reserved names. Using them blocks flow save.

When to use / skip

Use one wherever an app points at something that will be different in test and production — a SharePoint site, an external Dataverse environment, a SQL server, a threshold someone will want to change. It costs almost nothing at build time and saves you a manual edit on every deployment forever. Skip them for relational configuration data: if you're storing more than key/value pairs you want a configuration table and a migration tool, not a growing pile of environment variables. And don't reach for a secret-type variable expecting to read it in a canvas app, because you can't.

Configuration decisions

• Which references genuinely vary per environment, versus which are just hard-coded values someone would like to be configurable.
• Whether values ship inside the solution or are supplied at import. Shipping them makes deployment simpler and makes production values visible in dev, which is usually the wrong trade.
• Whether Studio auto-creates variables when data sources are added, which is convenient and produces variables nobody named deliberately.
• Naming, because duplicate display names make variables genuinely hard to tell apart at import time and there's nothing enforcing uniqueness.
• Whether secrets go through Key Vault at all, given the consumers are limited to flows, agents and custom connectors.
• One Key Vault per environment versus one shared vault, weighing blast radius against admin effort.

Gotchas

• If the environment variable is in a managed solution you can't see its value in that solution. You have to look inside the Default solution, and this is by design because the value is an unmanaged customisation.
• Deleting a value that arrived in a managed solution needs an upgrade, not an update — you remove it in the source, export a new version, and upgrade. An update won't delete it.
• SharePoint list environment variables need matching metadata. A recreated list in the target with the same name and columns has different internal identifiers and won't bind.
• Connections aren't stored on a data source variable. They're only used to render the picker, so a maker without access to the connection can still enter the value manually — and gets an access denied warning that's non-blocking and easily ignored.
• Pipelines can't update a connection reference that has no value in the solution or the target. Only ones with a previously deployed value can be changed.
• Power Platform Build Tools tasks don't yet manage data source environment variables, so that part of the deployment stays manual or scripted.

Consultant notes

• Make "no hard-coded site URLs, server names or thresholds" a code review rule rather than a suggestion. Retrofitting environment variables into a published app is tedious and always happens at the worst moment.
• The value-visibility rule catches support teams badly. Document that production values live in the Default solution, or you'll field the same question every time someone new joins.
• Key Vault integration is an Azure conversation with the client's platform team, not a Power Platform task. Raise it in discovery, because resource provider registration and RBAC roles sit with people who aren't in your project.
• Warn about the up-to-an-hour propagation delay before someone changes a value in production and starts debugging why nothing happened.

---

Worth revisiting if Build Tools gain data source variable support, or if secret variables become readable from canvas apps.