Make GitHub release retries resumable

MariusStorhaug · Copilot · MariusStorhaug · commit 034d5aa2ab91 · 2026-08-09T13:15:34.000+02:00
Co-authored-by: Copilot App &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/.github/actions/Cleanup-PSModulePrereleases/action.yml b/.github/actions/Cleanup-PSModulePrereleases/action.yml
@@ -7,6 +7,10 @@ inputs:
     description: Control whether to automatically delete prerelease tags.
     required: false
     default: 'true'
+  ReleaseTag:
+    description: GitHub release tag to retain during cleanup.
+    required: false
+    default: ''
   WhatIf:
     description: If specified, the action will only log the changes it would make.
     required: false
@@ -28,5 +32,5 @@ runs:
       working-directory: ${{ inputs.WorkingDirectory }}
       env:
         PSMODULE_CLEANUP_PSMODULEPRERELEASES_INPUT_WhatIf: ${{ inputs.WhatIf }}
-        PSMODULE_CLEANUP_PSMODULEPRERELEASES_CONTEXT_ReleaseTag: ${{ env.PSMODULE_RELEASE_PSMODULE_CONTEXT_ReleaseTag }}
+        PSMODULE_CLEANUP_PSMODULEPRERELEASES_CONTEXT_ReleaseTag: ${{ inputs.ReleaseTag }}
       run: ${{ github.action_path }}/src/cleanup.ps1
diff --git a/.github/actions/Release-PSModule/action.yml b/.github/actions/Release-PSModule/action.yml
@@ -38,6 +38,14 @@ inputs:
     description: Full GitHub release tag resolved by Resolve-PSModuleVersion.
     required: true
 
+outputs:
+  ReleaseTag:
+    description: Full GitHub release tag created or resumed by this action.
+    value: ${{ steps.release.outputs.ReleaseTag }}
+  ReleaseUrl:
+    description: URL of the GitHub release created or resumed by this action.
+    value: ${{ steps.release.outputs.ReleaseUrl }}
+
 runs:
   using: composite
   steps:
@@ -51,6 +59,7 @@ runs:
         path: ${{ inputs.ModulePath }}
 
     - name: Create GitHub release
+      id: release
       shell: pwsh
       working-directory: ${{ inputs.WorkingDirectory }}
       env:
diff --git a/.github/actions/Release-PSModule/src/release.ps1 b/.github/actions/Release-PSModule/src/release.ps1
@@ -1,4 +1,26 @@
-﻿[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+﻿#Requires -Version 7.0
+#Requires -Modules PSModule
+
+<#
+    .SYNOPSIS
+    Creates or resumes a GitHub release for a versioned PowerShell module artifact.
+
+    .DESCRIPTION
+    Validates the supplied module artifact, creates a GitHub release when its tag does not
+    already exist, uploads the artifact ZIP, and reports the result on the source pull request.
+
+    .EXAMPLE
+    ./release.ps1
+
+    Creates or resumes the release using inputs supplied by the Release-PSModule action.
+
+    .INPUTS
+    None. The Release-PSModule composite action supplies values through environment variables.
+
+    .OUTPUTS
+    None. The script writes ReleaseTag and ReleaseUrl to the GitHub Actions output file.
+#>
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
     'PSUseDeclaredVarsMoreThanAssignments', 'usePRBodyAsReleaseNotes',
     Justification = 'Variable is used in script blocks.'
 )]
@@ -25,11 +47,11 @@
 [CmdletBinding()]
 param()
 
+$ErrorActionPreference = 'Stop'
 $PSStyle.OutputRendering = 'Ansi'
 
 Import-Module -Name 'PSModule' -Force
 
-#region Load inputs
 LogGroup 'Load inputs' {
     $env:GITHUB_REPOSITORY_NAME = $env:GITHUB_REPOSITORY -replace '.+/'
 
@@ -67,9 +89,7 @@ LogGroup 'Load inputs' {
     Write-Host "Release tag: [$releaseTag]"
     Write-Host "WhatIf:      [$whatIf]"
 }
-#endregion Load inputs
 
-#region Load PR information
 LogGroup 'Load PR information' {
     $githubEventJson = Get-Content -Raw $env:GITHUB_EVENT_PATH
     $githubEvent = $githubEventJson | ConvertFrom-Json
@@ -80,9 +100,7 @@ LogGroup 'Load PR information' {
     $prNumber = $pull_request.number
     $prHeadRef = $pull_request.head.ref
 }
-#endregion Load PR information
 
-#region Resolve version from manifest
 LogGroup 'Resolve version from manifest' {
     Add-PSModulePath -Path (Split-Path -Path $modulePath -Parent)
     $manifestFilePath = Join-Path -Path $modulePath -ChildPath "$name.psd1"
@@ -101,100 +119,101 @@ LogGroup 'Resolve version from manifest' {
         Write-Host '::warning::Test-ModuleManifest returned warnings (e.g. unresolved RequiredModules). Continuing with data-file validation.'
     }
 
-    try {
-        $manifestData = Import-PowerShellDataFile -Path $manifestFilePath
-    } catch {
-        Write-Error "Failed to import manifest data file [$manifestFilePath]: $($_.Exception.Message)"
-        exit 1
-    }
+    $manifestData = Import-PowerShellDataFile -Path $manifestFilePath -ErrorAction Stop
     $moduleVersion = $manifestData.ModuleVersion
     if (-not ($moduleVersion -match '^\d+\.\d+\.\d+$')) {
-        Write-Error ("ModuleVersion [$moduleVersion] must be in Major.Minor.Patch format. " +
+        throw ("ModuleVersion [$moduleVersion] must be in Major.Minor.Patch format. " +
             'Ensure Build-PSModule has stamped the artifact with a final version.')
-        exit 1
     }
     if ($moduleVersion -eq '999.0.0') {
-        Write-Error ('ModuleVersion is the placeholder [999.0.0]. ' +
+        throw ('ModuleVersion is the placeholder [999.0.0]. ' +
             'The artifact was not stamped with a real version by the build step.')
-        exit 1
     }
     $prerelease = $manifestData.PrivateData.PSData.Prerelease
     if ([string]::IsNullOrWhiteSpace($prerelease)) {
         $prerelease = ''
         $createPrerelease = $false
     } else {
         if ($prerelease -notmatch '^[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*$') {
-            Write-Error ("Prerelease label [$prerelease] is not a valid SemVer prerelease identifier. " +
+            throw ("Prerelease label [$prerelease] is not a valid SemVer prerelease identifier. " +
                 'It must contain only alphanumerics, hyphens, and dots as separators.')
-            exit 1
         }
         $createPrerelease = $true
     }
 
     $releaseType = if ($createPrerelease) { 'New prerelease' } else { 'New release' }
     $publishPSVersion = if ($createPrerelease) { "$moduleVersion-$prerelease" } else { $moduleVersion }
 
-    [PSCustomObject]@{
-        ModuleVersion    = $moduleVersion
-        Prerelease       = $prerelease
-        CreatePrerelease = $createPrerelease
-        GalleryVersion   = $publishPSVersion
-        ReleaseTag       = $releaseTag
-        PRNumber         = $prNumber
-        PRHeadRef        = $prHeadRef
-    } | Format-List | Out-String
-
-    # Expose release tag to subsequent steps so cleanup can exclude the just-created tag.
-    "PSMODULE_RELEASE_PSMODULE_CONTEXT_ReleaseTag=$releaseTag" | Out-File -Path $env:GITHUB_ENV -Append -Encoding utf8NoBOM
+    Write-Host (
+        [PSCustomObject]@{
+            ModuleVersion    = $moduleVersion
+            Prerelease       = $prerelease
+            CreatePrerelease = $createPrerelease
+            GalleryVersion   = $publishPSVersion
+            ReleaseTag       = $releaseTag
+            PRNumber         = $prNumber
+            PRHeadRef        = $prHeadRef
+        } | Format-List | Out-String
+    )
 }
-#endregion Resolve version from manifest
 
-#region Create GitHub release with module artifact attached
 # A zip of the built module is uploaded so the GitHub Release page exposes the exact bytes.
 LogGroup 'Create GitHub release' {
     $releaseCreateCommand = @('release', 'create', $releaseTag)
     $notesFilePath = $null
+    $releaseExists = $false
 
-    if ($usePRTitleAsReleaseName -and $pull_request.title) {
-        $releaseCreateCommand += @('--title', $pull_request.title)
-        Write-Host "Using PR title as release name: [$($pull_request.title)]"
-    } else {
-        $releaseCreateCommand += @('--title', $releaseTag)
-    }
-
-    # Build release notes content. Uses temp file to avoid escaping issues with special characters.
-    # Precedence rules for the three UsePR* parameters:
-    #   1. UsePRTitleAsNotesHeading + UsePRBodyAsReleaseNotes: Creates "# Title (#PR)\n\nBody" format.
-    #   2. UsePRBodyAsReleaseNotes only: Uses PR body as-is.
-    #   3. Fallback: Auto-generates notes via GitHub's --generate-notes.
-    if ($usePRTitleAsNotesHeading -and $usePRBodyAsReleaseNotes -and $pull_request.title -and $pull_request.body) {
-        $notes = "# $($pull_request.title) (#$prNumber)`n`n$($pull_request.body)"
-        $notesFilePath = [System.IO.Path]::GetTempFileName()
-        Set-Content -Path $notesFilePath -Value $notes -Encoding utf8
-        $releaseCreateCommand += @('--notes-file', $notesFilePath)
-        Write-Host 'Using PR title as H1 heading with link and body as release notes'
-    } elseif ($usePRBodyAsReleaseNotes -and $pull_request.body) {
-        $notesFilePath = [System.IO.Path]::GetTempFileName()
-        Set-Content -Path $notesFilePath -Value $pull_request.body -Encoding utf8
-        $releaseCreateCommand += @('--notes-file', $notesFilePath)
-        Write-Host 'Using PR body as release notes'
-    } else {
-        $releaseCreateCommand += @('--generate-notes')
-    }
+    if (-not $whatIf) {
+        $encodedReleaseTag = [System.Uri]::EscapeDataString($releaseTag)
+        $releaseLookupResult = gh api "repos/$env:GITHUB_REPOSITORY/releases/tags/$encodedReleaseTag" --jq '.html_url' 2>&1
+        $releaseLookupExitCode = $LASTEXITCODE
 
-    if ($createPrerelease) {
-        $releaseCreateCommand += @('--target', $prHeadRef, '--prerelease')
+        if ($releaseLookupExitCode -eq 0) {
+            $releaseURL = ($releaseLookupResult | Out-String).Trim()
+            $releaseExists = $true
+            Write-Host "GitHub release [$releaseTag] already exists. Resuming its artifact upload."
+        } elseif (($releaseLookupResult | Out-String) -notmatch 'HTTP 404') {
+            throw "Unable to determine whether release [$releaseTag] exists: $($releaseLookupResult | Out-String)"
+        }
     }
 
-    if ($whatIf) {
-        Write-Host "WhatIf: gh $($releaseCreateCommand -join ' ')"
-        $releaseURL = "https://github.com/$env:GITHUB_REPOSITORY/releases/tag/$releaseTag"
-    } else {
+    if (-not $releaseExists) {
+        if ($usePRTitleAsReleaseName -and $pull_request.title) {
+            $releaseCreateCommand += @('--title', $pull_request.title)
+            Write-Host "Using PR title as release name: [$($pull_request.title)]"
+        } else {
+            $releaseCreateCommand += @('--title', $releaseTag)
+        }
+
+        # Build release notes content. Uses a file to preserve special characters.
+        if ($usePRTitleAsNotesHeading -and $usePRBodyAsReleaseNotes -and $pull_request.title -and $pull_request.body) {
+            $notes = "# $($pull_request.title) (#$prNumber)`n`n$($pull_request.body)"
+            $notesFilePath = [System.IO.Path]::GetTempFileName()
+            Set-Content -Path $notesFilePath -Value $notes -Encoding utf8
+            $releaseCreateCommand += @('--notes-file', $notesFilePath)
+            Write-Host 'Using PR title as H1 heading with link and body as release notes'
+        } elseif ($usePRBodyAsReleaseNotes -and $pull_request.body) {
+            $notesFilePath = [System.IO.Path]::GetTempFileName()
+            Set-Content -Path $notesFilePath -Value $pull_request.body -Encoding utf8
+            $releaseCreateCommand += @('--notes-file', $notesFilePath)
+            Write-Host 'Using PR body as release notes'
+        } else {
+            $releaseCreateCommand += @('--generate-notes')
+        }
+
+        if ($createPrerelease) {
+            $releaseCreateCommand += @('--target', $prHeadRef, '--prerelease')
+        }
+
         try {
-            $releaseURL = gh @releaseCreateCommand
-            if ($LASTEXITCODE -ne 0) {
-                Write-Error "Failed to create the release [$releaseTag]."
-                exit $LASTEXITCODE
+            if ($whatIf) {
+                Write-Host "WhatIf: gh $($releaseCreateCommand -join ' ')"
+                $releaseURL = "https://github.com/$env:GITHUB_REPOSITORY/releases/tag/$releaseTag"
+            } else {
+                $releaseURL = gh @releaseCreateCommand
+                if ($LASTEXITCODE -ne 0) {
+                    throw "Failed to create the release [$releaseTag]."
+                }
             }
         } finally {
             if ($notesFilePath -and (Test-Path -Path $notesFilePath)) {
@@ -218,8 +237,7 @@ LogGroup 'Create GitHub release' {
         try {
             gh release upload $releaseTag $zipPath --clobber
             if ($LASTEXITCODE -ne 0) {
-                Write-Error "Failed to upload module artifact to release [$releaseTag]."
-                exit $LASTEXITCODE
+                throw "Failed to upload module artifact to release [$releaseTag]."
             }
             Write-Host "::notice title=📦 Attached module artifact to release::$zipFileName"
         } finally {
@@ -234,12 +252,14 @@ LogGroup 'Create GitHub release' {
     } else {
         gh pr comment $prNumber -b "✅ $releaseType`: GitHub - [$name $releaseTag]($releaseURL)"
         if ($LASTEXITCODE -ne 0) {
-            Write-Error 'Failed to comment on the pull request.'
-            exit $LASTEXITCODE
+            throw 'Failed to comment on the pull request.'
         }
     }
+    if ($env:GITHUB_OUTPUT) {
+        "ReleaseTag=$releaseTag" | Out-File -Path $env:GITHUB_OUTPUT -Append -Encoding utf8NoBOM
+        "ReleaseUrl=$releaseURL" | Out-File -Path $env:GITHUB_OUTPUT -Append -Encoding utf8NoBOM
+    }
     Write-Host "::notice title=✅ $releaseType`: GitHub - $name $releaseTag::$releaseURL"
 }
-#endregion Create GitHub release
 
 Write-Host "Release creation complete. Version: [$releaseTag]"
diff --git a/.github/actions/Release-PSModule/tests/Release-PSModule.WhatIf.Tests.ps1 b/.github/actions/Release-PSModule/tests/Release-PSModule.WhatIf.Tests.ps1
@@ -10,10 +10,11 @@ BeforeAll {
 
     $script:releaseScriptPath = Join-Path -Path $PSScriptRoot -ChildPath '../src/release.ps1'
     $script:environmentVariableNames = @(
-        'GITHUB_ENV'
         'GITHUB_EVENT_PATH'
+        'GITHUB_OUTPUT'
         'GITHUB_REPOSITORY'
         'GITHUB_WORKSPACE'
+        'RELEASE_ACTION_GH_CALL_LOG'
         'PSMODULE_RELEASE_PSMODULE_INPUT_Name'
         'PSMODULE_RELEASE_PSMODULE_INPUT_ModulePath'
         'PSMODULE_RELEASE_PSMODULE_INPUT_WhatIf'
@@ -32,22 +33,26 @@ AfterAll {
     foreach ($name in $script:environmentVariableNames) {
         [System.Environment]::SetEnvironmentVariable($name, $script:originalEnvironment[$name])
     }
+    Remove-Item -Path function:global:gh -ErrorAction SilentlyContinue
 }
 
 Describe 'Release-PSModule WhatIf' {
-    It 'creates a prefixed prerelease tag without GitHub side effects' {
-        $moduleName = 'TestModule'
-        $workspacePath = Join-Path -Path $TestDrive -ChildPath 'workspace'
-        $modulePath = Join-Path -Path $workspacePath -ChildPath "outputs/module/$moduleName"
-        $manifestPath = Join-Path -Path $modulePath -ChildPath "$moduleName.psd1"
+    BeforeEach {
+        $script:moduleName = 'TestModule'
+        $script:workspacePath = Join-Path -Path $TestDrive -ChildPath 'workspace'
+        $script:modulePath = Join-Path -Path $script:workspacePath -ChildPath "outputs/module/$script:moduleName"
+        $manifestPath = Join-Path -Path $script:modulePath -ChildPath "$script:moduleName.psd1"
         $eventPath = Join-Path -Path $TestDrive -ChildPath 'event.json'
-        $githubEnvironmentPath = Join-Path -Path $TestDrive -ChildPath 'github-environment'
+        $script:githubOutputPath = Join-Path -Path $TestDrive -ChildPath 'github-output'
+        $script:ghCallLogPath = Join-Path -Path $TestDrive -ChildPath 'gh-calls'
 
-        New-Item -Path $modulePath -ItemType Directory -Force | Out-Null
-        Set-Content -Path (Join-Path -Path $modulePath -ChildPath "$moduleName.psm1") -Value ''
+        $null = New-Item -Path $script:modulePath -ItemType Directory -Force
+        $null = New-Item -Path $script:githubOutputPath -ItemType File -Force
+        $null = New-Item -Path $script:ghCallLogPath -ItemType File -Force
+        Set-Content -Path (Join-Path -Path $script:modulePath -ChildPath "$script:moduleName.psm1") -Value ''
         Set-Content -Path $manifestPath -Value @"
 @{
-    RootModule = '$moduleName.psm1'
+    RootModule = '$script:moduleName.psm1'
     ModuleVersion = '1.2.3'
     GUID = '3c0f8d73-60b7-4f38-b3cf-9386db4982a4'
     Author = 'PSModule'
@@ -71,20 +76,50 @@ Describe 'Release-PSModule WhatIf' {
             }
         } | ConvertTo-Json -Depth 5 | Set-Content -Path $eventPath
 
-        $env:GITHUB_ENV = $githubEnvironmentPath
         $env:GITHUB_EVENT_PATH = $eventPath
-        $env:GITHUB_REPOSITORY = "PSModule/$moduleName"
-        $env:GITHUB_WORKSPACE = $workspacePath
-        $env:PSMODULE_RELEASE_PSMODULE_INPUT_Name = $moduleName
+        $env:GITHUB_OUTPUT = $script:githubOutputPath
+        $env:GITHUB_REPOSITORY = "PSModule/$script:moduleName"
+        $env:GITHUB_WORKSPACE = $script:workspacePath
+        $env:RELEASE_ACTION_GH_CALL_LOG = $script:ghCallLogPath
+        $env:PSMODULE_RELEASE_PSMODULE_INPUT_Name = $script:moduleName
         $env:PSMODULE_RELEASE_PSMODULE_INPUT_ModulePath = 'outputs/module'
         $env:PSMODULE_RELEASE_PSMODULE_INPUT_WhatIf = 'true'
         $env:PSMODULE_RELEASE_PSMODULE_INPUT_UsePRBodyAsReleaseNotes = 'true'
         $env:PSMODULE_RELEASE_PSMODULE_INPUT_UsePRTitleAsReleaseName = 'false'
         $env:PSMODULE_RELEASE_PSMODULE_INPUT_UsePRTitleAsNotesHeading = 'true'
         $env:PSMODULE_RELEASE_PSMODULE_INPUT_ReleaseTag = 'v1.2.3-preview.1'
+    }
+
+    It 'creates a prefixed prerelease tag without GitHub side effects' {
+        { & $script:releaseScriptPath } | Should -Not -Throw
+
+        Get-Content -Path $script:githubOutputPath | Should -Contain 'ReleaseTag=v1.2.3-preview.1'
+        Get-Content -Path $script:githubOutputPath | Should -Contain 'ReleaseUrl=https://github.com/PSModule/TestModule/releases/tag/v1.2.3-preview.1'
+    }
+
+    It 'resumes an existing release after a partial failure' {
+        $env:PSMODULE_RELEASE_PSMODULE_INPUT_WhatIf = 'false'
+        Set-Item -Path function:global:gh -Value {
+            [CmdletBinding()]
+            param(
+                [Parameter(ValueFromRemainingArguments)]
+                [string[]] $Arguments
+            )
+
+            Add-Content -Path $env:RELEASE_ACTION_GH_CALL_LOG -Value ($Arguments -join ' ')
+            $global:LASTEXITCODE = 0
+            if ($Arguments[0] -eq 'api') {
+                return 'https://github.com/PSModule/TestModule/releases/tag/v1.2.3-preview.1'
+            }
+        }
 
         { & $script:releaseScriptPath } | Should -Not -Throw
 
-        Get-Content -Path $githubEnvironmentPath | Should -Contain 'PSMODULE_RELEASE_PSMODULE_CONTEXT_ReleaseTag=v1.2.3-preview.1'
+        $ghCalls = Get-Content -Path $script:ghCallLogPath -Raw
+        $ghCalls | Should -Match 'api repos/PSModule/TestModule/releases/tags/v1.2.3-preview.1 --jq .html_url'
+        $ghCalls | Should -Match 'release upload v1.2.3-preview.1'
+        $ghCalls | Should -Match 'pr comment 42'
+        $ghCalls | Should -Not -Match 'release create'
+        Get-Content -Path $script:githubOutputPath | Should -Contain 'ReleaseTag=v1.2.3-preview.1'
     }
 }
diff --git a/.github/workflows/Publish-Module.yml b/.github/workflows/Publish-Module.yml
