From dbfb984cba401eab710d4010a2a07a783a1ca7d7 Mon Sep 17 00:00:00 2001 From: Chris Taylor Date: Tue, 10 Nov 2026 21:59:44 -0700 Subject: [PATCH 1/3] Harden the release and CI pipelines after review Release: the publish job skips the upload when the version is already on the Gallery, so a re-run after a late failure is safe; the package hash comes from the build job's output; the GitHub Release step is idempotent and the wait for the Gallery listing moved after it. AGENTS.md documents what to do when a release run fails. Tools: every build, test and docs tool is pinned to an exact version in RequiredModules.psd1. CI resolves them once and shares the folder between jobs; test-local imports each tool at its pinned version and prints it. Checks: the analyzer stage also fails on plain-text password and credential-type warnings; a Pester run with no passing test fails; master CI runs are no longer cancelled; release/** branches no longer run twice. Co-Authored-By: Claude --- .github/dependabot.yml | 4 +- .github/workflows/ci.yml | 58 ++++++++++++++----------- .github/workflows/release.yml | 81 +++++++++++++++++++++++++++-------- AGENTS.md | 45 +++++++++++++------ CHANGELOG.md | 4 ++ RequiredModules.psd1 | 29 +++++++------ Tests/test-local.ps1 | 39 +++++++++++++++-- 7 files changed, 185 insertions(+), 75 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 28d7c8f..0a7998f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,8 +1,8 @@ # Keeps the SHA-pinned GitHub Actions in .github/workflows current. # Dependabot updates both the commit SHA and the trailing "# vX.Y.Z" comment. # -# PowerShell Gallery modules are NOT covered by Dependabot. The Pester, PSScriptAnalyzer and platyPS -# versions are pinned in the env: block of .github/workflows/ci.yml; bump them there by hand. +# PowerShell Gallery modules are NOT covered by Dependabot. The build, test and docs tools are pinned to +# exact versions in RequiredModules.psd1; raise them there by hand. version: 2 updates: - package-ecosystem: github-actions diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 47b4b30..6944297 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,6 +3,11 @@ # Every job calls Tests/test-local.ps1 for one stage, so `./Tests/test-local.ps1` locally runs the same checks. # The build job (Sampler/ModuleBuilder) produces output///; the Pester jobs test that built # module under both Windows PowerShell 5.1 and PowerShell 7, because the module must work on both. +# +# Tools (Pester, PSScriptAnalyzer, platyPS and the build modules) are downloaded from the PowerShell Gallery once, +# by the build job, at the exact versions in RequiredModules.psd1. The other jobs get that folder as an artifact, +# and test-local.ps1 imports each tool at its pinned version. No job installs a tool by itself. +# # Publishing to the PowerShell Gallery is done by release.yml (see AGENTS.md). No module name is hard-coded here. # # Security note: never interpolate ${{ github.* }} / ${{ matrix.* }} values directly into a @@ -10,13 +15,12 @@ name: CI -# Topic branches are covered by their pull request; listing them under push too would run every job twice. +# Branches are covered by their pull request; listing them under push too would run every job twice. # Use "Run workflow" (workflow_dispatch) to test a branch that has no PR yet. on: push: branches: - master - - 'release/**' pull_request: branches: - master @@ -26,14 +30,11 @@ on: permissions: contents: read +# A newer push to a pull request cancels the older run. Runs on master are never cancelled, so every merged +# commit gets a result. concurrency: group: ci-${{ github.ref }} - cancel-in-progress: true - -env: - PESTER_VERSION: 5.7.1 - PSSA_VERSION: 1.24.0 - PLATYPS_VERSION: 0.14.2 + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: build: @@ -62,6 +63,14 @@ jobs: if-no-files-found: error retention-days: 7 + - name: Upload Required Modules + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: required-modules + path: output/RequiredModules/ + if-no-files-found: error + retention-days: 1 + test: name: Pester (${{ matrix.name }}) needs: build @@ -90,14 +99,11 @@ jobs: name: module-build path: output - - name: Install Pester - run: | - [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072 - if (-not (Get-PackageProvider -ListAvailable -Name NuGet -ErrorAction SilentlyContinue)) { - Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Scope CurrentUser -Force | Out-Null - } - Set-PSRepository -Name PSGallery -InstallationPolicy Trusted - Install-Module -Name Pester -RequiredVersion $env:PESTER_VERSION -Scope CurrentUser -Force -SkipPublisherCheck + - name: Download Required Modules + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: required-modules + path: output/RequiredModules - name: Run Pester against the built module env: @@ -115,6 +121,7 @@ jobs: analyze: name: PSScriptAnalyzer + needs: build runs-on: windows-latest defaults: run: @@ -126,16 +133,18 @@ jobs: with: persist-credentials: false - - name: Install PSScriptAnalyzer - run: | - Set-PSRepository -Name PSGallery -InstallationPolicy Trusted - Install-Module -Name PSScriptAnalyzer -RequiredVersion $env:PSSA_VERSION -Scope CurrentUser -Force + - name: Download Required Modules + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: required-modules + path: output/RequiredModules - name: Analyze source run: ./Tests/test-local.ps1 -Stage Analyze docs: name: Docs drift + needs: build runs-on: windows-latest defaults: run: @@ -147,10 +156,11 @@ jobs: with: persist-credentials: false - - name: Install platyPS - run: | - Set-PSRepository -Name PSGallery -InstallationPolicy Trusted - Install-Module -Name platyPS -RequiredVersion $env:PLATYPS_VERSION -Scope CurrentUser -Force + - name: Download Required Modules + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: required-modules + path: output/RequiredModules - name: Regenerate help and check for drift run: ./Tests/test-local.ps1 -Stage Docs diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4533f7b..5d3826a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,10 +12,14 @@ # package on both editions (Build/Test-ReleasePackage.ps1) # 4. publish Publish-PSResource -NupkgPath of that exact .nupkg, after checking its SHA256. Runs in the # "psgallery" environment, which holds the PSGALLERY_API_KEY secret and should require the owner's -# approval. -# 5. release GitHub Release for the tag, with the CHANGELOG section as its notes +# approval. If the version is already on the Gallery (a re-run after the upload went through), it +# uploads nothing and succeeds. +# 5. release GitHub Release for the tag, with the CHANGELOG section as its notes, then a wait until the +# Gallery lists the version (a warning, never a failure) # # A Gallery version can never be replaced, so everything that can fail is checked before step 4. +# Re-running: "Re-run failed jobs" is always safe. "Re-run all jobs" after a successful publish stops at step 1, +# because the version then exists. See "Releasing" in AGENTS.md. # No module name is hard-coded here. # # Security note: never interpolate ${{ github.* }} values directly into a run: script. Use env: or the @@ -45,6 +49,9 @@ jobs: defaults: run: shell: pwsh + outputs: + # Passed to the publish job apart from the artifact, so the file and its expected hash do not travel together + sha256: ${{ steps.package.outputs.sha256 }} steps: - name: Checkout Repository @@ -70,9 +77,11 @@ jobs: run: ./Tests/test-local.ps1 - name: Package and check the package + id: package run: | $Release = Join-Path 'output' 'release' $Package = ./Build/Test-ReleasePackage.ps1 -PackagePath $Release + "sha256=$($Package.PackageSha256)" | Add-Content -Path $env:GITHUB_OUTPUT Move-Item -Path 'release-notes.md' -Destination $Release $Package | Select-Object ModuleName, Version, Functions, PackageName, PackageSha256 | ConvertTo-Json | Set-Content -Path (Join-Path $Release 'release.json') @@ -122,32 +131,44 @@ jobs: - name: Publish env: PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }} + EXPECTED_SHA256: ${{ needs.build.outputs.sha256 }} run: | if (-not $env:PSGALLERY_API_KEY) { throw 'The PSGALLERY_API_KEY secret is not set in the psgallery environment.' } + if (-not $env:EXPECTED_SHA256) { throw 'The build job reported no package hash.' } $Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json if ("v$($Release.Version)" -ne $env:GITHUB_REF_NAME) { throw "The built version $($Release.Version) does not match tag $env:GITHUB_REF_NAME." } - # Publish the .nupkg the build job checked, and only if it is byte-for-byte that file + # Publish the .nupkg the build job checked: its hash must be the one that job reported $Package = Join-Path 'release' $Release.PackageName $Hash = (Get-FileHash -Path $Package -Algorithm SHA256).Hash - if ($Hash -ne $Release.PackageSha256) { - throw "The package hash $Hash does not match the checked package $($Release.PackageSha256)." + if ($Hash -ne $env:EXPECTED_SHA256) { + throw "The package hash $Hash does not match the checked package $env:EXPECTED_SHA256." } - Publish-PSResource -NupkgPath $Package -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY - Write-Host "Published $($Release.ModuleName) $($Release.Version) ($($Release.PackageName), SHA256 $Hash)" - - name: Wait until the Gallery lists the version - run: | - $Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json - foreach ($Attempt in 1..20) { - $Found = Find-PSResource -Name $Release.ModuleName -Version $Release.Version -Repository PSGallery ` - -ErrorAction SilentlyContinue - if ($Found) { Write-Host "The Gallery lists $($Found.Name) $($Found.Version)"; exit 0 } - Start-Sleep -Seconds 30 + # Is the version already on the Gallery? 200 = yes, 404 = no, anything else = stop. It is there when + # this job is re-run after an upload that went through (the build job refuses a version that exists + # before it builds). Uploading again would only fail, so skip it and let the release be created. + $Uri = "https://www.powershellgallery.com/api/v2/Packages(Id='$($Release.ModuleName)',Version='$($Release.Version)')" + try { + Invoke-WebRequest -Uri $Uri -UseBasicParsing | Out-Null + $Exists = $true + } catch { + $Status = 0 + if ($_.Exception.Response) { $Status = [int]$_.Exception.Response.StatusCode } + if ($Status -ne 404) { throw "Could not check the PowerShell Gallery (HTTP $Status): $($_.Exception.Message)" } + $Exists = $false + } + if ($Exists) { + Write-Warning "$($Release.ModuleName) $($Release.Version) is already on the PowerShell Gallery. Nothing was uploaded." + "Already on the Gallery: $($Release.ModuleName) $($Release.Version). Nothing was uploaded in this run." | + Add-Content -Path $env:GITHUB_STEP_SUMMARY + exit 0 } - # The publish itself succeeded; the Gallery can take longer to validate and index a package. - Write-Warning 'The Gallery does not list the version yet. Check the package page before announcing it.' + + Publish-PSResource -NupkgPath $Package -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY + Write-Host "Published $($Release.ModuleName) $($Release.Version) ($($Release.PackageName), SHA256 $Hash)" + "Published $($Release.ModuleName) $($Release.Version), SHA256 $Hash" | Add-Content -Path $env:GITHUB_STEP_SUMMARY github-release: name: Create the GitHub Release @@ -164,8 +185,32 @@ jobs: name: release path: release + # Safe to re-run: an existing release is left as it is - name: Create Release env: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} - run: gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md + run: | + if gh release view "$GITHUB_REF_NAME" > /dev/null 2>&1; then + echo "Release $GITHUB_REF_NAME already exists." + else + gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md + fi + + # Last, and never a failure: the upload succeeded, but the Gallery can take a while to validate and list it + - name: Wait until the Gallery lists the version + shell: pwsh + run: | + try { + $Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json + foreach ($Attempt in 1..20) { + $Found = Find-PSResource -Name $Release.ModuleName -Version $Release.Version -Repository PSGallery ` + -ErrorAction SilentlyContinue + if ($Found) { Write-Host "The Gallery lists $($Found.Name) $($Found.Version)"; exit 0 } + Start-Sleep -Seconds 30 + } + Write-Warning 'The Gallery does not list the version yet. Check the package page before announcing it.' + } catch { + Write-Warning "Could not ask the Gallery for the version: $($_.Exception.Message)" + } + exit 0 diff --git a/AGENTS.md b/AGENTS.md index b3c2717..b54d28f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,7 +46,11 @@ Invoke-Pester -Path ./Tests/ConnectWiseControlAPI.Private.Tests.ps1 ./Build/Update-Help.ps1 ``` -Tooling: PowerShell 7 for the build; Pester 5.7.1+, PSScriptAnalyzer, platyPS 0.14.x (`RequiredModules.psd1`). +Tooling: PowerShell 7 for the build. Every tool version (Sampler, ModuleBuilder, InvokeBuild, powershell-yaml, +Pester 5.7.1, PSScriptAnalyzer, platyPS 0.14.2) is pinned exactly in `RequiredModules.psd1`, the only place versions +are written. The first build resolves them into `output/RequiredModules`; `Tests/test-local.ps1` imports each tool +at its pinned version and fails if it is missing. To raise a pin, change the file in a PR and delete +`output/RequiredModules`. `Tests/ConnectWiseControlAPI.Live.Tests.ps1` skips unless `$env:CWC_SERVER`, `CWC_USER` and `CWC_PASSWORD` are set. `Tests/Live/Invoke-CWCLiveSmokeTest.ps1` checks behaviour against a real server (read-only unless `-AllowWrites`). @@ -59,10 +63,12 @@ Tooling: PowerShell 7 for the build; Pester 5.7.1+, PSScriptAnalyzer, platyPS 0. | --- | --- | | Build module | `./build.ps1` (Sampler/ModuleBuilder); `Test-ModuleManifest` on source and built manifests | | Pester (PowerShell 7) / Pester (Windows PowerShell 5.1) | Full Pester suite against the built module, both editions | -| PSScriptAnalyzer | Zero analyzer errors in `source/` | +| PSScriptAnalyzer | No analyzer errors in `source/`, and nothing from three rules that block at any severity: `PSUseCompatibleSyntax`, `PSAvoidUsingPlainTextForPassword`, `PSUsePSCredentialType` | | Docs drift | `Build/Update-Help.ps1` leaves no diff | -`.github/workflows/pr-validation.yml` warns when a PR doesn't update `CHANGELOG.md`. +Only the build job downloads tools from the Gallery; the other jobs get `output/RequiredModules` as an artifact. +A Pester run in which no test passes fails. `.github/workflows/pr-validation.yml` warns when a PR doesn't update +`CHANGELOG.md`. ### Releasing @@ -72,18 +78,31 @@ every step below needs the owner's explicit go. 1. Release PR: set `ModuleVersion` in `source/.psd1` (three parts), rename the CHANGELOG's `## [Unreleased]` notes to `## [] - ` (leave an empty `[Unreleased]` above it) and update the compare links at the bottom. Merge it. -2. Dry run: run the **Release** workflow by hand (`gh workflow run release.yml`). It checks, builds, tests and - packages, and publishes nothing. Locally: `./Build/Get-ReleaseInfo.ps1`, then `./Tests/test-local.ps1`, then - `./Build/Test-ReleasePackage.ps1`. -3. Tag the merged commit on `master` as `v` and push the tag. The workflow fails before building unless - the tag equals `ModuleVersion`, the CHANGELOG has the dated section, the version is not on the Gallery and the - commit is on `master`. +2. Dry run on the exact commit that will be tagged: run the **Release** workflow by hand + (`gh workflow run release.yml --ref master`). It checks, builds, tests and packages, and publishes nothing. + Locally: `./Build/Get-ReleaseInfo.ps1`, then `./Tests/test-local.ps1`, then `./Build/Test-ReleasePackage.ps1`. +3. Tag that commit and push only that tag (never `--tags`): + `git fetch origin; git tag -a v origin/master -m "v"; git push origin v`. + The workflow fails before building unless the tag equals `ModuleVersion`, the CHANGELOG has the dated section, + the version is not on the Gallery and the commit is on `master`. 4. The `publish` job waits for the owner's approval in the `psgallery` environment, which holds the - `PSGALLERY_API_KEY` secret. Agents never see or handle that key. The job publishes the `.nupkg` the package - check tested, after comparing its SHA256. After the publish, the workflow creates the GitHub Release from the - CHANGELOG section. + `PSGALLERY_API_KEY` secret. Agents never see or handle that key. Before approving, check that the commit in + the run summary is the `master` commit that was reviewed; to cancel, reject the deployment. The job publishes + the `.nupkg` the package check tested, after comparing its SHA256 with the one the build job reported. +5. The workflow then creates the GitHub Release from the CHANGELOG section and waits for the Gallery to list the + version. If it warns that the Gallery does not list it yet, check the package page before announcing. -If the publish succeeded and a later job failed, re-run only the failed job; never re-run the publish. +When a release run fails: + +| What happened | What to do | +| --- | --- | +| A job failed before `publish` | Nothing was published. For a flaky download, "Re-run failed jobs". A re-run uses the same commit and workflow file, so for a real fault delete the tag (`git push origin :refs/tags/v`), fix it in a PR, dry-run and tag again. | +| `publish` failed or timed out | Look at `https://www.powershellgallery.com/packages//`, then "Re-run failed jobs". The job asks the Gallery first: if the version is there it uploads nothing and goes on to the GitHub Release; if not, it uploads. It needs the owner's approval again. | +| `github-release` failed | "Re-run failed jobs". It leaves an existing release alone. | +| "Re-run all jobs" after a successful publish | Fails at the first check ("already on the PowerShell Gallery"). That is intended; nothing needs fixing. | +| The upload itself cannot work from the runner | Download the run's `release` artifact and run `Publish-PSResource -NupkgPath -Repository PSGallery -ApiKey ` locally (owner only), then "Re-run failed jobs" to create the release. | + +The `release` artifact is kept for 30 days; re-runs need it. ## Architecture diff --git a/CHANGELOG.md b/CHANGELOG.md index 66cafa9..c5a26c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -165,6 +165,10 @@ Changes to the repository. They do not change the published module. tag against the manifest and this changelog, builds, runs every test stage, checks the package installs on both editions, publishes to the PowerShell Gallery after the owner approves, and creates the GitHub Release. A manual run is a dry run that publishes nothing +- Build, test and docs tools are pinned to exact versions in `RequiredModules.psd1`. CI downloads them once per + run and shares them between jobs, and `Tests/test-local.ps1` imports each tool at its pinned version +- The analyzer stage also fails on the warnings `PSAvoidUsingPlainTextForPassword` and `PSUsePSCredentialType`, + and lists its other findings by rule; a Pester run in which no test passes fails - Repository layout follows the GitHub-Template (Sampler): the module source moved from `ConnectWiseControlAPI/` to `source/` (`Extensions/Remote Workforce` is now `Extensions/RemoteWorkforce`; the `Launcher` extension folder was the Remote Workforce extension) and `./build.ps1` builds the published module into diff --git a/RequiredModules.psd1 b/RequiredModules.psd1 index 2ba1060..88bff76 100644 --- a/RequiredModules.psd1 +++ b/RequiredModules.psd1 @@ -7,22 +7,23 @@ } } - # Versions use NuGet range syntax (passed to Save-PSResource -Version): - # '[5.7.1,6.0.0)' = 5.7.1 or newer, below 6.0.0 (newest match wins) - # .build/required-modules.ps1 (task Assert_RequiredModule_Versions) fails the build if a resolved - # version falls outside its range. + # Every version is exact. These modules build, test and document the package that is published, and a + # Gallery version can never be replaced, so an exact version is also a pin on the content. Raise a pin on + # purpose, in a pull request, and delete output/RequiredModules to resolve again. + # .build/required-modules.ps1 (task Assert_RequiredModule_Versions) fails the build if a resolved version + # is not the pinned one. This file is the only place the versions are written: CI, the release workflow + # and Tests/test-local.ps1 all read it. + # Not pinned here: the modules these depend on (Configuration, Metadata, Plaster, PSDepend). - # Bounded: breaking changes have landed (or would land) in these - Sampler = '[0.120.1,0.121.0)' # 0.x: minor versions may break tasks - ModuleBuilder = '[3.2.18,4.0.0)' - # Exact: same versions as the env: block in .github/workflows/ci.yml, so a local run matches CI. - # Pester 5 and platyPS 0.14 (not the template's Pester 6 / PlatyPS 1.x): the suite runs on Windows - # PowerShell 5.1 and Build/Update-Help.ps1 produces MAML for Get-Help on 5.1. See AGENTS.md. + # Build + Sampler = '0.120.1' + ModuleBuilder = '3.2.18' # writes the built .psm1 and .psd1 + InvokeBuild = '5.14.23' + 'powershell-yaml' = '0.4.12' + + # Test and docs. Pester 5 and platyPS 0.14 (not the template's Pester 6 / PlatyPS 1.x): the suite runs on + # Windows PowerShell 5.1 and Build/Update-Help.ps1 produces MAML. See AGENTS.md. Pester = '5.7.1' PSScriptAnalyzer = '1.24.0' platyPS = '0.14.2' - - # Floating: low risk (build tooling only) - InvokeBuild = 'latest' - 'powershell-yaml' = 'latest' } diff --git a/Tests/test-local.ps1 b/Tests/test-local.ps1 index f4136a5..424ac7e 100644 --- a/Tests/test-local.ps1 +++ b/Tests/test-local.ps1 @@ -73,6 +73,21 @@ function Add-RequiredModulesPath { } Add-RequiredModulesPath +# Tools are imported at the exact version pinned in RequiredModules.psd1, never "whatever is installed": a runner +# image or a developer machine can have another Pester or PSScriptAnalyzer earlier on the module path. +$PinnedModules = Import-PowerShellDataFile -Path (Join-Path $RepoRoot 'RequiredModules.psd1') +function Import-PinnedModule([string]$Name) { + $Pin = "$($PinnedModules[$Name])" + if ($Pin -notmatch '^\d+(\.\d+){1,3}$') { throw "RequiredModules.psd1 has no exact version for $Name ('$Pin')." } + try { + Import-Module $Name -RequiredVersion $Pin -ErrorAction Stop + } catch { + throw ("$Name $Pin is not available: $($_.Exception.Message) Run './Tests/test-local.ps1 -Stage Build' " + + "once to resolve it into output/RequiredModules, or Install-Module $Name -RequiredVersion $Pin.") + } + Write-Host "Using $Name $((Get-Module $Name).Version)" +} + function Write-Stage([string]$Name) { Write-Host '' Write-Host "=== $Name ($($PSVersionTable.PSEdition) $($PSVersionTable.PSVersion)) ===" -ForegroundColor Cyan @@ -110,15 +125,25 @@ if ($Stage -contains 'Build') { if ($Stage -contains 'Analyze') { Write-Stage 'Analyze' - Import-Module PSScriptAnalyzer -ErrorAction Stop + Import-PinnedModule PSScriptAnalyzer $Results = @(Invoke-ScriptAnalyzer -Path $SourceFolder -Recurse -ErrorAction Stop ` -Settings (Join-Path $RepoRoot '.PSScriptAnalyzerSettings.psd1')) - $Errors = @($Results | Where-Object Severity -EQ 'Error') + # Errors fail the stage (a file that does not parse stops Invoke-ScriptAnalyzer through -ErrorAction Stop). + # These rules also fail it, whatever severity they report: + # PSUseCompatibleSyntax is the only check behind the manifest's PowerShellVersion = '3.0' (the 5.1 test run + # cannot catch syntax that 5.1 accepts and 3.0 does not); the other two are warnings that keep secrets out + # of [string] parameters. + $BlockingRules = 'PSUseCompatibleSyntax', 'PSAvoidUsingPlainTextForPassword', 'PSUsePSCredentialType' + $Errors = @($Results | Where-Object { + "$($_.Severity)" -in 'Error', 'ParseError' -or $_.RuleName -in $BlockingRules + }) if ($Errors) { $Errors | Format-Table RuleName, ScriptName, Line, Message -AutoSize -Wrap | Out-String | Write-Host $Failures.Add("PSScriptAnalyzer: $($Errors.Count) error(s)") } Write-Host "PSScriptAnalyzer: $($Errors.Count) error(s), $($Results.Count - $Errors.Count) other finding(s)" + $Results | Where-Object { $Errors -notcontains $_ } | Group-Object RuleName | Sort-Object Count -Descending | + ForEach-Object { Write-Host (' {0,4} {1}' -f $_.Count, $_.Name) } } if ($Stage -contains 'Manifest') { @@ -163,7 +188,7 @@ if ($Stage -contains 'Test') { Write-Host "Testing $(Get-DisplayPath $TestTarget)" $env:MODULE_TEST_PATH = $TestTarget try { - Import-Module Pester -MinimumVersion 5.7.1 -ErrorAction Stop + Import-PinnedModule Pester $Config = New-PesterConfiguration $Config.Run.Path = Join-Path $RepoRoot 'Tests' $Config.Run.PassThru = $true @@ -185,6 +210,10 @@ if ($Stage -contains 'Test') { if ($Result.FailedCount -gt 0 -or $Result.Result -ne 'Passed') { $Failures.Add("Pester ($($PSVersionTable.PSEdition)): $($Result.FailedCount) failed, result $($Result.Result)") } + # Pester reports 'Passed' when it found nothing to run (a wrong path, renamed files) + if ($Result.PassedCount -eq 0) { + $Failures.Add("Pester ($($PSVersionTable.PSEdition)): no test passed ($($Result.TotalCount) found)") + } $CanRunDesktop = $PSVersionTable.PSEdition -eq 'Core' -and $IsWindows -and (Get-Command powershell.exe -ErrorAction SilentlyContinue) @@ -213,9 +242,11 @@ if ($Stage -contains 'Docs') { (git -C $RepoRoot ls-files --others --exclude-standard -- $GeneratedPaths) -join "`n" } $Before = (& $GetSnapshot) -join "`n" + # Loaded here at the pinned version; Update-Help.ps1's own Import-Module platyPS then finds it loaded + Import-PinnedModule platyPS & (Join-Path $RepoRoot 'Build/Update-Help.ps1') -ErrorAction Stop $After = (& $GetSnapshot) -join "`n" - if ($Before -ne $After) { + if ($Before -cne $After) { git -C $RepoRoot status --porcelain -- $GeneratedPaths | Write-Host $Failures.Add('Docs drift: ./Build/Update-Help.ps1 changed generated help; review and commit the result') } else { From aea5daa292594b3ec6ea93e48e09659d24012331 Mon Sep 17 00:00:00 2001 From: Chris Taylor Date: Tue, 10 Nov 2026 22:11:16 -0700 Subject: [PATCH 2/3] test-local: fail the Build stage when no module was built; retry resolve build.ps1 exits 0 after an aborted build, so the stage reported success when a Gallery download failed (HTTP 502) and no module was written. The stage now requires a manifest written by the build, and repeats a failed first-time resolve of the build tools from an empty folder. Co-Authored-By: Claude --- AGENTS.md | 4 ++-- Tests/test-local.ps1 | 29 ++++++++++++++++++++++++----- 2 files changed, 26 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b54d28f..d9ca7cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -96,11 +96,11 @@ When a release run fails: | What happened | What to do | | --- | --- | -| A job failed before `publish` | Nothing was published. For a flaky download, "Re-run failed jobs". A re-run uses the same commit and workflow file, so for a real fault delete the tag (`git push origin :refs/tags/v`), fix it in a PR, dry-run and tag again. | +| A job failed before `publish` | Nothing was published. A failed download of the build tools is retried twice by the build itself; if it still fails, "Re-run failed jobs". A re-run uses the same commit and workflow file, so for a real fault delete the tag (`git push origin :refs/tags/v`), fix it in a PR, dry-run and tag again. | | `publish` failed or timed out | Look at `https://www.powershellgallery.com/packages//`, then "Re-run failed jobs". The job asks the Gallery first: if the version is there it uploads nothing and goes on to the GitHub Release; if not, it uploads. It needs the owner's approval again. | | `github-release` failed | "Re-run failed jobs". It leaves an existing release alone. | | "Re-run all jobs" after a successful publish | Fails at the first check ("already on the PowerShell Gallery"). That is intended; nothing needs fixing. | -| The upload itself cannot work from the runner | Download the run's `release` artifact and run `Publish-PSResource -NupkgPath -Repository PSGallery -ApiKey ` locally (owner only), then "Re-run failed jobs" to create the release. | +| The upload itself cannot work from the runner | Download the run's `release` artifact and run `Publish-PSResource -NupkgPath -Repository PSGallery -ApiKey ` locally (owner only), then "Re-run failed jobs" to create the release. Do not use `Publish-Module` on the built folder: it adds the command tags a second time, which exceeds the Gallery's tag limit. | The `release` artifact is kept for 30 days; re-runs need it. diff --git a/Tests/test-local.ps1 b/Tests/test-local.ps1 index 424ac7e..f60a5ec 100644 --- a/Tests/test-local.ps1 +++ b/Tests/test-local.ps1 @@ -108,14 +108,33 @@ if ($Stage -contains 'Build') { $Failures.Add('Build: needs PowerShell 7 (run ./build.ps1 from pwsh)') } else { $BuildArgs = @('-NoProfile', '-File', (Join-Path $RepoRoot 'build.ps1'), '-Tasks', 'build') - # Resolve dependencies only once: re-resolving 'latest' modules piles up versions side by side, which the - # Assert_RequiredModule_Versions task rejects. Delete output/RequiredModules to refresh them. - if (-not (Test-Path $RequiredModulesPath)) { $BuildArgs += '-ResolveDependency' } + # Resolve dependencies only when output/RequiredModules is missing. Delete that folder to resolve again + # (after changing a pin in RequiredModules.psd1). + $Resolve = -not (Test-Path $RequiredModulesPath) + if ($Resolve) { $BuildArgs += '-ResolveDependency' } # Pin the version to the manifest: Sampler would otherwise use GitVersion when it is installed. $SavedBuildVersion = $env:ModuleVersion $env:ModuleVersion = (Import-PowerShellDataFile -Path $ManifestPath).ModuleVersion - & (Get-Process -Id $PID).Path @BuildArgs - if ($LASTEXITCODE -ne 0) { $Failures.Add("Build: build.ps1 exited with $LASTEXITCODE") } + # The PowerShell Gallery sometimes fails a download (HTTP 502). A half-filled RequiredModules folder cannot + # be repaired, so a failed first-time resolve is repeated from an empty folder. + $Attempts = if ($Resolve) { 3 } else { 1 } + for ($Attempt = 1; $Attempt -le $Attempts; $Attempt++) { + $BuildStarted = [DateTime]::UtcNow + & (Get-Process -Id $PID).Path @BuildArgs + $BuildExit = $LASTEXITCODE + # build.ps1 can exit 0 after an aborted build, so also require a manifest written by this attempt + $Built = Get-BuiltManifest + $BuildWroteModule = $Built -and $Built.LastWriteTimeUtc -ge $BuildStarted.AddSeconds(-2) + if (($BuildExit -eq 0 -and $BuildWroteModule) -or $Attempt -eq $Attempts) { break } + Write-Warning "Build attempt $Attempt of $Attempts failed; resolving the build tools again in 20 seconds." + Remove-Item -Path $RequiredModulesPath -Recurse -Force -ErrorAction SilentlyContinue + Start-Sleep -Seconds 20 + } + if ($BuildExit -ne 0) { + $Failures.Add("Build: build.ps1 exited with $BuildExit") + } elseif (-not $BuildWroteModule) { + $Failures.Add('Build: build.ps1 exited with 0 but wrote no built module (see the build output above)') + } $env:ModuleVersion = $SavedBuildVersion # On a clean checkout the build has only just created output/RequiredModules; the later stages need it # (the release workflow runs every stage in one call on a runner that has no platyPS). From 1625e67bce31cd5e5aa3a05a29c359818787fd37 Mon Sep 17 00:00:00 2001 From: Chris Taylor Date: Thu, 12 Nov 2026 09:56:08 -0700 Subject: [PATCH 3/3] Address review of the release and CI hardening CI: runs outside pull requests get a concurrency group per commit, so a waiting master run is never replaced; the tools artifact is kept as long as the build artifact. test-local: repeat the build only when a pinned tool is missing, remove a half-filled tools folder after the last attempt too, and require the manifest of the version being built. Release: a version found on the Gallery fails a first attempt and is accepted only on a re-run; a conflict on a re-run counts as uploaded; a draft release for the tag is published. AGENTS.md tags the dry-run SHA. Co-Authored-By: Claude Fable 5.2 --- .github/workflows/ci.yml | 8 ++++---- .github/workflows/release.yml | 32 ++++++++++++++++++++++++++------ AGENTS.md | 5 +++-- Tests/test-local.ps1 | 19 ++++++++++++++----- 4 files changed, 47 insertions(+), 17 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6944297..57bf7ce 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -30,10 +30,10 @@ on: permissions: contents: read -# A newer push to a pull request cancels the older run. Runs on master are never cancelled, so every merged -# commit gets a result. +# A newer push to a pull request cancels the older run. Other runs get a group of their own (the commit), so a +# run on master is never cancelled or replaced while it waits, and every merged commit gets a result. concurrency: - group: ci-${{ github.ref }} + group: ci-${{ github.event_name == 'pull_request' && github.ref || github.sha }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: @@ -69,7 +69,7 @@ jobs: name: required-modules path: output/RequiredModules/ if-no-files-found: error - retention-days: 1 + retention-days: 7 # as long as module-build: a job re-run later still needs it test: name: Pester (${{ matrix.name }}) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 5d3826a..11c2cfc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -159,14 +159,31 @@ jobs: if ($Status -ne 404) { throw "Could not check the PowerShell Gallery (HTTP $Status): $($_.Exception.Message)" } $Exists = $false } + $AlreadyThere = "Already on the Gallery: $($Release.ModuleName) $($Release.Version). Nothing was uploaded in this run." + $IsRerun = [int]$env:GITHUB_RUN_ATTEMPT -gt 1 if ($Exists) { - Write-Warning "$($Release.ModuleName) $($Release.Version) is already on the PowerShell Gallery. Nothing was uploaded." - "Already on the Gallery: $($Release.ModuleName) $($Release.Version). Nothing was uploaded in this run." | - Add-Content -Path $env:GITHUB_STEP_SUMMARY + # On the first attempt nothing in this run can have uploaded it, so it came from somewhere else + # and is not the package this run tested + if (-not $IsRerun) { + throw "$($Release.ModuleName) $($Release.Version) appeared on the PowerShell Gallery after the build job checked, and this run did not upload it." + } + Write-Warning $AlreadyThere + $AlreadyThere | Add-Content -Path $env:GITHUB_STEP_SUMMARY exit 0 } - Publish-PSResource -NupkgPath $Package -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY + try { + Publish-PSResource -NupkgPath $Package -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY -ErrorAction Stop + } catch { + # A version the Gallery is still validating can answer 404 above; a re-run then gets a conflict + # here, which means the earlier attempt's upload went through + if ($IsRerun -and "$($_.Exception.Message)" -match '409|Conflict|already exists') { + Write-Warning "$AlreadyThere ($($_.Exception.Message))" + $AlreadyThere | Add-Content -Path $env:GITHUB_STEP_SUMMARY + exit 0 + } + throw + } Write-Host "Published $($Release.ModuleName) $($Release.Version) ($($Release.PackageName), SHA256 $Hash)" "Published $($Release.ModuleName) $($Release.Version), SHA256 $Hash" | Add-Content -Path $env:GITHUB_STEP_SUMMARY @@ -185,14 +202,17 @@ jobs: name: release path: release - # Safe to re-run: an existing release is left as it is + # Safe to re-run: a published release is left as it is, and a draft for the tag is published with the notes - name: Create Release env: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} run: | - if gh release view "$GITHUB_REF_NAME" > /dev/null 2>&1; then + draft=$(gh release view "$GITHUB_REF_NAME" --json isDraft --jq .isDraft 2> /dev/null || echo none) + if [ "$draft" = "false" ]; then echo "Release $GITHUB_REF_NAME already exists." + elif [ "$draft" = "true" ]; then + gh release edit "$GITHUB_REF_NAME" --verify-tag --draft=false --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md else gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md fi diff --git a/AGENTS.md b/AGENTS.md index d9ca7cc..0a0f63d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,8 +81,9 @@ every step below needs the owner's explicit go. 2. Dry run on the exact commit that will be tagged: run the **Release** workflow by hand (`gh workflow run release.yml --ref master`). It checks, builds, tests and packages, and publishes nothing. Locally: `./Build/Get-ReleaseInfo.ps1`, then `./Tests/test-local.ps1`, then `./Build/Test-ReleasePackage.ps1`. -3. Tag that commit and push only that tag (never `--tags`): - `git fetch origin; git tag -a v origin/master -m "v"; git push origin v`. +3. Tag that commit by the SHA the dry run reported (not `origin/master`, which may have moved) and push only + that tag (never `--tags`): + `git fetch origin; git tag -a v -m "v"; git push origin v`. The workflow fails before building unless the tag equals `ModuleVersion`, the CHANGELOG has the dated section, the version is not on the Gallery and the commit is on `master`. 4. The `publish` job waits for the owner's approval in the `psgallery` environment, which holds the diff --git a/Tests/test-local.ps1 b/Tests/test-local.ps1 index f60a5ec..7f836a3 100644 --- a/Tests/test-local.ps1 +++ b/Tests/test-local.ps1 @@ -117,17 +117,26 @@ if ($Stage -contains 'Build') { $env:ModuleVersion = (Import-PowerShellDataFile -Path $ManifestPath).ModuleVersion # The PowerShell Gallery sometimes fails a download (HTTP 502). A half-filled RequiredModules folder cannot # be repaired, so a failed first-time resolve is repeated from an empty folder. + # Only a resolve that left a pinned tool out is repeated: a build fault would fail the same way again. $Attempts = if ($Resolve) { 3 } else { 1 } + $ExpectedManifest = Join-Path $RepoRoot "output/$ModuleName/$($env:ModuleVersion)/$ModuleName.psd1" for ($Attempt = 1; $Attempt -le $Attempts; $Attempt++) { $BuildStarted = [DateTime]::UtcNow & (Get-Process -Id $PID).Path @BuildArgs $BuildExit = $LASTEXITCODE - # build.ps1 can exit 0 after an aborted build, so also require a manifest written by this attempt - $Built = Get-BuiltManifest - $BuildWroteModule = $Built -and $Built.LastWriteTimeUtc -ge $BuildStarted.AddSeconds(-2) - if (($BuildExit -eq 0 -and $BuildWroteModule) -or $Attempt -eq $Attempts) { break } - Write-Warning "Build attempt $Attempt of $Attempts failed; resolving the build tools again in 20 seconds." + # build.ps1 can exit 0 after an aborted build, so also require this version's manifest, written by + # this attempt (an older version folder left under output/ does not count) + $Built = Get-Item -Path $ExpectedManifest -ErrorAction SilentlyContinue + $BuildWroteModule = [bool]($Built -and $Built.LastWriteTimeUtc -ge $BuildStarted.AddSeconds(-2)) + if ($BuildExit -eq 0 -and $BuildWroteModule) { break } + $MissingTools = @($PinnedModules.Keys | Where-Object { $PinnedModules[$_] -is [string] } | + Where-Object { -not (Test-Path (Join-Path $RequiredModulesPath "$_/$($PinnedModules[$_])")) }) + if (-not $Resolve -or -not $MissingTools) { break } + # A half-filled folder is removed even after the last attempt, so the next run resolves again Remove-Item -Path $RequiredModulesPath -Recurse -Force -ErrorAction SilentlyContinue + if ($Attempt -eq $Attempts) { break } + Write-Warning ("Build attempt $Attempt of $Attempts did not resolve $($MissingTools -join ', '); " + + 'resolving the build tools again in 20 seconds.') Start-Sleep -Seconds 20 } if ($BuildExit -ne 0) {