Repository navigation
fix(website): the build no longer fails when the PowerShell Gallery hiccups - #2707
Conversation
…iccups The website job installs three pinned modules through build/Update-CommandReference.ps1 and one more in the workflow, every run, with no cache and no retry. When the Gallery cannot serve one of them the job fails with an error four steps removed from the cause, which reads as a problem with the branch being built. Measured on a run of my own PR maester365#2702, whose diff is two test files and touches neither build/ nor website/: WARNING: Source Location 'http://www.powershellgallery.com:8080/api/v2/package/platyPS/0.14.2' is not valid. Install-Package: Package 'platyPS' failed to download. Import-Module: The specified module 'PlatyPS' with version '0.14.2' was not loaded because no valid module file was found in any module directory. New-MarkdownHelp: The term 'New-MarkdownHelp' is not recognized... NewSidebarIncludeFile: Cannot bind argument to parameter 'MarkdownFiles' because it is null. The Gallery handed the runner a source location on port 8080 over plain HTTP, the download failed, and the reported failure was the last line. The step spent just over five minutes retrying inside Install-Module before giving up. PR maester365#2603 is failing the same way. Two changes. Install-PinnedModule in build/Update-CommandReference.ps1 replaces the three bare Install-Module calls. It returns immediately when the pinned version is already present, retries a failed download three times with a growing pause, and throws naming the module, the version and the Gallery when it still cannot be had. Install-Module writes a non-terminating error on a failed download, so the old code carried on to the Import-Module calls and failed there instead, which is where the misleading message came from. The same helper also makes the script survivable when run by hand. The workflow caches ~/.local/share/powershell/Modules, keyed on the files that pin the versions, so on a hit the Gallery is not contacted at all. The job already caches the Open Graph cards this way, with the same pinned actions/cache. Its own Install-Module for Microsoft.Graph.Authentication gets the same retry, inline. Verified locally: the three paths of Install-PinnedModule (already present, transient failure that then succeeds, and permanent failure) with the install and availability checks stubbed; the YAML parses and the cache step is ordered before both installs; the embedded PowerShell parses; the cached path is the CurrentUser module path on Linux; and PSScriptAnalyzer reports no Error or Warning on the changed script, which is what main reports for it today. What I could not verify locally is the cache hit itself, since that needs the Actions cache.
|
No actionable comments were generated in the recent review. Walkthrough
Merge Risk:
|
Up to standards ✅🟢 Issues
|
The guard asserted the literal 'Install-Module Pester -RequiredVersion 5.7.1' in build/Update-CommandReference.ps1. That install now goes through the retry helper, so the pin reads 'Install-PinnedModule -Name Pester -Version 5.7.1' and the guard failed on ubuntu while the version was still pinned. Updated the pattern the same way the repo already does for .github/workflows/build-validation.yaml, whose install also goes through a helper. Verified with a negative control: changing the file to 5.7.2 fails the guard, so it still catches an unpinned or bumped version.
|
Updated the pattern the same way the repo already does for Verified it still has teeth rather than just going green: with the file changed to Worth noting from the last run: |
|
Correction to my previous comment, which claimed the passing I retriggered #2702 — same workflow, without this fix — and its The case for it is therefore the failure mode itself rather than a measured recovery: the website build had a single unretried All 14 checks are green here, including |
There was a problem hiding this comment.
🟢 Approval recommended
There are no active review issues for the PowerShell dependency installation and website-build resilience changes.
No open issues 🎉
What changed in this PR
This PR makes website builds more resilient to PowerShell Gallery failures by caching modules, retrying installation, and reporting dependency failures before command-reference generation continues.
Changes:
- Cache PowerShell modules and retry Microsoft.Graph.Authentication installation.
- Add an
Install-PinnedModulehelper that skips available versions, retries failed installs, and throws a clear error if installation fails. - Update the Pester version-pinning test to recognize the helper call.
| File | Description |
|---|---|
powershell/tests/general/PesterVersionPinning.Tests.ps1 |
Updates the pinning assertion for the new installation helper. |
build/Update-CommandReference.ps1 |
Adds retry and failure handling for pinned documentation dependencies. |
.github/workflows/build-website.yaml |
Caches PowerShell modules and retries Graph authentication module installation. |
Review effort: Balanced
|
thks @SamErde |
The website job installs four pinned PowerShell modules on every run, with no cache and no retry, so a bad moment at the PowerShell Gallery fails the build — and it fails it with an error four steps removed from the cause, which reads as a problem with the branch being built.
What the log actually says
From a run of my own #2702, whose diff is two test files and touches neither
build/norwebsite/:The Gallery handed the runner a source location on port 8080 over plain HTTP, the download failed, and the only line that surfaces as the failure is the last one. The
prepare-data: Generate the command referencestep spent just over five minutes retrying insideInstall-Modulebefore giving up. #2603 is failing the same way right now, and it reproduced across two runs of #2702.Two changes
Install-PinnedModuleinbuild/Update-CommandReference.ps1replaces the three bareInstall-Modulecalls:That last point is the real fix for the confusing message.
Install-Modulewrites a non-terminating error on a failed download, so the old code carried on to theImport-Modulecalls and failed there instead. The helper also makes the script survivable when a contributor runs it by hand.The workflow caches
~/.local/share/powershell/Modules, keyed on the files that pin the versions, so on a hit the Gallery is not contacted at all. The job already caches the Open Graph cards this way, and I reused the same pinnedactions/cachethat is already in the file. Its ownInstall-Module Microsoft.Graph.Authenticationgets the same retry, inline.Verified locally
Install-PinnedModule, with the install and the availability check stubbed: already present → no install call; transient failure → retries and succeeds on the second attempt without throwing; permanent failure → three attempts, then throws with a message namingPlatyPS 0.14.2and the Gallery.~/.local/share/powershell/Modulesis theCurrentUsermodule path on Linux, confirmed from$env:PSModulePath.Invoke-ScriptAnalyzer -Severity Error,Warningon the changed script: 0, which is whatmainreports for that file today. My first draft usedWrite-Host "::warning::"for the retry notice and that introduced aPSAvoidUsingWriteHostwarning the file did not have, so it isWrite-Warninginstead — the hard failure is thethrow, which Actions surfaces either way, and there is no existing convention in the repo's.ps1files for Actions annotations.What I could not verify locally is the cache hit itself, since that needs the Actions cache. The first run on this PR will be a cache miss by definition; the second should skip the installs.
If you would rather not cache and only keep the retry, or the other way round, say which and I will trim it.
Summary by CodeRabbit