GitTools · mergify · Aug 1, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/BREAKING_CHANGES.md b/BREAKING_CHANGES.md
@@ -1,5 +1,18 @@
 ## Unreleased
 
+### Pre-release output variables renamed
+
+The pre-release output variables now use SemVer label terminology consistently:
+
+| Previous variable | Replacement | Example value |
+| --- | --- | --- |
+| `PreReleaseTag` | `PreReleaseLabel` | `beta.99` |
+| `PreReleaseTagWithDash` | `PreReleaseLabelWithDash` | `-beta.99` |
+| `PreReleaseLabel` | `PreReleaseLabelName` | `beta` |
+| `PreReleaseLabelWithDash` | `PreReleaseLabelNameWithDash` | `-beta` |
+
+The change applies to JSON output, formatting variables, build-agent environment variables, generated version-information files, and `GitVersion.MsBuild` outputs. `PreReleaseNumber` is unchanged.
+
 ### .NET 8 and .NET 9 target frameworks removed
 
 GitVersion now targets .NET 10 only. The CLI, global tool, and `GitVersion.MsBuild` require a .NET 10 runtime. The MSBuild integration continues to support projects targeting earlier frameworks through its `dotnet exec --roll-forward Major` launcher, provided .NET 10 is installed.

diff --git a/build/common/Addins/GitVersion/GitVersion.cs b/build/common/Addins/GitVersion/GitVersion.cs
@@ -77,32 +77,32 @@ public sealed class GitVersion
     public int? Patch { get; set; }
 
     /// <summary>
-    /// Gets or sets the pre-release label. The pre-release label is the name of the pre-release.
+    /// Gets or sets the pre-release label name without the numeric identifier.
     /// </summary>
-    public string? PreReleaseLabel { get; set; }
+    public string? PreReleaseLabelName { get; set; }
 
     /// <summary>
-    /// Gets or sets the pre-release label with dash. The pre-release label prefixed with a dash.
+    /// Gets or sets the pre-release label name prefixed with a dash.
     /// </summary>
-    public string? PreReleaseLabelWithDash { get; set; }
+    public string? PreReleaseLabelNameWithDash { get; set; }
 
     /// <summary>
     /// Gets or sets the pre-release number. The pre-release number is the number of commits since the last version bump.
     /// </summary>
     public int? PreReleaseNumber { get; set; }
 
     /// <summary>
-    /// Gets or sets the pre-release tag. The pre-release tag is the pre-release label suffixed by the PreReleaseNumber.
+    /// Gets or sets the full pre-release label, including the PreReleaseNumber when present.
     /// </summary>
-    public string? PreReleaseTag { get; set; }
+    public string? PreReleaseLabel { get; set; }
 
     /// <summary>
-    /// Gets or sets the pre-release tag with dash. The pre-release tag prefixed with a dash.
+    /// Gets or sets the pre-release label prefixed with a dash.
     /// </summary>
-    public string? PreReleaseTagWithDash { get; set; }
+    public string? PreReleaseLabelWithDash { get; set; }
 
     /// <summary>
-    /// Gets or sets the Semantic Version. The semantic version number, including PreReleaseTagWithDash for pre-release version numbers.
+    /// Gets or sets the Semantic Version. The semantic version number, including PreReleaseLabelWithDash for pre-release version numbers.
     /// </summary>
     public string? SemVer { get; set; }
 

diff --git a/build/common/Utilities/Models.cs b/build/common/Utilities/Models.cs
@@ -24,13 +24,13 @@ public static BuildVersion Calculate(GitVersion gitVersion)
         var nugetVersion = gitVersion.SemVer;
         var chocolateyVersion = gitVersion.MajorMinorPatch;
 
-        if (!string.IsNullOrWhiteSpace(gitVersion.PreReleaseTag))
+        if (!string.IsNullOrWhiteSpace(gitVersion.PreReleaseLabel))
         {
-            // Chocolatey does not support pre-release tags with dots, so we replace them with dashes
-            // if the pre-release tag is a number, we add a "a" prefix to the pre-release tag
+            // Chocolatey does not support pre-release labels with dots, so we replace them with dashes
+            // if the pre-release label name is a number, we add an "a" prefix to the pre-release label
             // the trick should be removed when Chocolatey supports semver 2.0
-            var prefix = int.TryParse(gitVersion.PreReleaseLabel, out _) ? "a" : string.Empty;
-            chocolateyVersion += $"-{prefix}{gitVersion.PreReleaseTag?.Replace(".", "-")}";
+            var prefix = int.TryParse(gitVersion.PreReleaseLabelName, out _) ? "a" : string.Empty;
+            chocolateyVersion += $"-{prefix}{gitVersion.PreReleaseLabel?.Replace(".", "-")}";
         }
 
         if (gitVersion.BuildMetaData is not null)

diff --git a/docs/input/docs/migration/v6-to-v7.md b/docs/input/docs/migration/v6-to-v7.md
@@ -6,6 +6,23 @@ Description: Migration guidance for upgrading from GitVersion v6 to GitVersion v
 
 This document summarizes the relevant breaking changes when migrating from GitVersion v6 to v7.
 
+## Pre-release output variables renamed
+
+The pre-release output variables now use SemVer terminology consistently. Update JSON consumers, `--show-variable` arguments, custom format strings, build-agent environment variables, generated version-information files, and `GitVersion.MsBuild` properties according to this mapping:
+
+| GitVersion v6 | GitVersion v7 | Example value |
+| --- | --- | --- |
+| `PreReleaseTag` | `PreReleaseLabel` | `beta.99` |
+| `PreReleaseTagWithDash` | `PreReleaseLabelWithDash` | `-beta.99` |
+| `PreReleaseLabel` | `PreReleaseLabelName` | `beta` |
+| `PreReleaseLabelWithDash` | `PreReleaseLabelNameWithDash` | `-beta` |
+
+`PreReleaseNumber` is unchanged. In MSBuild and build-agent environments, apply the same mapping to the `GitVersion_`-prefixed names. For example, `GitVersion_PreReleaseTag` becomes `GitVersion_PreReleaseLabel`.
+
+:::{.alert .alert-warning}
+`PreReleaseLabel` and `PreReleaseLabelWithDash` retain their names but change from the label name (`beta`) to the full label (`beta.99`). Consumers that require only the name must use `PreReleaseLabelName` and `PreReleaseLabelNameWithDash`.
+:::
+
 ## Intel macOS artifacts removed
 
 GitVersion v7 no longer ships native `osx-x64` artifacts. Apple Silicon (`osx-arm64`) is now the only supported macOS target. Intel Mac users should continue using the last GitVersion v6 release that shipped an `osx-x64` artifact.

diff --git a/docs/input/docs/reference/build-servers/octopus-deploy.md b/docs/input/docs/reference/build-servers/octopus-deploy.md
@@ -162,7 +162,7 @@ $nugetVersion = $versionInfo.NuGetVersion
 msbuild MyProj.sln
 
 # Only create nuget package for stable
-if ($versionInfo.PreReleaseTag -eq '')
+if ($versionInfo.PreReleaseLabel -eq '')
 {
     Write-Host
     Write-Host "Creating a release" -ForegroundColor Magenta

diff --git a/docs/input/docs/reference/configuration.md b/docs/input/docs/reference/configuration.md
@@ -999,7 +999,7 @@ This indicates that this branch is a main branch. By default `main` and `support
 
 ### pre-release-weight
 
-Provides a way to translate the `PreReleaseLabel` ([variables][variables]) to a numeric
+Provides a way to translate the `PreReleaseLabelName` ([variables][variables]) to a numeric
 value in order to avoid version collisions across different branches. For
 example, a release branch created after "1.2.3-alpha.55" results in
 "1.2.3-beta.1" and thus e.g. "1.2.3-alpha.4" and "1.2.3-beta.4" would have the

diff --git a/docs/input/docs/reference/custom-formatting.md b/docs/input/docs/reference/custom-formatting.md
@@ -18,7 +18,7 @@ For example, a PEP 440-compatible pre-release version can omit SemVer's dash and
 separator:
 
 ```yaml
-custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}'
+custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}'
 # 0.6.3-beta.10 becomes CustomVersion 0.6.3beta10
 ```
 
@@ -28,7 +28,7 @@ For example, a branch-specific format can override the global default:
 custom-version-format: '{SemVer}'
 branches:
   feature:
-    custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}'
+    custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}'
 ```
 
 A fixed-width numeric format can provide an increasing integer version for
@@ -64,7 +64,7 @@ You can now use standard .NET numeric format strings with version components:
 
 ```yaml
 # GitVersion.yml
-assembly-informational-format: "{Major}.{Minor}.{Patch:F2}-{PreReleaseLabel}"
+assembly-informational-format: "{Major}.{Minor}.{Patch:F2}-{PreReleaseLabelName}"
 ```
 
 **Supported Numeric Formats:**
@@ -114,7 +114,7 @@ branches:
   feature:
     label: "{BranchName:c}"  # Converts to PascalCase
 
-assembly-informational-format: "{Major}.{Minor}.{Patch}-{PreReleaseLabel:l}.{VersionSourceDistance:0000}"
+assembly-informational-format: "{Major}.{Minor}.{Patch}-{PreReleaseLabelName:l}.{VersionSourceDistance:0000}"
 ```
 
 **Template Usage:**

diff --git a/docs/input/docs/reference/mdsource/configuration.source.md b/docs/input/docs/reference/mdsource/configuration.source.md
@@ -600,7 +600,7 @@ This indicates that this branch is a main branch. By default `main` and `support
 
 ### pre-release-weight
 
-Provides a way to translate the `PreReleaseLabel` ([variables][variables]) to a numeric
+Provides a way to translate the `PreReleaseLabelName` ([variables][variables]) to a numeric
 value in order to avoid version collisions across different branches. For
 example, a release branch created after "1.2.3-alpha.55" results in
 "1.2.3-beta.1" and thus e.g. "1.2.3-alpha.4" and "1.2.3-beta.4" would have the

diff --git a/docs/input/docs/reference/variables.md b/docs/input/docs/reference/variables.md
@@ -25,11 +25,11 @@ what is available. For the `release/3.0.0` branch of GitVersion it shows:
     "MajorMinorPatch": "3.22.11",
     "Minor": 22,
     "Patch": 11,
-    "PreReleaseLabel": "beta",
-    "PreReleaseLabelWithDash": "-beta",
+    "PreReleaseLabelName": "beta",
+    "PreReleaseLabelNameWithDash": "-beta",
     "PreReleaseNumber": 99,
-    "PreReleaseTag": "beta.99",
-    "PreReleaseTagWithDash": "-beta.99",
+    "PreReleaseLabel": "beta.99",
+    "PreReleaseLabelWithDash": "-beta.99",
     "SemVer": "3.22.11-beta.99",
     "Sha": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
     "ShortSha": "28c8531",
@@ -60,12 +60,12 @@ Each property of the above JSON document is described in the below table.
 |           `MajorMinorPatch` | `Major`, `Minor` and `Patch` joined together, separated by `.`.                                                                                                            |
 |                     `Minor` | The minor version. Should be incremented on new features.                                                                                                                  |
 |                     `Patch` | The patch version. Should be incremented on bug fixes.                                                                                                                     |
-|           `PreReleaseLabel` | The pre-release label.                                                                                                                                                     |
-|   `PreReleaseLabelWithDash` | The pre-release label prefixed with a dash.                                                                                                                                |
+|       `PreReleaseLabelName` | The name of the pre-release label, without the `PreReleaseNumber`.                                                                                                         |
+| `PreReleaseLabelNameWithDash` | The pre-release label name prefixed with a dash.                                                                                                                         |
 |          `PreReleaseNumber` | The pre-release number.                                                                                                                                                    |
-|             `PreReleaseTag` | The pre-release tag is the pre-release label suffixed by the `PreReleaseNumber`.                                                                                           |
-|     `PreReleaseTagWithDash` | The pre-release tag prefixed with a dash.                                                                                                                                  |
-|                    `SemVer` | The semantical version number, including `PreReleaseTagWithDash` for pre-release version numbers.                                                                          |
+|           `PreReleaseLabel` | The full pre-release label, including the `PreReleaseNumber` when present.                                                                                                  |
+|   `PreReleaseLabelWithDash` | The pre-release label prefixed with a dash.                                                                                                                                |
+|                    `SemVer` | The semantic version number, including `PreReleaseLabelWithDash` for pre-release version numbers.                                                                          |
 |                       `Sha` | The SHA of the Git commit.                                                                                                                                                 |
 |                  `ShortSha` | The `Sha` limited to 7 characters.                                                                                                                                         |
 |        `UncommittedChanges` | The number of uncommitted changes present in the repository.                                                                                                               |

diff --git a/schemas/7.0/GitVersion.configuration.json b/schemas/7.0/GitVersion.configuration.json
@@ -112,7 +112,7 @@
             ]
           },
           "pre-release-weight": {
-            "description": "Provides a way to translate the PreReleaseLabel to a number.",
+            "description": "Provides a way to translate the PreReleaseLabelName to a number.",
             "type": [
               "null",
               "integer"
@@ -293,7 +293,7 @@
       ]
     },
     "pre-release-weight": {
-      "description": "Provides a way to translate the PreReleaseLabel to a number.",
+      "description": "Provides a way to translate the PreReleaseLabelName to a number.",
       "type": [
         "null",
         "integer"

diff --git a/schemas/7.0/GitVersion.json b/schemas/7.0/GitVersion.json
@@ -104,42 +104,42 @@
       ]
     },
     "PreReleaseLabel": {
-      "description": "The pre-release label is the name of the pre-release.",
+      "description": "The full pre-release label, including the PreReleaseNumber when present.",
       "type": [
         "null",
         "string"
       ]
     },
-    "PreReleaseLabelWithDash": {
-      "description": "The pre-release label prefixed with a dash.",
+    "PreReleaseLabelName": {
+      "description": "The name of the pre-release label, without the PreReleaseNumber.",
       "type": [
         "null",
         "string"
       ]
     },
-    "PreReleaseNumber": {
-      "description": "The pre-release number is the number of commits since the last version bump.",
+    "PreReleaseLabelNameWithDash": {
+      "description": "The pre-release label name prefixed with a dash.",
       "type": [
         "null",
-        "integer"
+        "string"
       ]
     },
-    "PreReleaseTag": {
-      "description": "The pre-release tag is the pre-release label suffixed by the PreReleaseNumber.",
+    "PreReleaseLabelWithDash": {
+      "description": "The pre-release label prefixed with a dash.",
       "type": [
         "null",
         "string"
       ]
     },
-    "PreReleaseTagWithDash": {
-      "description": "The pre-release tag prefixed with a dash.",
+    "PreReleaseNumber": {
+      "description": "The pre-release number is the number of commits since the last version bump.",
       "type": [
         "null",
-        "string"
+        "integer"
       ]
     },
     "SemVer": {
-      "description": "The semantic version number, including PreReleaseTagWithDash for pre-release version numbers.",
+      "description": "The semantic version number, including PreReleaseLabelWithDash for pre-release version numbers.",
       "type": [
         "null",
         "string"

diff --git a/src/GitVersion.App.Tests/ArgumentParserTests.cs b/src/GitVersion.App.Tests/ArgumentParserTests.cs
@@ -450,10 +450,10 @@ private static IEnumerable<TestCaseData> OverrideConfigWithSingleOptionTestData(
             }
         );
         yield return new TestCaseData(
-            "custom-version-format=\"{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}\"",
+            "custom-version-format=\"{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}\"",
             new GitVersionConfiguration
             {
-                CustomVersionFormat = "{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}"
+                CustomVersionFormat = "{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}"
             }
         );
         yield return new TestCaseData(

diff --git a/src/GitVersion.App.Tests/LegacyArgumentParserTests.cs b/src/GitVersion.App.Tests/LegacyArgumentParserTests.cs
@@ -440,10 +440,10 @@ private static IEnumerable<TestCaseData> OverrideConfigWithSingleOptionTestData(
             }
         );
         yield return new TestCaseData(
-            "custom-version-format=\"{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}\"",
+            "custom-version-format=\"{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}\"",
             new GitVersionConfiguration
             {
-                CustomVersionFormat = "{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}"
+                CustomVersionFormat = "{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}"
             }
         );
         yield return new TestCaseData(

diff --git a/src/GitVersion.Configuration.Tests/Configuration/ConfigurationProviderTests.cs b/src/GitVersion.Configuration.Tests/Configuration/ConfigurationProviderTests.cs
@@ -245,12 +245,12 @@ public void CanUpdateAssemblyInformationalVersioningSchemeWithFullSemVer()
     [Test]
     public void CanReadCustomVersionFormat()
     {
-        const string text = "custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}'";
+        const string text = "custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}'";
         using var _ = this.fileSystem.SetupConfigFile(path: this.repoPath, text: text);
 
         var configuration = this.configurationProvider.ProvideForDirectory(this.repoPath);
 
-        configuration.CustomVersionFormat.ShouldBe("{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}");
+        configuration.CustomVersionFormat.ShouldBe("{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}");
     }
 
     [Test]
@@ -260,14 +260,14 @@ public void CanReadBranchSpecificCustomVersionFormat()
                             custom-version-format: '{SemVer}'
                             branches:
                               feature:
-                                custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}'
+                                custom-version-format: '{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}'
                             """;
         using var _ = this.fileSystem.SetupConfigFile(path: this.repoPath, text: text);
 
         var configuration = this.configurationProvider.ProvideForDirectory(this.repoPath);
 
         configuration.CustomVersionFormat.ShouldBe("{SemVer}");
-        configuration.Branches["feature"].CustomVersionFormat.ShouldBe("{Major}.{Minor}.{Patch}{PreReleaseLabel:l}{PreReleaseNumber}");
+        configuration.Branches["feature"].CustomVersionFormat.ShouldBe("{Major}.{Minor}.{Patch}{PreReleaseLabelName:l}{PreReleaseNumber}");
     }
 
     [Test]

diff --git a/src/GitVersion.Configuration/BranchConfiguration.cs b/src/GitVersion.Configuration/BranchConfiguration.cs
@@ -76,7 +76,7 @@ internal record BranchConfiguration : IBranchConfiguration
     public bool? IsMainBranch { get; set; }
 
     [JsonPropertyName("pre-release-weight")]
-    [JsonPropertyDescription("Provides a way to translate the PreReleaseLabel to a number.")]
+    [JsonPropertyDescription("Provides a way to translate the PreReleaseLabelName to a number.")]
     public int? PreReleaseWeight { get; set; }
 
     public virtual IBranchConfiguration Inherit(IBranchConfiguration configuration)

diff --git a/src/GitVersion.Core.Tests/Core/GitVersionExecutorTests.cs b/src/GitVersion.Core.Tests/Core/GitVersionExecutorTests.cs
@@ -36,11 +36,11 @@ public class GitVersionExecutorTests : TestBase
           "MajorMinorPatch": "4.10.3",
           "Minor": 10,
           "Patch": 3,
-          "PreReleaseLabel": "test",
-          "PreReleaseLabelWithDash": "-test",
+          "PreReleaseLabel": "test.19",
+          "PreReleaseLabelName": "test",
+          "PreReleaseLabelNameWithDash": "-test",
+          "PreReleaseLabelWithDash": "-test.19",
           "PreReleaseNumber": 19,
-          "PreReleaseTag": "test.19",
-          "PreReleaseTagWithDash": "-test.19",
           "SemVer": "4.10.3-test.19",
           "Sha": "dd2a29aff0c948e1bdf3dabbe13e1576e70d5f9f",
           "ShortSha": "dd2a29af",

diff --git a/src/GitVersion.Core.Tests/Helpers/TestableGitVersionVariables.cs b/src/GitVersion.Core.Tests/Helpers/TestableGitVersionVariables.cs
@@ -17,11 +17,11 @@ internal record TestableGitVersionVariables() : GitVersionVariables(
     MajorMinorPatch: "",
     Minor: "",
     Patch: "",
+    PreReleaseLabelName: "",
+    PreReleaseLabelNameWithDash: "",
+    PreReleaseNumber: "",
     PreReleaseLabel: "",
     PreReleaseLabelWithDash: "",
-    PreReleaseNumber: "",
-    PreReleaseTag: "",
-    PreReleaseTagWithDash: "",
     SemVer: "",
     Sha: "",
     ShortSha: "",