In an Azure Pipelines YAML file, what does referencing a variable group under variables: give the run, and what changes when that group is linked to Azure Key Vault?

## What a variable group is A variable group is a named bag of key/value pairs stored in the Azure DevOps project's **Library**, outside any single pipeline. Its point is sharing: one `prod-config` group can feed a dozen pipelines, and rotating a value there changes every consumer at once. A YAML pipeline pulls one in by name: ```yaml variables: - group: prod-config - name: buildConfiguration value: Release ``` Everything in `prod-config` is now readable as an ordinary pipeline variable — `$(apiEndpoint)`, and so on. ## Two mechanical gotchas **The list form is contagious.** Azure accepts two shapes under `variables:` — a simple mapping (`buildConfiguration: Release`) and a sequence of typed entries. `- group:` only exists in the sequence form, so the moment you add a group, every other variable in that block has to be rewritten as `- name: … / value: …`. A half-converted block is a YAML parse error, and it is the first thing people hit. **Authorisation is separate from reference.** Naming a group does not grant access to it. The group carries its own pipeline permissions, and the first run of a pipeline that references an unauthorised group waits for someone to approve it. This is a feature, not friction: it prevents any pipeline in the project from silently helping itself to production credentials by typing the right name. ## Scope `variables:` can be declared at pipeline, stage or job level, and a group declared at stage level is visible only inside that stage. That is the natural way to keep a production group out of the reach of a build stage that has no business reading it. ## Linking to Key Vault A group can instead be marked as linked to an **Azure Key Vault**. You choose an Azure Resource Manager service connection, pick the vault, and select which secret names to expose. The YAML does not change at all — it is still `- group: prod-secrets`. What changes is where the value comes from: - Values are **fetched from the vault at run time**, at the start of the run, rather than being copied into Azure DevOps. Rotating the secret in the vault means the next run picks up the new value with no edit anywhere. - The service connection's identity needs **Get** and **List** permissions on the vault's secrets — `List` to enumerate the names in the UI, `Get` to read values during the run. A group that worked yesterday and returns nothing today is very often an expired service-principal credential or a changed vault access policy. - **Only secrets are supported.** Key Vault also stores keys and certificates; a linked variable group cannot surface those. - Every value arrives as a **secret variable**. ## The secret-variable behaviour that surprises people Secret variables are handled differently from ordinary ones, and the difference causes a specific, very common bug: ```yaml steps: - bash: | echo "len=${#API_KEY}" # prints 0 — not in the environment displayName: Broken - bash: | echo "len=${#API_KEY}" # correct env: API_KEY: $(apiKey) displayName: Working ``` Ordinary pipeline variables are mapped into each task's process environment automatically. **Secret variables are not** — precisely so that a rogue task or a process dump does not sweep them up for free. To use one inside a script you map it explicitly with `env:`, or you reference `$(apiKey)` directly in a task input, where the agent substitutes it. The failure mode is quiet: the script sees an empty string, and you get an authentication error from a downstream service rather than a message about the variable. Secret values are also **masked in the logs** — Azure replaces occurrences with `***`. Treat that as a backstop only: a script that base64-encodes or otherwise transforms the value before printing it defeats the masking entirely, because the agent is matching on the literal string. One further constraint follows from the timing: secrets exist only once the run starts, so a secret can never be read by a compile-time `${{ }}` expression. Anything that must *shape* the pipeline has to come from a parameter, not a secret. ## Choosing between the two Plain variable groups are fine for non-sensitive shared configuration — region names, feature toggles, image tags. Key Vault linkage earns its extra moving part when the values are real credentials: the vault owns rotation, access history and its own access policies, and Azure DevOps holds only a reference. The cost is one more identity to keep alive and one more failure mode (vault permissions) between a green pipeline and a red one.