feat: add support for environment variables in branch labels by robertcoltheart · Pull Request #4944 · GitTools/GitVersion

robertcoltheart · 2026-05-19T11:24:56Z

Description

Supports environment variable substitution in the label configuration for a branch using the established format used elsewhere. Fallbacks are also supported if the environment variable is not found. The changes are backwards compatible and should not fail for existing configuration.

Documentation detailing the changes has been added to configuration.md.

Related Issue

Resolves #4745

Motivation and Context

Allow labels to include environment variables as well as regex-captured variables. This is useful for CICD environments like GitHub where the pull request head_ref can be provided instead of the merge commit target.

How Has This Been Tested?

Unit tests covering the new functionality have been added.

Screenshots (if appropriate):

Checklist:

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have added tests to cover my changes.
All new and existing tests passed.

robertcoltheart · 2026-05-20T21:03:51Z

1 check is failing because the Nuke website is down.

robertcoltheart · 2026-05-30T12:12:27Z

-            return label;
+            var labelPlaceholders = BuildLabelPlaceholders(configuration.RegularExpression, effectiveBranchName);
+
+            return label.FormatWith(labelPlaceholders, environment);


Throws if environment variable is not found and has no fallback. This is deliberate to stay consistent with other usages of environment variables, for example in assembly file version.

robertcoltheart · 2026-05-31T04:31:30Z

@HHobeck @arturcic Fixed a couple of issues that I missed. This is ready for review and merge now, thanks!

HHobeck · 2026-05-31T10:53:04Z

Here are a few suggestions regarding this implementation:

Use object instead of generics: Change the generic type T to object. It makes more sense here since a generic type parameter provides no extra benefit for this use case.

Clarify supported types: The method currently supports instances of type object and IDictionary<string, object>, but this intent is not clearly expressed in the method body. I suggest splitting this into explicit overloads for better readability, like this:

internal static class StringFormatWithExtension { extension(string template) { public string FormatWith(object? source, IEnvironment environment) { object? GetFromSource(string value) { // ... } object? GetFromEnvironment(string value) => environment.GetEnvironmentVariable(value); return template.FormatWith(GetFromSource, GetFromEnvironment); } public string FormatWith(IDictionary<string, object> source, IEnvironment environment) { object? GetFromSource(string value) { source.TryGetValue(value, out var result); return result; } object? GetFromEnvironment(string value) => environment.GetEnvironmentVariable(value); return template.FormatWith(GetFromSource, GetFromEnvironment); } private string FormatWith( Func<string, object?> getFromSource, Func<string, object?> getFromEnvironment) { // ... } } }

Allow flexible placeholder combinations: It does not make sense to restrict how placeholders can occur. Why shouldn't all of the following combinations be valid?

{JustAProperty}

{JustAProperty ?? "JustAFallback"}

{JustAProperty} ?? {env:JustAVariable}

{JustAProperty} ?? {env:JustAVariable} ?? "JustAFallback"

{env:JustAVariable}

{env:JustAVariable} ?? "JustAFallback"

{env:JustAVariable} ?? {JustAProperty}

{env:JustAVariable} ?? {JustAProperty} ?? "JustAFallback"

1 and 2, fair enough, will make these changes.

For 3, it was written this way (and I'm guessing the original implementor in #4746 did it this way for the same reason) to remain compatible/easy to understand as the existing configuration options for label and for assembly-file-versioning-format, where the {env:} syntax is derived from. The understanding I have is that {Name} syntax is reserved for regex captures, whereas {env:} is used for environment variables. I think it would be more confusing given the language that the configuration has cultivated to conflate these 2 concepts.

If the longer-term intention is to further enhance the regex/env var to support this conflation, I'd suggest doing this in a follow up change rather than here. Let me know your thoughts on this.

For 3, it was written this way (and I'm guessing the original implementor in #4746 did it this way for the same reason) to remain compatible/easy to understand as the existing configuration options for label and for assembly-file-versioning-format, where the {env:} syntax is derived from. The understanding I have is that {Name} syntax is reserved for regex captures, whereas {env:} is used for environment variables. I think it would be more confusing given the language that the configuration has cultivated to conflate these 2 concepts.

Good question. @asbjornu @arturcic: What do you think?

Any thoughts on this guys?

I'm not sure I understand the following statement:

The understanding I have is that {Name} syntax is reserved for regex captures

From the documentation:

Expressions in curly braces reference one of the variables or a process-scoped environment variable (when prefixed with env:).

So for {Name}, Name would represent a GitVersion variable called Name. I think @HHobeck's example (in the configuration context):

assembly-file-versioning-format: '{env:JustAVariable} ?? {JustAProperty} ?? "JustAFallback"`'

Should be possible as follows:

assembly-file-versioning-format: '{env:JustAVariable ?? JustAProperty ?? "JustAFallback"}'

…the difference being the placement of the braces, which IIRC needs to embrace the entire expression. Whether one, two or multiple fallback values are possible already is not something I have tested, but I think it's something that should be supported.

Should be possible as follows:

assembly-file-versioning-format: '{env:JustAVariable ?? JustAProperty ?? "JustAFallback"}'

I agree. The would be the correction:

{JustAProperty}

{JustAProperty ?? "JustAFallback"}

{JustAProperty ?? env:JustAVariable}

{JustAProperty ?? env:JustAVariable ?? "JustAFallback"}

{env:JustAVariable}

{env:JustAVariable ?? "JustAFallback"}

{env:JustAVariable ?? JustAProperty}

{env:JustAVariable ?? JustAProperty ?? "JustAFallback"}

Fair enough, if that's the consensus I'll have a go at implementing it in this PR.

Awesome! But feel free to create a separate PR if you'd like.

arturcic · 2026-06-09T10:21:27Z

@robertcoltheart please rebase onto main and fix the sonarcloud

arturcic · 2026-06-10T07:07:34Z

@robertcoltheart could you please rebase instead of merging main into your branch? Thanks in advance. See https://github.com/GitTools/GitVersion/blob/main/CONTRIBUTING.md#git-history--pull-request-updates

arturcic · 2026-06-10T10:13:25Z

@robertcoltheart please fix the Sonar Cloud issue as well https://sonarcloud.io/project/issues?id=GitTools_GitVersion&pullRequest=4944&issueStatuses=OPEN,CONFIRMED&sinceLeakPeriod=true

arturcic · 2026-06-10T12:30:51Z

@robertcoltheart is there anything left to be fixed/implemented based on the feedback. I'm considering to prepare a new release soon and was wondering if we can include this in the new release

robertcoltheart · 2026-06-10T12:43:27Z

No I'm happy with this for now. I can address the updated fallback logic in a separate pull request.

arturcic · 2026-06-10T12:45:02Z

@asbjornu @HHobeck can you have a second review and approve it if you're fine with the current state

sonarqubecloud · 2026-06-10T20:03:56Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.9% Duplication on New Code

See analysis details on SonarQube Cloud

arturcic · 2026-06-10T20:37:15Z

@Mergifyio refresh

mergify · 2026-06-10T20:37:19Z

refresh

✅ Pull request refreshed

mergify · 2026-06-10T20:38:20Z

Thank you @robertcoltheart for your contribution!

arturcic reviewed May 19, 2026

View reviewed changes

Comment thread docs/input/docs/reference/configuration.md

arturcic requested a review from HHobeck May 22, 2026 16:16

robertcoltheart requested a review from arturcic May 26, 2026 22:53

robertcoltheart commented May 30, 2026

View reviewed changes

Comment thread docs/input/docs/learn/who.md

robertcoltheart commented May 30, 2026

View reviewed changes

HHobeck requested changes May 31, 2026

View reviewed changes

robertcoltheart force-pushed the feature/enhance-branch-label-with-env-vars branch from 854bae7 to 2627649 Compare June 10, 2026 10:08

arturcic mentioned this pull request Jun 10, 2026

Enhance branch label configuration with environment variable support #4746

Closed

HHobeck approved these changes Jun 10, 2026

View reviewed changes

robertcoltheart added 8 commits June 10, 2026 22:01

feat: add support for environment variables in branch labels

014ae33

docs: update configuration.source with environment vars for labels

91e1cb2

fix: remove unused using

ebe16d0

fix: remove unnecessary null check

7fd0dc7

fix: remove nuke.build due to failing dns

b5f47b2

fix: throw when env not found for consistency

1f26fa0

fix: add formatwith overload for dictionary

b762c23

fix: move branch name duplication to const

8d1e896

arturcic force-pushed the feature/enhance-branch-label-with-env-vars branch from d047baf to 8d1e896 Compare June 10, 2026 20:01

arturcic enabled auto-merge June 10, 2026 20:01

arturcic added this to the 6.x milestone Jun 10, 2026

arturcic added the feature label Jun 10, 2026

arturcic disabled auto-merge June 10, 2026 20:38

arturcic merged commit 375cb8d into GitTools:main Jun 10, 2026
218 of 219 checks passed

arturcic mentioned this pull request Jun 15, 2026

[ISSUE]: {BranchName} format strings for label not working #4976

Open

2 tasks

Conversation

robertcoltheart commented May 19, 2026

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Checklist:

Uh oh!

Uh oh!

robertcoltheart commented May 20, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robertcoltheart commented May 31, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arturcic commented Jun 9, 2026

Uh oh!

arturcic commented Jun 10, 2026

Uh oh!

arturcic commented Jun 10, 2026

Uh oh!

arturcic commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robertcoltheart commented Jun 10, 2026

Uh oh!

arturcic commented Jun 10, 2026

Uh oh!

sonarqubecloud Bot commented Jun 10, 2026

Quality Gate passed

Uh oh!

arturcic commented Jun 10, 2026

Uh oh!

mergify Bot commented Jun 10, 2026

✅ Pull request refreshed

Uh oh!

Uh oh!

mergify Bot commented Jun 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

arturcic commented Jun 10, 2026 •

edited

Loading