feat: add support for environment variables in branch labels

docs/input/docs/learn/who.md

@@ -12,7 +12,6 @@ that we know about today.
 * [ChocolateyGUI](https://github.com/chocolatey/ChocolateyGUI)
 * [GitLink](https://github.com/GitTools/GitLink)
 * [OctopusDeploy](https://github.com/OctopusDeploy)
-* [NUKE](https://nuke.build)
 * [Orc.\* packages](https://github.com/wildgums?query=orc)
 * [Orchestra](https://github.com/wildgums/orchestra)
 * [Shouldly](https://github.com/shouldly/shouldly)

docs/input/docs/reference/mdsource/configuration.source.md

@@ -504,6 +504,8 @@ of `alpha.foo` with `label: 'alpha.{BranchName}'` and `regex: '^features?[\/-](?
 
 Another example: branch `features/sc-12345/some-description` would become a pre-release label of `sc-12345` with `label: '{StoryNo}'` and `regex: '^features?[\/-](?<StoryNo>sc-\d+)[-/].+'`.
 
+You can also use environment variable placeholders with the `{env:VARIABLE_NAME}` syntax. Environment variable placeholders can also be combined with regex placeholders, for example `{BranchName}-{env:VARIABLE_NAME}`, and support fallback values using the `{env:VARIABLE_NAME ?? "fallback"}` syntax.
+
 **Note:** To clear a default use an empty string: `label: ''`
 
 ### increment

src/GitVersion.Configuration.Tests/Configuration/ConfigurationExtensionsTests.cs

@@ -6,6 +6,8 @@ namespace GitVersion.Configuration.Tests;
 [TestFixture]
 public class ConfigurationExtensionsTests : TestBase
 {
+    private const string BranchName = "pull-request";
+
     [TestCase("release/2.0.0",
         "refs/heads/release/2.0.0", "release/2.0.0", "release/2.0.0",
         true, false, false, false, true)]
@@ -51,7 +53,94 @@ public void EnsureGetBranchSpecificLabelWorksAsExpected(string branchName, strin
             .Build();
 
         var effectiveConfiguration = configuration.GetEffectiveConfiguration(ReferenceName.FromBranchName(branchName));
-        var actual = effectiveConfiguration.GetBranchSpecificLabel(ReferenceName.FromBranchName(branchName), null);
+        var actual = effectiveConfiguration.GetBranchSpecificLabel(ReferenceName.FromBranchName(branchName), null, new TestEnvironment());
         actual.ShouldBe(expectedLabel);
     }
+
+    [Test]
+    public void EnsureGetBranchSpecificLabelProcessesEnvironmentVariables()
+    {
+        var environment = new TestEnvironment();
+        environment.SetEnvironmentVariable("GITHUB_HEAD_REF", "feature-branch");
+
+        var configuration = GitFlowConfigurationBuilder.New
+            .WithoutBranches()
+            .WithBranch(BranchName, builder => builder
+                .WithLabel("pr-{env:GITHUB_HEAD_REF}")
+                .WithRegularExpression(@"^pull[/-]"))
+            .Build();
+
+        var effectiveConfiguration = configuration.GetEffectiveConfiguration(ReferenceName.FromBranchName(BranchName));
+        var actual = effectiveConfiguration.GetBranchSpecificLabel(ReferenceName.FromBranchName(BranchName), null, environment);
+        actual.ShouldBe("pr-feature-branch");
+    }
+
+    [Test]
+    public void EnsureGetBranchSpecificLabelProcessesEnvironmentVariablesWithFallback()
+    {
+        var environment = new TestEnvironment();
+        // Don't set GITHUB_HEAD_REF to test fallback
+
+        var configuration = GitFlowConfigurationBuilder.New
+            .WithoutBranches()
+            .WithBranch(BranchName, builder => builder
+                .WithLabel("pr-{env:GITHUB_HEAD_REF ?? \"unknown\"}")
+                .WithRegularExpression(@"^pull[/-]"))
+            .Build();
+
+        var effectiveConfiguration = configuration.GetEffectiveConfiguration(ReferenceName.FromBranchName(BranchName));
+        var actual = effectiveConfiguration.GetBranchSpecificLabel(ReferenceName.FromBranchName(BranchName), null, environment);
+        actual.ShouldBe("pr-unknown");
+    }
+
+    [Test]
+    public void EnsureGetBranchSpecificLabelProcessesEnvironmentVariablesAndRegexPlaceholders()
+    {
+        var environment = new TestEnvironment();
+        environment.SetEnvironmentVariable("GITHUB_HEAD_REF", "feature-branch");
+
+        var configuration = GitFlowConfigurationBuilder.New
+            .WithoutBranches()
+            .WithBranch("feature/test-branch", builder => builder
+                .WithLabel("{BranchName}-{env:GITHUB_HEAD_REF}")
+                .WithRegularExpression(@"^features?[\/-](?<BranchName>.+)"))
+            .Build();
+
+        var effectiveConfiguration = configuration.GetEffectiveConfiguration(ReferenceName.FromBranchName("feature/test-branch"));
+        var actual = effectiveConfiguration.GetBranchSpecificLabel(ReferenceName.FromBranchName("feature/test-branch"), null, environment);
+        actual.ShouldBe("test-branch-feature-branch");
+    }
+
+    [Test]
+    public void EnsureGetBranchSpecificLabelWorksWithoutEnvironmentWhenNoEnvPlaceholders()
+    {
+        var configuration = GitFlowConfigurationBuilder.New
+            .WithoutBranches()
+            .WithBranch("feature/test", builder => builder
+                .WithLabel("{BranchName}")
+                .WithRegularExpression(@"^features?[\/-](?<BranchName>.+)"))
+            .Build();
+
+        var effectiveConfiguration = configuration.GetEffectiveConfiguration(ReferenceName.FromBranchName("feature/test"));
+        var actual = effectiveConfiguration.GetBranchSpecificLabel(ReferenceName.FromBranchName("feature/test"), null, new TestEnvironment());
+        actual.ShouldBe("test");
+    }
+
+    [Test]
+    public void EnsureGetBranchSpecificLabelThrowsWhenThrowIfNotFoundAndEnvVarMissing()
+    {
+        var environment = new TestEnvironment();
+        // Do not set MISSING_VAR
+
+        var configuration = GitFlowConfigurationBuilder.New
+            .WithoutBranches()
+            .WithBranch(BranchName, builder => builder
+                .WithLabel("pr-{env:MISSING_VAR}")
+                .WithRegularExpression(@"^pull[/-]"))
+            .Build();
+
+        var effectiveConfiguration = configuration.GetEffectiveConfiguration(ReferenceName.FromBranchName(BranchName));
+        Should.Throw<ArgumentException>(() =>
+            effectiveConfiguration.GetBranchSpecificLabel(ReferenceName.FromBranchName(BranchName), null, environment));
+    }
 }

src/GitVersion.Core/Extensions/ConfigurationExtensions.cs

@@ -1,5 +1,6 @@
 using GitVersion.Core;
 using GitVersion.Extensions;
+using GitVersion.Formatting;
 using GitVersion.Git;
 using GitVersion.VersionCalculation;
 
@@ -97,38 +98,25 @@ private static bool ShouldBeIgnored(ICommit commit, IIgnoreConfiguration ignore)
 
     extension(EffectiveConfiguration configuration)
     {
-        public string? GetBranchSpecificLabel(ReferenceName branchName, string? branchNameOverride)
-            => GetBranchSpecificLabel(configuration, branchName.WithoutOrigin, branchNameOverride);
+        public string? GetBranchSpecificLabel(ReferenceName branchName, string? branchNameOverride, IEnvironment environment)
+            => GetBranchSpecificLabel(configuration, branchName.WithoutOrigin, branchNameOverride, environment);
 
-        public string? GetBranchSpecificLabel(string? branchName, string? branchNameOverride)
+        public string? GetBranchSpecificLabel(string? branchName, string? branchNameOverride, IEnvironment environment)
         {
             configuration.NotNull();
+            environment.NotNull();
 
             var label = configuration.Label;
+
             if (label is null)
             {
                 return label;
             }
 
             var effectiveBranchName = branchNameOverride ?? branchName;
-            if (configuration.RegularExpression.IsNullOrWhiteSpace() || effectiveBranchName.IsNullOrEmpty()) return label;
-            var regex = RegexPatterns.Cache.GetOrAdd(configuration.RegularExpression);
-            var match = regex.Match(effectiveBranchName);
-            if (!match.Success) return label;
-            foreach (var groupName in regex.GetGroupNames())
-            {
-                var groupValue = match.Groups[groupName].Value;
-                Lazy<string> escapedGroupValueLazy = new(() => groupValue.RegexReplace(RegexPatterns.SanitizeNameRegexPattern, "-"));
-                var placeholder = $"{{{groupName}}}";
-                int index, startIndex = 0;
-                while ((index = label.IndexOf(placeholder, startIndex, StringComparison.InvariantCulture)) >= 0)
-                {
-                    var escapedGroupValue = escapedGroupValueLazy.Value;
-                    label = label.Remove(index, placeholder.Length).Insert(index, escapedGroupValue);
-                    startIndex = index + escapedGroupValue.Length;
-                }
-            }
-            return label;
+            var labelPlaceholders = BuildLabelPlaceholders(configuration.RegularExpression, effectiveBranchName);
+
+            return label.FormatWith(labelPlaceholders, environment);
         }
 
         public TaggedSemanticVersions GetTaggedSemanticVersion()
@@ -153,5 +141,27 @@ public TaggedSemanticVersions GetTaggedSemanticVersion()
             }
             return taggedSemanticVersion;
         }
+
+        private static Dictionary<string, object> BuildLabelPlaceholders(string? regularExpression, string? effectiveBranchName)
+        {
+            var placeholders = new Dictionary<string, object>();
+
+            if (regularExpression.IsNullOrWhiteSpace() || effectiveBranchName.IsNullOrEmpty())
+                return placeholders;
+
+            var regex = RegexPatterns.Cache.GetOrAdd(regularExpression);
+            var match = regex.Match(effectiveBranchName);
+
+            if (!match.Success)
+                return placeholders;
+
+            foreach (var groupName in regex.GetGroupNames())
+            {
+                var groupValue = match.Groups[groupName].Value;
+                placeholders[groupName] = groupValue.RegexReplace(RegexPatterns.SanitizeNameRegexPattern, "-");
+            }
+
+            return placeholders;
+        }
     }
 }

src/GitVersion.Core/Formatting/StringFormatWithExtension.cs

@@ -37,17 +37,51 @@ internal static class StringFormatWithExtension
         /// "{env:BUILD_NUMBER}".FormatWith(new { }, env);
         /// "{env:BUILD_NUMBER ?? \"0\"}".FormatWith(new { }, env);
         /// </example>
-        public string FormatWith<T>(T? source, IEnvironment environment)
+        public string FormatWith(object source, IEnvironment environment)
+        {
+            ArgumentNullException.ThrowIfNull(source);
+
+            return template.FormatWith((member, format, fallback) => EvaluateMemberFromObject(source, member, format, fallback), environment);
+        }
+
+        /// <summary>
+        /// Formats the <paramref name="template"/>, replacing each expression wrapped in curly braces
+        /// with the corresponding property from the <paramref name="source"/> or <paramref name="environment"/>.
+        /// </summary>
+        /// <param name="source">The source object to apply to the <paramref name="template"/></param>
+        /// <param name="environment"></param>
+        /// <exception cref="ArgumentNullException">The <paramref name="template"/> is null.</exception>
+        /// <exception cref="ArgumentException">An environment variable was null and no fallback was provided.</exception>
+        /// <remarks>
+        /// An expression containing "." is treated as a property or field access on the <paramref name="source"/>.
+        /// An expression starting with "env:" is replaced with the value of the corresponding variable from the <paramref name="environment"/>.
+        /// Each expression may specify a single hardcoded fallback value using the {Prop ?? "fallback"} syntax, which applies if the expression evaluates to null.
+        /// </remarks>
+        /// <example>
+        /// // replace an expression with a property value
+        /// "Hello {Name}".FormatWith(new { Name = "Fred" }, env);
+        /// "Hello {Name ?? \"Fred\"}".FormatWith(new { Name = GetNameOrNull() }, env);
+        /// // replace an expression with an environment variable
+        /// "{env:BUILD_NUMBER}".FormatWith(new { }, env);
+        /// "{env:BUILD_NUMBER ?? \"0\"}".FormatWith(new { }, env);
+        /// </example>
+        public string FormatWith(IDictionary<string, object> source, IEnvironment environment)
         {
-            ArgumentNullException.ThrowIfNull(template);
             ArgumentNullException.ThrowIfNull(source);
 
+            return template.FormatWith((member, format, fallback) => EvaluateMemberFromDictionary(source, member, format, fallback), environment);
+        }
+
+        private string FormatWith(EvaluateMemberDelegate memberEvaluator, IEnvironment environment)
+        {
+            ArgumentNullException.ThrowIfNull(template);
+
             var result = new StringBuilder();
             var lastIndex = 0;
 
             foreach (var match in RegexPatterns.ExpandTokensRegex.Matches(template).Cast<Match>())
             {
-                var replacement = EvaluateMatch(match, source, environment);
+                var replacement = EvaluateMatch(match, memberEvaluator, environment);
                 result.Append(template, lastIndex, match.Index - lastIndex);
                 result.Append(replacement);
                 lastIndex = match.Index + match.Length;
@@ -58,7 +92,7 @@ public string FormatWith<T>(T? source, IEnvironment environment)
         }
     }
 
-    private static string EvaluateMatch<T>(Match match, T source, IEnvironment environment)
+    private static string EvaluateMatch(Match match, EvaluateMemberDelegate memberEvaluator, IEnvironment environment)
     {
         var fallback = match.Groups["fallback"].Success ? match.Groups["fallback"].Value : null;
 
@@ -68,7 +102,7 @@ private static string EvaluateMatch<T>(Match match, T source, IEnvironment envir
         if (match.Groups["member"].Success)
         {
             var format = match.Groups["format"].Success ? match.Groups["format"].Value : null;
-            return EvaluateMember(source, match.Groups["member"].Value, format, fallback);
+            return memberEvaluator(match.Groups["member"].Value, format, fallback);
         }
 
         throw new ArgumentException($"Invalid token format: '{match.Value}'");
@@ -82,7 +116,7 @@ private static string EvaluateEnvVar(string name, string? fallback, IEnvironment
             ?? throw new ArgumentException($"Environment variable {safeName} not found and no fallback provided");
     }
 
-    private static string EvaluateMember<T>(T source, string member, string? format, string? fallback)
+    private static string EvaluateMemberFromObject(object source, string member, string? format, string? fallback)
     {
         var safeMember = InputSanitizer.SanitizeMemberName(member);
         var memberPath = MemberResolver.ResolveMemberPath(source!.GetType(), safeMember);
@@ -93,13 +127,31 @@ private static string EvaluateMember<T>(T source, string member, string? format,
             return fallback ?? string.Empty;
 
         if (format is not null && ValueFormatter.Default.TryFormat(
-            value,
-            InputSanitizer.SanitizeFormat(format),
-            out var formatted))
+                value,
+                InputSanitizer.SanitizeFormat(format),
+                out var formatted))
         {
             return formatted;
         }
 
         return value.ToString() ?? fallback ?? string.Empty;
     }
+
+    private static string EvaluateMemberFromDictionary(IDictionary<string, object> source, string member, string? format, string? fallback)
+    {
+        var safeMember = InputSanitizer.SanitizeMemberName(member);
+
+        if (!source.TryGetValue(safeMember, out var value))
+            return fallback ?? string.Empty;
+
+        if (value is null)
+            return fallback ?? string.Empty;
+
+        if (format is not null && ValueFormatter.Default.TryFormat(value, InputSanitizer.SanitizeFormat(format), out var formatted))
+            return formatted;
+
+        return value.ToString() ?? fallback ?? string.Empty;
+    }
+
+    private delegate string EvaluateMemberDelegate(string member, string? format, string? fallback);
 }

src/GitVersion.Core/VersionCalculation/Mainline/EnrichIncrement.cs

@@ -19,7 +19,7 @@ public void Enrich(MainlineIteration iteration, MainlineCommit commit, MainlineC
 
         if (commit.Predecessor is not null && commit.Predecessor.BranchName != commit.BranchName)
             context.Label = null;
-        context.Label ??= effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null);
+        context.Label ??= effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null, context.Environment);
 
         if (effectiveConfiguration.IsMainBranch)
             context.BaseVersionSource = commit.Predecessor?.Value;

src/GitVersion.Core/VersionCalculation/Mainline/EnrichSemanticVersion.cs

@@ -9,9 +9,9 @@ public void Enrich(MainlineIteration iteration, MainlineCommit commit, MainlineC
     {
         var branchSpecificLabel = context.TargetLabel;
         branchSpecificLabel ??= iteration.GetEffectiveConfiguration(context.Configuration)
-            .GetBranchSpecificLabel(commit.BranchName, null);
+            .GetBranchSpecificLabel(commit.BranchName, null, context.Environemnt);
         branchSpecificLabel ??= commit.GetEffectiveConfiguration(context.Configuration)
-            .GetBranchSpecificLabel(commit.BranchName, null);
+            .GetBranchSpecificLabel(commit.BranchName, null, context.Environment);
 
         var semanticVersions = commit.SemanticVersions.Where(
             element => element.IsMatchForBranchSpecificLabel(branchSpecificLabel)

src/GitVersion.Core/VersionCalculation/Mainline/MainlineContext.cs

@@ -4,12 +4,14 @@
 
 namespace GitVersion.VersionCalculation.Mainline;
 
-internal record MainlineContext(IIncrementStrategyFinder IncrementStrategyFinder, IGitVersionConfiguration Configuration)
+internal record MainlineContext(IIncrementStrategyFinder IncrementStrategyFinder, IGitVersionConfiguration Configuration, IEnvironment Environment)
 {
     public IIncrementStrategyFinder IncrementStrategyFinder { get; } = IncrementStrategyFinder.NotNull();
 
     public IGitVersionConfiguration Configuration { get; } = Configuration.NotNull();
 
+    public IEnvironment Environemnt { get; } = Environment.NotNull();
+
     public string? TargetLabel { get; init; }
 
     public SemanticVersion? SemanticVersion { get; set; }

src/GitVersion.Core/VersionCalculation/Mainline/NonTrunk/CommitOnNonTrunk.cs

@@ -22,7 +22,7 @@ public IEnumerable<IBaseVersionIncrement> GetIncrements(
             context.Label = null;
 
         var effectiveConfiguration = commit.GetEffectiveConfiguration(context.Configuration);
-        context.Label ??= effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null);
+        context.Label ??= effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null, context.Environment);
 
         if (commit.Successor is not null) yield break;
         yield return new BaseVersionOperator

src/GitVersion.Core/VersionCalculation/Mainline/NonTrunk/CommitOnNonTrunkBranchedBase.cs

@@ -21,7 +21,7 @@ public virtual IEnumerable<IBaseVersionIncrement> GetIncrements(
         context.Increment = context.Increment.Consolidate(incrementForcedByBranch);
 
         var iterationEffectiveConfiguration = iteration.GetEffectiveConfiguration(context.Configuration);
-        context.Label = iterationEffectiveConfiguration.GetBranchSpecificLabel(iteration.BranchName, null) ?? context.Label;
+        context.Label = iterationEffectiveConfiguration.GetBranchSpecificLabel(iteration.BranchName, null, context.Environment) ?? context.Label;
         context.ForceIncrement = true;
 
         yield return new BaseVersionOperator

src/GitVersion.Core/VersionCalculation/Mainline/NonTrunk/CommitOnNonTrunkWithPreReleaseTagBase.cs

@@ -24,7 +24,7 @@ public virtual IEnumerable<IBaseVersionIncrement> GetIncrements(
 
         context.Increment = commit.GetIncrementForcedByBranch(context.Configuration);
         var effectiveConfiguration = commit.GetEffectiveConfiguration(context.Configuration);
-        context.Label = effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null);
+        context.Label = effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null, context.Environment);
         context.ForceIncrement = false;
     }
 }

src/GitVersion.Core/VersionCalculation/Mainline/NonTrunk/CommitOnNonTrunkWithStableTagBase.cs

@@ -24,6 +24,6 @@ public virtual IEnumerable<IBaseVersionIncrement> GetIncrements(
 
         context.Increment = commit.GetIncrementForcedByBranch(context.Configuration);
         var effectiveConfiguration = commit.GetEffectiveConfiguration(context.Configuration);
-        context.Label = effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null);
+        context.Label = effectiveConfiguration.GetBranchSpecificLabel(commit.BranchName, null, context.Environment);
     }
 }