🪲 [Fix]: Release tags keep the configured version prefix (#440)

MariusStorhaug · Copilot · web-flow · commit 1653be8d3660 · 2026-08-03T03:18:18.000+02:00
Releases created by the module pipeline are tagged with the version prefix configured in `.github/PSModule.yml` again. A repository that keeps the default `VersionPrefix: 'v'` is tagged `v1.1.10`, not `1.1.10`, and its prereleases are tagged `v1.1.11-mybranch001`. A repository that sets `VersionPrefix: ''` keeps its unprefixed tags exactly as before. ## Fixed: release tags no longer lose the configured version prefix Since v6 the release tag was built from the compiled manifest's `ModuleVersion` alone. That value is `Major.Minor.Patch` by definition, so the prefix had nowhere to live and every repository publishing on v6 with the default prefix picked up a tag that did not match its own history — `PSModule/Toml` went from `v0.0.1` to `0.0.2`, `PSModule/Domeneshop` from `v0.0.2` to `1.0.0`, `PSModule/PSSemVer` from `v1.1.9` to `1.1.10`. Nothing needs to change in a module repository. The prefix is read from the setting that already exists: ```yaml Publish: Module: VersionPrefix: 'v' # default; set to '' for unprefixed tags ``` **The prefix applies to the GitHub release tag and to nothing else.** A PowerShell module manifest's `ModuleVersion` and a PowerShell Gallery package version only accept plain SemVer, so the version published to the Gallery, the version in the Gallery link, and the name of the module zip attached to the release all stay unprefixed. With `VersionPrefix: 'v'` a release looks like this: | | Value | | --- | --- | | GitHub release tag and title | `v1.1.10` | | PowerShell Gallery version | `1.1.10` | | Manifest `ModuleVersion` | `1.1.10` | | Attached artifact | `MyModule-1.1.10.zip` | Repositories that already published an unprefixed tag on v6 keep it. Those releases are public, their artifacts are linked from the release pages, and the PowerShell Gallery listing points at them, so they are left alone and the prefix resumes from the next release. An unprefixed tag left in the history does not affect future version resolution. --- <details> <summary>Technical details</summary> **What changed** - `.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1` — new action-scoped helper module with `Get-ModuleVersionString`, which composes the module's SemVer string, and `Get-ReleaseTag`, which prefixes it. - `.github/actions/Publish-PSModule/src/publish.ps1` — reads the new `VersionPrefix` input, derives both version strings from those helpers in one place, and reports both in the resolved-version summary and the closing log line. - `.github/actions/Publish-PSModule/action.yml` — new optional `VersionPrefix` input, defaulting to `''`. - `.github/workflows/Publish-Module.yml` — passes `Settings.Publish.Module.VersionPrefix` into the action. - `.github/actions/Publish-PSModule/tests/Publish-PSModule.Helpers.Tests.ps1` — new Pester suite, picked up automatically by the existing `Test-Actions` discovery over `.github/actions/*/tests`. Five files, all on the tag-derivation path. No test fixture or pipeline behaviour outside it changes. **Approach** The manifest stays the source of the numeric version. `ModuleVersion` is what was built, tested, and pushed to the Gallery, so the tag has to agree with it — the `^\d+\.\d+\.\d+$` guard and the `999.0.0` placeholder check are unchanged. Only the prefix, the one piece of the tag the manifest cannot carry, is taken from the settings the Plan job already resolves. Composing the two is equivalent to using `Resolution.FullVersion` in the normal case and stays anchored to the artifact if the two ever disagree. **Keeping the prefix off the module version.** `publish.ps1` previously built the Gallery version with its own copy of the prerelease composition, independent of the tag. Two independent implementations of the same string is how they drift, and drift in this direction means a prefixed version reaching `Publish-PSResource`. Both now come from `Get-ModuleVersionString`; `Get-ReleaseTag` is that string with the prefix in front, so the prefix is the only possible difference between them, by construction rather than by convention. The prefix reaches: the release tag, the release title fallback, the `gh release upload` target, the release URL, the GitHub half of the pull request comment, and `PSMODULE_PUBLISH_PSMODULE_CONTEXT_ReleaseTag` for cleanup. It reaches nothing else. `publish.ps1` never writes to the manifest — it is read-only on the artifact by design — and `Build-PSModule` stamps the manifest from `Resolution.Version` and `Resolution.Prerelease`, which are unprefixed. `Resolution.FullVersion`, the one prefix-bearing value in the Settings object, is consumed by no downstream job. `Get-ModuleVersionString` and `Get-ReleaseTag` both trim their inputs, because prefix and label arrive through environment variables, and both treat a whitespace-only prerelease label as a stable release. **Verification — unit tests, red then green in CI** | Commit | Change | `Test actions` | | --- | --- | --- | | `fd2c7d9` | Extract tag derivation into a helper, no behavior change | success | | `d0f8f7a` | Add the regression test | **failure** (13 of 15) | | `06b4714` | Apply the configured version prefix | success (15 of 15) | 32 cases now. Alongside the prefixed and unprefixed tag shapes, absent and null prefixes, whitespace normalization, and the tag shape `Cleanup-PSModulePrereleases` depends on, a `the prefix reaches the release tag and nothing else` context pins the separation directly: - for five prefix/version/label combinations, the tag equals `$Prefix` + the module version string; - the module version string never begins with the prefix and always matches `^\d+\.\d+\.\d+(-[0-9A-Za-z\-.]+)?$`; - `Get-ModuleVersionString` has no `VersionPrefix` parameter at all, so a caller cannot pass one; - an unprefixed repository gets two identical strings, and stripping `v` from a prefixed tag returns the module version string. **Verification — the wiring, observed once in CI on an interim commit** This bug was a wiring failure, not a logic failure. `VersionPrefix` was resolved correctly by the Plan job and present in the Settings JSON; it simply never reached the tag. Unit tests prove the helpers compose correctly given the right input — they cannot prove that `fromJson(inputs.Settings).Publish.Module.VersionPrefix` → action input → `PSMODULE_PUBLISH_PSMODULE_INPUT_VersionPrefix` → `$versionPrefix` delivers the value. `Publish-Module` is skipped at the *job* level in every self-test run — `Publish.Module.Enabled` is `(ReleaseType -ne 'None') -or shouldAutoCleanup`, and an open pull request satisfies neither without a prerelease label — so the self-test does not exercise that chain on this diff. To close that gap once, an interim commit on this branch added `Fix` to a fixture's `PrereleaseLabels`, which made the self-test run the publish path under `WhatIf`. That commit has since been reset and is **not part of this pull request**; the observation below is from [run 30759608449](https://github.com/PSModule/Process-PSModule/actions/runs/30759608449) and is reported as a one-time measurement, not as coverage this change carries forward. ```text Module name: [PSModuleTest] Version prefix: [v] WhatIf: [True] ``` ```text ModuleVersion : 6.1.16 VersionPrefix : v Prerelease : fixversionprefixreleasetag001 CreatePrerelease : True ReleaseTag : v6.1.16-fixversionprefixreleasetag001 ``` ```text WhatIf: gh release create v6.1.16-fixversionprefixreleasetag001 --title v6.1.16-fixversionprefixreleasetag001 --notes-file /tmp/tmpjar7Eu.tmp --target fix-version-prefix-release-tag --prerelease ``` Nothing was published in that run: `Publish-PSResource` was logged rather than executed, no release or tag was created, and the `Release` workflow on the same push reported `Create a prerelease: [False]` / `Skipping release creation.` Standing publish-path coverage in CI is the subject of #436. **Verification — locally, outside CI** `publish.ps1` run end to end in `WhatIf` mode against a fabricated artifact, all four combinations, re-run after the separation change. Every line below is from those runs: | Prefix | Prerelease | Gallery version | Release tag | Artifact | Exported `…_CONTEXT_ReleaseTag` | | --- | --- | --- | --- | --- | --- | | `v` | — | `1.1.10` | `v1.1.10` | `PSModuleTest-1.1.10.zip` | `v1.1.10` | | `v` | `mybranch001` | `1.1.11-mybranch001` | `v1.1.11-mybranch001` | `PSModuleTest-1.1.11-mybranch001.zip` | `v1.1.11-mybranch001` | | `''` | — | `1.1.10` | `1.1.10` | `PSModuleTest-1.1.10.zip` | `1.1.10` | | `''` | `mybranch001` | `1.1.11-mybranch001` | `1.1.11-mybranch001` | `PSModuleTest-1.1.11-mybranch001.zip` | `1.1.11-mybranch001` | The first row is the `PSModule/PSSemVer` case from the bug report, which produced tag `1.1.10` before this change. The Gallery link and comment carried the unprefixed version in every run: ```text Publishing complete. PowerShell Gallery version: [1.1.10]. GitHub release tag: [v1.1.10]. gh pr comment 42 -b '✅ New release: PowerShell Gallery - [PSModuleTest 1.1.10](https://www.powershellgallery.com/packages/PSModuleTest/1.1.10)' ``` `AutoCleanup` was verified the same way, running `cleanup.ps1` against fixture release lists with the `gh` CLI shadowed. It keys off `tagName -like "*$prereleaseName*"`, which is prefix-agnostic, and excludes the published release by comparing `tagName` to `PSMODULE_PUBLISH_PSMODULE_CONTEXT_ReleaseTag`, which is now prefixed on both sides: | Repository | Published tag | Deleted | Excluded | | --- | --- | --- | --- | | Prefixed | `v1.1.11-mybranch003` | `v1.1.11-mybranch002`, `v1.1.11-mybranch001` | published tag, `v1.1.10`, another branch's prerelease | | Unprefixed | `1.1.11-mybranch003` | `1.1.11-mybranch002`, `1.1.11-mybranch001` | published tag, `1.1.10`, another branch's prerelease | | Mixed history — unprefixed leftovers from v6 | `v1.1.11-mybranch003` | `1.1.11-mybranch002`, `1.1.11-mybranch001` | published tag | | Stable release run | `v1.1.11` | all three branch prereleases | published tag | The mixed row is the migration case: a repository whose open pull request already has unprefixed prerelease tags created by the current v6 still has them cleaned up after this change. `Invoke-ScriptAnalyzer -Recurse -Settings .github/linters/.powershell-psscriptanalyzer.psd1` reports no findings for the action. **What is verified where** | Path | Evidence | | --- | --- | | Settings → action input → env var → `$versionPrefix` | One-time CI observation above; not covered by this diff going forward | | Prefix reaches the release tag and nothing else | Unit tests, plus all four local end-to-end runs | | Prefixed stable and prerelease tags | Unit tests, plus local end-to-end runs | | Unprefixed stable and prerelease tags | Unit tests, plus local end-to-end runs | | `AutoCleanup` tag matching, prefixed / unprefixed / mixed history | Local runs of `cleanup.ps1` against fixture release lists | **Implementation plan progress** Completes every step of the plan in #439 — regression test confirmed failing first, tag derivation changed, prefixed and unprefixed fixtures plus the `AutoCleanup` path re-run. The two decisions the issue records are answered in [a comment on it](#439 (comment)): the already-published unprefixed tags are left in place, and the prefix-consistency warning is carried by #441 rather than widened into this pull request. **Standards and framework alignment** | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `.github/actions/Publish-PSModule/src/**` (PowerShell) | PowerShell Functions, Naming, Messaging, Error Handling | GitHub Actions — helper modules named after the action | Aligned | | `.github/actions/Publish-PSModule/tests/**` (Pester) | Testing, PowerShell Testing | Action unit-test discovery in `Test-Actions.yml` | Aligned | | `.github/actions/Publish-PSModule/action.yml` (GitHub Actions) | GitHub Actions — behavior driven by inputs, defaults only at the interface layer | Action contract | Aligned | | `.github/actions/Publish-PSModule/` (folder conventions) | GitHub Actions — entry script named `main.ps1`, README per action | Action contract | Exception — #442 | | `.github/workflows/Publish-Module.yml` (GitHub Actions) | GitHub Actions | Reusable workflow contract | Aligned | The helper module is named after the action, per the standard, and matches the existing `Resolve-PSModuleVersion.Helpers.psm1`. The entry script here is `src/publish.ps1` rather than `src/main.ps1` and the action has no README; both predate this change and apply to `Cleanup-PSModulePrereleases` too, so they are carried by #442 instead of being renamed inside a bugfix. **Issue convergence sweep** Scoped to the publish and version-resolution surface: open issues in this repository touching `Publish-PSModule`, `Resolve-PSModuleVersion`, `Cleanup-PSModulePrereleases`, release tags, or versioning. #439 is the only one this diff fully satisfies. #438 (v5 to v6 migration) is affected by the fix but not delivered by it — the 48 repositories still on v5 need this merged and released before they migrate, so it is linked as context. #436 is linked as context only; this diff does not advance it. #441, #442, and #443 were opened by this session for findings deliberately left out of scope. </details> <details> <summary>Relevant issues (or links)</summary> - Fixes #439 - #436 - #438 - #441 - #442 - #443 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
diff --git a/.github/actions/Publish-PSModule/action.yml b/.github/actions/Publish-PSModule/action.yml
@@ -37,6 +37,13 @@ inputs:
     description: Name of the uploaded artifact to download. Must match the name used in the upstream upload-artifact step.
     required: false
     default: module
+  VersionPrefix:
+    description: |
+      Prefix put in front of the version in the git tag of the GitHub release, for example 'v'.
+      Comes from Settings.Publish.Module.VersionPrefix, which the Plan job resolves. The compiled manifest carries the module version as
+      Major.Minor.Patch and cannot carry the prefix, so it is supplied here. An empty value tags the release without a prefix.
+    required: false
+    default: ''
 
 runs:
   using: composite
@@ -65,4 +72,5 @@ runs:
         PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRBodyAsReleaseNotes: ${{ inputs.UsePRBodyAsReleaseNotes }}
         PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRTitleAsReleaseName: ${{ inputs.UsePRTitleAsReleaseName }}
         PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRTitleAsNotesHeading: ${{ inputs.UsePRTitleAsNotesHeading }}
+        PSMODULE_PUBLISH_PSMODULE_INPUT_VersionPrefix: ${{ inputs.VersionPrefix }}
       run: ${{ github.action_path }}/src/publish.ps1
diff --git a/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1 b/.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1
@@ -0,0 +1,104 @@
+﻿function Get-ModuleVersionString {
+    <#
+        .SYNOPSIS
+        Builds the SemVer version string that identifies the module itself.
+
+        .DESCRIPTION
+        Composes the module version and, when there is one, the prerelease label. This is the string the
+        PowerShell Gallery and the module manifest understand: `Major.Minor.Patch` optionally followed by
+        `-<prerelease>`. It never carries the repository's version prefix, because neither the manifest's
+        `ModuleVersion` nor a Gallery package version accepts one.
+
+        .OUTPUTS
+        String with the module version.
+
+        .EXAMPLE
+        Get-ModuleVersionString -ModuleVersion '1.1.10'
+
+        Returns '1.1.10'.
+
+        .EXAMPLE
+        Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+
+        Returns '1.1.10-mybranch001'.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        # The module version from the compiled manifest, in Major.Minor.Patch format.
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string] $ModuleVersion,
+
+        # The prerelease label from the compiled manifest. Empty for a stable release.
+        [Parameter()]
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $Prerelease
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Prerelease)) {
+        return $ModuleVersion
+    }
+
+    "$ModuleVersion-$($Prerelease.Trim())"
+}
+
+function Get-ReleaseTag {
+    <#
+        .SYNOPSIS
+        Builds the git tag used for the GitHub release.
+
+        .DESCRIPTION
+        Prefixes the module's SemVer version string with the configured version prefix. The version comes
+        from the compiled manifest, which is the artifact that is published, so the tag always names the
+        exact bytes that were tested and pushed to the PowerShell Gallery. The manifest's ModuleVersion is
+        Major.Minor.Patch by definition and cannot carry the prefix, so the prefix is supplied from the
+        resolved settings (Publish.Module.VersionPrefix) instead.
+
+        The prefix belongs to the GitHub release tag and to nothing else. PowerShell manifests and Gallery
+        package versions only accept plain SemVer, so callers that need the module's own version use
+        Get-ModuleVersionString. Deriving both from the same composition keeps the prefix as the only
+        difference between them.
+
+        .OUTPUTS
+        String with the release tag.
+
+        .EXAMPLE
+        Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10'
+
+        Returns 'v1.1.10'.
+
+        .EXAMPLE
+        Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+
+        Returns 'v1.1.10-mybranch001'.
+
+        .EXAMPLE
+        Get-ReleaseTag -VersionPrefix '' -ModuleVersion '1.1.10'
+
+        Returns '1.1.10'.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        # The module version from the compiled manifest, in Major.Minor.Patch format.
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string] $ModuleVersion,
+
+        # The prefix put in front of the version, for example 'v'. Empty for an unprefixed repository.
+        [Parameter()]
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $VersionPrefix,
+
+        # The prerelease label from the compiled manifest. Empty for a stable release.
+        [Parameter()]
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $Prerelease
+    )
+
+    "$($VersionPrefix.Trim())$(Get-ModuleVersionString -ModuleVersion $ModuleVersion -Prerelease $Prerelease)"
+}
diff --git a/.github/actions/Publish-PSModule/src/publish.ps1 b/.github/actions/Publish-PSModule/src/publish.ps1
@@ -28,6 +28,7 @@ param()
 $PSStyle.OutputRendering = 'Ansi'
 
 Import-Module -Name 'PSModule' -Force
+Import-Module -Name "$PSScriptRoot/Publish-PSModule.Helpers.psm1" -Force
 
 #region Load inputs
 LogGroup 'Load inputs' {
@@ -58,10 +59,14 @@ LogGroup 'Load inputs' {
     $usePRBodyAsReleaseNotes = $env:PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRBodyAsReleaseNotes -eq 'true'
     $usePRTitleAsReleaseName = $env:PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRTitleAsReleaseName -eq 'true'
     $usePRTitleAsNotesHeading = $env:PSMODULE_PUBLISH_PSMODULE_INPUT_UsePRTitleAsNotesHeading -eq 'true'
+    # The prefix the repository tags releases with, resolved by the Plan job from
+    # Settings.Publish.Module.VersionPrefix. Empty means the repository tags without a prefix.
+    $versionPrefix = $env:PSMODULE_PUBLISH_PSMODULE_INPUT_VersionPrefix
 
-    Write-Host "Module name: [$name]"
-    Write-Host "Module path: [$modulePath]"
-    Write-Host "WhatIf:      [$whatIf]"
+    Write-Host "Module name:    [$name]"
+    Write-Host "Module path:    [$modulePath]"
+    Write-Host "Version prefix: [$versionPrefix]"
+    Write-Host "WhatIf:         [$whatIf]"
 }
 #endregion Load inputs
 
@@ -129,12 +134,18 @@ LogGroup 'Resolve version from manifest' {
         $createPrerelease = $true
     }
 
-    $releaseTag = if ($createPrerelease) { "$moduleVersion-$prerelease" } else { $moduleVersion }
+    # The PowerShell Gallery and the module manifest only accept plain SemVer, so the configured
+    # VersionPrefix is applied to the GitHub release tag and to nothing else. Both strings are derived
+    # from the same composition here, so the prefix is the only difference between them.
+    $publishPSVersion = Get-ModuleVersionString -ModuleVersion $moduleVersion -Prerelease $prerelease
+    $releaseTag = Get-ReleaseTag -VersionPrefix $versionPrefix -ModuleVersion $moduleVersion -Prerelease $prerelease
 
     [PSCustomObject]@{
         ModuleVersion    = $moduleVersion
+        VersionPrefix    = $versionPrefix
         Prerelease       = $prerelease
         CreatePrerelease = $createPrerelease
+        GalleryVersion   = $publishPSVersion
         ReleaseTag       = $releaseTag
         PRNumber         = $prNumber
         PRHeadRef        = $prHeadRef
@@ -154,7 +165,6 @@ LogGroup 'Install module dependencies' {
 #region Publish to PSGallery
 LogGroup 'Publish to PSGallery' {
     $releaseType = if ($createPrerelease) { 'New prerelease' } else { 'New release' }
-    $publishPSVersion = if ($createPrerelease) { "$moduleVersion-$prerelease" } else { $moduleVersion }
     $psGalleryReleaseLink = "https://www.powershellgallery.com/packages/$name/$publishPSVersion"
 
     Write-Host 'Publish module to PowerShell Gallery using API key from environment.'
@@ -280,4 +290,4 @@ LogGroup 'Create GitHub release' {
 }
 #endregion Create GitHub release
 
-Write-Host "Publishing complete. Version: [$releaseTag]"
+Write-Host "Publishing complete. PowerShell Gallery version: [$publishPSVersion]. GitHub release tag: [$releaseTag]."
diff --git a/.github/actions/Publish-PSModule/tests/Publish-PSModule.Helpers.Tests.ps1 b/.github/actions/Publish-PSModule/tests/Publish-PSModule.Helpers.Tests.ps1
@@ -0,0 +1,167 @@
+﻿[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseDeclaredVarsMoreThanAssignments', '',
+    Justification = 'Variables are assigned in BeforeAll and used inside It blocks.'
+)]
+[CmdletBinding()]
+param()
+
+BeforeAll {
+    Import-Module -Name 'PSModule' -Force
+    Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../src/Publish-PSModule.Helpers.psm1') -Force
+}
+
+Describe 'Publish-PSModule.Helpers' {
+    Describe 'Get-ModuleVersionString' {
+        Context 'Get-ModuleVersionString - SemVer only, never prefixed' {
+            It 'Get-ModuleVersionString - returns the module version for a stable release' {
+                Get-ModuleVersionString -ModuleVersion '1.1.10' | Should -Be '1.1.10'
+            }
+
+            It 'Get-ModuleVersionString - appends the prerelease label' {
+                Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease 'mybranch001' |
+                    Should -Be '1.1.10-mybranch001'
+            }
+
+            It 'Get-ModuleVersionString - treats an empty prerelease label as a stable release' {
+                Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease '' | Should -Be '1.1.10'
+            }
+
+            It 'Get-ModuleVersionString - treats a whitespace-only prerelease label as a stable release' {
+                Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease '   ' | Should -Be '1.1.10'
+            }
+
+            It 'Get-ModuleVersionString - trims whitespace around the prerelease label' {
+                Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease ' mybranch001 ' |
+                    Should -Be '1.1.10-mybranch001'
+            }
+
+            It 'Get-ModuleVersionString - takes no version prefix parameter at all' {
+                (Get-Command Get-ModuleVersionString).Parameters.Keys | Should -Not -Contain 'VersionPrefix'
+            }
+
+            It 'Get-ModuleVersionString - requires a module version' {
+                { Get-ModuleVersionString -ModuleVersion '' } | Should -Throw
+            }
+        }
+    }
+
+    Describe 'Get-ReleaseTag' {
+        Context 'Get-ReleaseTag - repository with a version prefix' {
+            It 'Get-ReleaseTag - prefixes a stable release tag with the configured prefix' {
+                Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' | Should -Be 'v1.1.10'
+            }
+
+            It 'Get-ReleaseTag - prefixes a stable release tag when the prerelease label is empty' {
+                Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease '' | Should -Be 'v1.1.10'
+            }
+
+            It 'Get-ReleaseTag - prefixes a prerelease tag with the configured prefix' {
+                Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease 'mybranch001' |
+                    Should -Be 'v1.1.10-mybranch001'
+            }
+
+            It 'Get-ReleaseTag - supports a multi-character prefix' {
+                Get-ReleaseTag -VersionPrefix 'release-v' -ModuleVersion '2.0.0' | Should -Be 'release-v2.0.0'
+            }
+        }
+
+        Context 'Get-ReleaseTag - repository without a version prefix' {
+            It 'Get-ReleaseTag - leaves a stable release tag unprefixed' {
+                Get-ReleaseTag -VersionPrefix '' -ModuleVersion '1.1.10' | Should -Be '1.1.10'
+            }
+
+            It 'Get-ReleaseTag - leaves a prerelease tag unprefixed' {
+                Get-ReleaseTag -VersionPrefix '' -ModuleVersion '1.1.10' -Prerelease 'mybranch001' |
+                    Should -Be '1.1.10-mybranch001'
+            }
+
+            It 'Get-ReleaseTag - treats an absent prefix as no prefix' {
+                Get-ReleaseTag -ModuleVersion '1.1.10' | Should -Be '1.1.10'
+            }
+
+            It 'Get-ReleaseTag - treats a null prefix as no prefix' {
+                Get-ReleaseTag -VersionPrefix $null -ModuleVersion '1.1.10' | Should -Be '1.1.10'
+            }
+        }
+
+        Context 'Get-ReleaseTag - input normalization' {
+            It 'Get-ReleaseTag - trims whitespace around the prefix' {
+                Get-ReleaseTag -VersionPrefix ' v ' -ModuleVersion '1.1.10' | Should -Be 'v1.1.10'
+            }
+
+            It 'Get-ReleaseTag - trims whitespace around the prerelease label' {
+                Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease ' mybranch001 ' |
+                    Should -Be 'v1.1.10-mybranch001'
+            }
+
+            It 'Get-ReleaseTag - treats a whitespace-only prerelease label as a stable release' {
+                Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease '   ' | Should -Be 'v1.1.10'
+            }
+
+            It 'Get-ReleaseTag - requires a module version' {
+                { Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '' } | Should -Throw
+            }
+        }
+
+        # Cleanup-PSModulePrereleases selects the releases to delete with
+        # `tagName -like "*$prereleaseName*" -and tagName -ne $publishedReleaseTag`, where the published tag is
+        # the value publish.ps1 exports as PSMODULE_PUBLISH_PSMODULE_CONTEXT_ReleaseTag. Both halves of that
+        # filter have to keep working once the tag carries a prefix.
+        Context 'Get-ReleaseTag - AutoCleanup tag matching contract' {
+            It 'Get-ReleaseTag - keeps the prerelease name inside a prefixed tag so cleanup still matches it' {
+                Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease 'mybranch001' |
+                    Should -BeLike '*mybranch*'
+            }
+
+            It 'Get-ReleaseTag - keeps the prerelease name inside an unprefixed tag so cleanup still matches it' {
+                Get-ReleaseTag -VersionPrefix '' -ModuleVersion '1.1.10' -Prerelease 'mybranch001' |
+                    Should -BeLike '*mybranch*'
+            }
+
+            It 'Get-ReleaseTag - produces the same tag twice so cleanup can exclude the published release' {
+                $first = Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+                $second = Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+                $first | Should -Be $second
+            }
+        }
+
+        # The PowerShell Gallery and the module manifest only accept plain SemVer. The prefix therefore
+        # belongs to the GitHub release tag and to nothing else, and the two strings must differ by exactly
+        # the prefix - never by anything else, and never in the other direction.
+        Context 'Get-ReleaseTag - the prefix reaches the release tag and nothing else' {
+            It 'Get-ReleaseTag - the tag is the prefix followed by the module version string' -ForEach @(
+                @{ Prefix = 'v'; Version = '1.1.10'; Label = '' }
+                @{ Prefix = 'v'; Version = '1.1.10'; Label = 'mybranch001' }
+                @{ Prefix = ''; Version = '1.1.10'; Label = '' }
+                @{ Prefix = ''; Version = '1.1.10'; Label = 'mybranch001' }
+                @{ Prefix = 'release-v'; Version = '2.0.0'; Label = 'mybranch001' }
+            ) {
+                $moduleVersion = Get-ModuleVersionString -ModuleVersion $Version -Prerelease $Label
+                $tag = Get-ReleaseTag -VersionPrefix $Prefix -ModuleVersion $Version -Prerelease $Label
+                $tag | Should -Be "$Prefix$moduleVersion"
+            }
+
+            It 'Get-ReleaseTag - the module version string never gains the prefix' -ForEach @(
+                @{ Prefix = 'v'; Version = '1.1.10'; Label = '' }
+                @{ Prefix = 'v'; Version = '1.1.10'; Label = 'mybranch001' }
+                @{ Prefix = 'release-v'; Version = '2.0.0'; Label = 'mybranch001' }
+            ) {
+                $moduleVersion = Get-ModuleVersionString -ModuleVersion $Version -Prerelease $Label
+                $moduleVersion | Should -Not -BeLike "$Prefix*"
+                $moduleVersion | Should -Match '^\d+\.\d+\.\d+(-[0-9A-Za-z\-.]+)?$'
+            }
+
+            It 'Get-ReleaseTag - an unprefixed repository gets identical strings' {
+                $moduleVersion = Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+                $tag = Get-ReleaseTag -VersionPrefix '' -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+                $tag | Should -Be $moduleVersion
+            }
+
+            It 'Get-ReleaseTag - stripping the prefix from the tag yields the module version string' {
+                $moduleVersion = Get-ModuleVersionString -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+                $tag = Get-ReleaseTag -VersionPrefix 'v' -ModuleVersion '1.1.10' -Prerelease 'mybranch001'
+                $tag -replace '^v' | Should -Be $moduleVersion
+            }
+        }
+    }
+}
diff --git a/.github/workflows/Publish-Module.yml b/.github/workflows/Publish-Module.yml
@@ -50,6 +50,7 @@ jobs:
           UsePRTitleAsReleaseName: ${{ fromJson(inputs.Settings).Publish.Module.UsePRTitleAsReleaseName }}
           UsePRBodyAsReleaseNotes: ${{ fromJson(inputs.Settings).Publish.Module.UsePRBodyAsReleaseNotes }}
           UsePRTitleAsNotesHeading: ${{ fromJson(inputs.Settings).Publish.Module.UsePRTitleAsNotesHeading }}
+          VersionPrefix: ${{ fromJson(inputs.Settings).Publish.Module.VersionPrefix }}
           WorkingDirectory: ${{ fromJson(inputs.Settings).WorkingDirectory }}
 
       - name: Cleanup prereleases
