Skip to content

fix(website): the build no longer fails when the PowerShell Gallery hiccups - #2707

Merged
merill merged 2 commits into
maester365:mainfrom
earbona23:fix/website-platyps-install-is-a-single-point-of-failure
Nov 7, 2026
Merged

merill merged 2 commits into
maester365:mainfrom
earbona23:fix/website-platyps-install-is-a-single-point-of-failure

Conversation

@earbona23

@earbona23 earbona23 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

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/ 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 only line that surfaces as the failure is the last one. The prepare-data: Generate the command reference step spent just over five minutes retrying inside Install-Module before giving up. #2603 is failing the same way right now, and it reproduced across two runs of #2702.

Two changes

Install-PinnedModule in build/Update-CommandReference.ps1 replaces the three bare Install-Module calls:

  • returns immediately when the pinned version is already present, so a warm cache never touches the Gallery;
  • retries a failed download three times with a growing pause;
  • throws naming the module, the version and the Gallery when it still cannot be had.

That last point is the real fix for the confusing message. 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. 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 pinned actions/cache that is already in the file. Its own Install-Module Microsoft.Graph.Authentication gets the same retry, inline.

Verified locally

  • The three paths of 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 naming PlatyPS 0.14.2 and the Gallery.
  • The YAML parses, and the cache step is ordered before both installs and before the build.
  • The PowerShell embedded in the workflow step parses.
  • ~/.local/share/powershell/Modules is the CurrentUser module path on Linux, confirmed from $env:PSModulePath.
  • Invoke-ScriptAnalyzer -Severity Error,Warning on the changed script: 0, which is what main reports for that file today. My first draft used Write-Host "::warning::" for the retry notice and that introduced a PSAvoidUsingWriteHost warning the file did not have, so it is Write-Warning instead — the hard failure is the throw, which Actions surfaces either way, and there is no existing convention in the repo's .ps1 files 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

  • Chores
    • Website builds now reuse cached PowerShell modules, reducing repeated setup work.
    • PowerShell module setup for website builds and command-reference generation now skips installation when required versions are already available and retries failed installations. If a required module remains unavailable, setup reports an error rather than continuing without it.

…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.
@earbona23
earbona23 requested a review from a team as a code owner November 6, 2026 16:43
@coderabbitai

coderabbitai Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The command-reference script now uses a helper to install pinned PowerShell modules. The website workflow caches PowerShell modules and retries installation of Microsoft.Graph.Authentication when the required version is unavailable.

Changes: PowerShell module installation

Layer / File(s) Summary
Pinned module installation helper
build/Update-CommandReference.ps1, powershell/tests/general/PesterVersionPinning.Tests.ps1
A helper checks for the requested version, retries installation up to three times, and throws an error if the version remains unavailable. The script uses it for Alt3.Docusaurus.Powershell, PlatyPS, and Pester. The test expects the helper call with Pester version 5.7.1.
Website workflow module setup
.github/workflows/build-website.yaml
The workflow caches PowerShell modules. It checks for Microsoft.Graph.Authentication version 2.27.0 or later, retries installation up to three times when needed, and fails if the module remains unavailable.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Possibly related PRs

  • maester365/maester#2661: Adds website command-reference generation and Microsoft.Graph.Authentication installation, which this change updates with caching and retries.

Suggested labels: bug, github_actions, area: build & ci, size: M

Suggested reviewers: merill

Merge Risk: Minimal · up to 33db8

The change adds installation retries and caching. No concrete merge-blocking issue remains.

Pre-merge checks: Passed 5

Check name Status Explanation
Title check Passed The title describes the website build fix for PowerShell Gallery failures.
Description check Passed The description explains the problem, changes, local verification, and cache verification limit. It omits the template's Checks and Additional Information sections.
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between d73e038 and 33db843.

Files selected for processing: 1

  • powershell/tests/general/PesterVersionPinning.Tests.ps1

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

@codacy-production

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

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.
@earbona23

Copy link
Copy Markdown
Contributor Author

build-validation (ubuntu-latest) was red and it was this change, not the runner.

powershell/tests/general/PesterVersionPinning.Tests.ps1 asserts that each place which installs Pester carries the literal 5.7.1 pin. For build/Update-CommandReference.ps1 it expected Install-Module Pester -RequiredVersion 5.7.1, and that install now goes through the retry helper, so the line reads Install-PinnedModule -Name Pester -Version '5.7.1'. The version was still pinned; the guard was matching the old spelling.

Updated the pattern the same way the repo already does for .github/workflows/build-validation.yaml, whose Pester install also goes through a helper and whose expectation carries a comment saying so.

Verified it still has teeth rather than just going green: with the file changed to 5.7.2 the suite reports 6 passed / 1 failed, and back at 5.7.1 it reports 7 passed / 0 failed. So a bumped or unpinned version is still caught.

Worth noting from the last run: Build Website passed on this branch, which is the behaviour the PR is for.

@earbona23

Copy link
Copy Markdown
Contributor Author

Correction to my previous comment, which claimed the passing Build website on this branch as evidence for the change. It is not, and I should not have offered it as such.

I retriggered #2702 — same workflow, without this fix — and its Build website passed too. So the Gallery recovered, and today's green on this branch does not distinguish the retry from a good day upstream. The honest statement is that I have not observed this change convert a Gallery failure into a success; what I have verified is the helper's three paths with the install and availability check stubbed (already present → no install call; transient → succeeds on the second attempt; permanent → three attempts, then throws naming the module, the version and the Gallery).

The case for it is therefore the failure mode itself rather than a measured recovery: the website build had a single unretried Install-Module for platyPS on the critical path, and when the Gallery served that invalid :8080 source location the job failed with MarkdownFiles is null, three steps away from the real cause. Whether that is worth a retry plus a cache, or a retry alone, is your call — I am happy to drop the cache step if you would rather not add one.

All 14 checks are green here, including build-validation on the three runners after the pinning-guard alignment above.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 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-PinnedModule helper 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

@earbona23

Copy link
Copy Markdown
Contributor Author

thks @SamErde

@merill
merill merged commit 679dbf6 into maester365:main Nov 7, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants