environment-variables

name	environment-variables
description	Author Microsoft Power Platform environment variables and connection references inside an unpacked solution so an agent can parameterize apps, flows, and plugins across dev/test/prod without hardcoding -- definitions, current values, data types (string/number/JSON/secret/Data Source), and Key Vault-backed secrets. Covers the ALM mechanism that makes a solution portable.
metadata	{"author":"AgentX","version":"1.0.0","created":"2026-05-30"}
compatibility	{"surfaces":["low-code-builder","agent-x","engineer"],"platforms":["power-platform","dataverse","alm"]}

Environment Variables & Connection References

Purpose: emit environment variables + connection references so one solution moves cleanly across dev/test/prod -- the ALM parameterization layer. No environment-specific value should be hardcoded in an app or flow.

When to Use

• Any value that differs per environment: API base URLs, IDs, feature flags, secrets
• Decoupling flows from specific connections so importers bind their own
• Reviewing a solution for hardcoded environment-specific values before export

Environment Variables

Two parts: a definition (schema name, display name, type, default) and an optional current value (this environment's value). Ship the definition + a default in the solution; let each environment override the current value.

src/
  environmentvariabledefinitions/<prefix>_<name>/
    environmentvariabledefinition.xml   # type, default value, schema name
  environmentvariablevalues/...         # current value (often NOT shipped to prod; set on import)

Type	Use for
String / Number / Boolean	URLs, IDs, flags
JSON	Structured config
Data Source	Bind to a connector data source per environment
Secret	Key Vault-backed -- the value lives in Azure Key Vault, only a reference ships

In a flow or app, read the variable rather than a literal (e.g. flows reference the environment variable; canvas reads it via the data source).

Secrets Belong in Key Vault

For credentials/keys, use a Secret environment variable bound to an Azure Key Vault secret. The solution carries only the Key Vault reference (vault name + secret name), never the secret material. Grant the environment's identity GET access to the secret.

Connection References

A connection reference is a named placeholder a flow points to instead of a concrete connection. On import, the admin maps each connection reference to an actual connection in the target environment -- so the same flow uses dev creds in dev and prod creds in prod.

src/
  connectionreferences/<prefix>_<name>/
    connectionreference.xml   # logical name, connector id

Every flow connector binding SHOULD go through a connection reference, not an embedded connection, or the flow breaks on import.

Anti-Patterns

• Hardcoding URLs/IDs/secrets in flow or app definitions -- breaks portability and leaks secrets.
• Shipping production current values inside the solution -- set them at import time instead.
• Plaintext secret-type values instead of Key Vault references -- credential exposure in source.
• Embedded connections in flows instead of connection references -- import binding fails.

Verify

pac solution pack ...    # definitions + connection references must pack
# Import to a second environment and confirm you are prompted to set values / map connections.

Related

• power-automate-flow-json -- flows consume connection references + variables
• pac-cli -- import-time value and connection mapping
• solution-anatomy -- definition placement