Environment name binding is compile-time only in Azure DevOps YAML

Answer the question first

In Azure DevOps YAML the environment keyword must be known when the pipeline is parsed. It cannot be set from a runtime variable or a queue‑time parameter. The only supported syntax is a compile‑time template expression that references a variable or parameter that is defined before the YAML is compiled.

Confirmed facts

• Runtime variables (e.g., $(envName)) are rejected with a configuration error.
• Compile‑time template expressions such as $[variables['envName']] or $[parameters.envName] are accepted.
• The referenced variable or parameter must exist before the pipeline is parsed.
• Environments must pre‑exist in the project; the pipeline cannot create them on the fly.
• Missing or mismatched environment names cause the pipeline to fail before any jobs run.

Typical pattern for branch‑to‑environment mapping

Define a compile‑time parameter or variable that maps the current branch to the desired environment name. The mapping can live in a variable group, a parameter file, or directly in the pipeline definition.

parameters:
  - name: envName
    type: string
    default: 'dev'

variables:
  # Map branches to environments – can be overridden by a variable group
  branchEnvMap: |
    main: prod
    feature/*: test

steps:
- script: |
    echo "Branch: $(Build.SourceBranchName)"
  displayName: 'Show branch'

- deployment: Deploy
  environment: $[variables['envName']]
  strategy:
    runOnce:
      deploy:
        steps:
          - script: echo Deploying to $(environment)

In this example the envName parameter is set to the value from the branchEnvMap variable group (or overridden by a pipeline variable). Because the value is known at compile time, Azure DevOps can resolve the environment name before any jobs start.

Steps for your scenario

1. Pre‑create the environments in Azure DevOps (e.g., dev, test, prod).
2. Store a branch‑to‑environment map in a variable group or a parameter file.
3. Expose a compile‑time parameter (or variable) that pulls the correct environment name from that map.
4. Reference the parameter in the environment keyword using a compile‑time template expression: environment: $[parameters.envName].
5. Run the pipeline; the environment name is resolved during compilation and the deployment job will target the correct environment.

Limits on templating environment references

• Only compile‑time expressions are allowed; runtime or queue‑time variables are rejected.
• The variable or parameter must be defined before the environment keyword is encountered.
• Environment names are project‑global; you cannot create a new environment as part of the pipeline run.
• Approvals and variable groups attached to the environment are applied automatically once the environment is resolved.

Diagnostic question

Do you currently maintain a variable group that maps branch names to environment names, or would you prefer to embed the mapping directly in the pipeline parameters?