What it does

An environment variable is a solution component holding a key whose value can differ per environment. Flows, apps and plug-ins read the key, the deployment supplies the value, and the same solution artefact works in dev, test and production without anyone opening a flow to change a hard-coded URL.

Key facts

• Data types are Decimal number, Text, JSON, Two options, Data source, and Secret. Secret needs Azure Key Vault configured so Power Platform can read it.
• There are two records behind every variable: a definition (which carries the default value) and a value record (the current value). Current value wins when both are present; default is the fallback.
• Values are held in separate JSON files inside the exported solution zip and can be edited offline, which is what makes deployment settings files work.
• Microsoft's guidance is to ship the definition but not the value. Remove the current value from the solution before export so each target supplies its own.
• Values are capped at 2,000 characters. There's no limit on the number of variables beyond the 95 MB solution cap.
• Changed values propagate asynchronously to apps and flows, and can take up to an hour to fully publish.
• $authentication and $connection are reserved names. A flow using variables with those names is blocked from saving.
• No premium licence is needed for environment variables themselves. Dataverse is required, but you only need premium if you're reading them through the Dataverse connector.
• If a value is deleted, the runtime falls back to the last known value where the dependency system hasn't already prevented the deletion.

When to use / skip

Use them for anything that legitimately differs between environments — site URLs, list IDs, API base addresses, approver groups, feature toggles. Skip them for relational configuration data; that belongs in a custom table, and environment variables are meant for key-value pairs. Also skip them for values that are genuinely identical everywhere, because each one is another thing to populate at deployment and another way for a release to fail at 6pm on a Friday.

Configuration decisions

• Which values genuinely vary by environment versus which are constants people have assumed should be variables.
• Whether secrets go through the Key Vault-backed Secret type or stay in the connection, given Key Vault brings its own access configuration.
• Whether you set default values at all, remembering a default masks a missing deployment value rather than failing loudly.
• Whether values are supplied interactively at import, through a deployment settings file, or by pipelines.
• Naming, since duplicate display names make variables genuinely hard to tell apart in the designer.

Gotchas

• A variable in a managed solution hides its value in the normal solution view. You have to look inside the Default solution to see it, which is by design because the value is an unmanaged customisation.
• Deleting a value that arrived via a managed solution needs an upgrade, not an update — you remove the value in the source, export a new version, and upgrade the target.
• SharePoint data source variables need matching metadata between environments. Recreating a list with the same name and columns gives you different internal identifiers and it won't bind.
• Renaming a variable used in a flow leaves both old and new display name tokens visible in the designer. Remove the reference and re-add it rather than trusting it.
• Power Platform Build Tools tasks still don't manage data source environment variables, so those need handling another way in a fully automated pipeline.
• The connection on a data source variable is only used to render the picker. It isn't stored, and if you lose access you enter the GUID by hand.

Consultant notes

• Set the standard early: definitions ship, values don't. It's the single rule that keeps environment variables from becoming a source of production incidents.
• The one-hour asynchronous publish catches people out during cutover. Change values well ahead of the go-live window rather than during it.
• Push back on clients who want to use environment variables as a general configuration store. When they start asking for lookups and relationships, it's a table.
• If secrets are in scope, get the Key Vault conversation started early — it usually involves a different team and their lead time, not yours.

---

Worth revisiting if Build Tools ever gain support for data source variables, or if the value character limit changes.