Discuss replacing dotted Azure Pipelines output variable names

Decision needed

Should Azure Pipelines output variables keep their current dotted names, gain underscore aliases, or switch to a new naming convention in a breaking release?

The original proposal targeted v7. That is a proposed release scope, not an accepted compatibility decision.

Current behavior

AzurePipelines.SetOutputVariables emits both an ordinary variable and an output variable using the same dotted name:

• GitVersion.SemVer
• GitVersion.SemVer with isOutput=true

This behavior is distinct from environment-variable naming. Changing the emitted pipeline name requires checking consumers of both forms; do not assume that environment-name normalization makes a rename compatible.

Motivation

A consistent GitVersion_ prefix could make naming easier to explain across integrations. Before introducing a breaking change, identify a concrete problem with the current names and confirm whether aliases or clearer documentation would solve it.

Options

Option	Benefit	Cost
Keep dotted names	Preserves existing pipelines	Retains different naming conventions
Add underscore aliases	Allows gradual adoption	More emitted variables and a compatibility policy to maintain
Replace dotted names in a major release	Establishes one convention	Breaks consumers and requires coordinated migration

Initial recommendation: establish the consumer impact first. If consistency is the main benefit, evaluate additive aliases before removing existing names.

Investigation scope

• Inventory documentation, adapter tests, GitTools Actions integrations, and common pipeline templates that consume dotted names.
• Validate same-job access and output-variable access across jobs and stages.
• Check how ordinary variables and output variables become environment variables, including case and separator normalization.
• Define interaction with custom build-number templates and user-supplied variables.
• Identify name collisions and duplicate-output behavior if both naming schemes are emitted.
• Decide the target release and any deprecation period.

Decision criteria

• A concrete user problem and intended replacement names are documented.
• Same-job, cross-job, and cross-stage examples are tested in Azure Pipelines.
• Macro, expression, and environment access behavior is understood.
• Existing integrations and documentation have a migration plan.
• The selected option, release scope, and compatibility policy are recorded.

Open questions

• Is the goal to standardize names or fix a specific pipeline failure?
• Should aliases be permanent, opt-in, or temporary?
• Should ordinary and output variables follow the same transition?
• Is a breaking change justified for v7, or should this remain a later-release discussion?

No renaming or removal is implied until this decision is made.

Original issue

Moved from arturcic/GitVersion#589. GitHub does not support a direct transfer between these repository owners.

Triage — 16 September 2026

• Area: Azure Pipelines integration and output compatibility.
• Milestone: 7.0.x for a design decision before the v7 compatibility contract is finalized.
• Classification: improvement / question; potentially breaking if dotted names are removed.
• Next step: compare retaining names, adding aliases, and replacement using same-job and cross-job examples. Choose and document a compatibility policy before implementation.
• Release scope: this schedules the decision, not approval of removal. If the change is not justified or ready, explicitly retain current behavior and defer any breaking replacement.
• Tracking: direct sub-issue of GitTools/GitVersion#5137. No implementation dependency has been established.

Start with src/GitVersion.BuildAgents/Agents/AzurePipelines.cs and inventory the documentation, adapter tests, GitTools Actions integrations, and pipeline templates that consume dotted names. Validate same-job, cross-job, and cross-stage behavior, including environment normalization and custom variables. Done means the consumer impact, selected naming option, release scope, migration or deprecation policy, and compatibility decision are documented.