⚙️ [Maintenance]: Pinned PowerShell Gallery module versions kept current automatically

[Marius Storhaug (MariusStorhaug)]

Pinned PowerShell Gallery module versions now move on their own. The Pester version this repository's test suites run against is pinned exactly and verified by module GUID, which is the right posture for a CI pipeline — but only while something keeps that pin current. Dependabot has no PowerShell Gallery ecosystem, so nothing ever did, and the pin could only drift further behind the fixes Pester ships.

New: pinned Gallery versions are raised by an automated pull request

A workflow checks the Gallery for a newer release inside the range the test suites declare, and opens a labelled pull request when it finds one. Nothing changes about how tightly the pin is set — exact plus GUID stays exactly as it was, and only its movement is new. The update is reviewed and gated like any other change: a bump that breaks the suite turns the Test check red before it can merge.

The check runs weekly, on demand, and on every push to main. The last of those is deliberate: GitHub silently disables a scheduled workflow after 60 days of inactivity in a public repository, and a workflow that has stopped running looks exactly like one that ran and found nothing to do.

New: the gap is written down for every other repository

The Dependency Updates capability now records that the PowerShell Gallery is an ecosystem the platform updater does not cover, the pattern that fills the gap, how to notice if the schedule lapses, and the steps another repository follows to adopt it. It says plainly that the gap is Dependabot's, not a preference of this organization — so if the platform ever ships that ecosystem, the right response is to delete the bespoke updater and add a package-ecosystem entry.

---

Technical details

Decision. Of the three candidates in #136, the first was chosen — a scheduled workflow here, with the logic in a parameterised script so promoting it later is a move rather than a rewrite. The decision and the evidence are recorded in the issue's Technical decisions section.

• Declaring the dependency for an existing updater was ruled out by checking rather than assuming: dependabot/dependabot-core has no PowerShell ecosystem directory, and Renovate's lib/modules/datasource has no PowerShell Gallery datasource. Renovate could be coerced via a customManagers regex over the nuget datasource, but that is bespoke automation plus a second updater and an org-level app install.
• A reusable action was judged premature: a code search across MSXOrg for RequiredVersion returns exactly one pin — this repository's. PSModule/Invoke-Pester uses NuGet ranges, not exact pins, so it is not a waiting consumer. GitHub Actions → "Start local; promote when it is reused" is explicit about not paying for a shared release surface before there is a second consumer.

Files.

• .github/scripts/Update-GalleryModulePin.ps1 — parameterised by module name, target file, pin pattern (a regex with a version capture group), allowed range, and -GalleryUri. Only the captured group is rewritten; byte-order mark and line endings are preserved, and the GUID is never touched. A pattern matching nothing, a pattern matching several places, and an unreachable Gallery are all hard failures, so a broken lookup can never read as "already up to date".
• .github/workflows/Update-ModulePin.yml — permissions: {} floor, contents: write + pull-requests: write on the job, idempotent against an already-open pull request or an existing branch, and no auto-merge because identity-plus-exact is the one track Dependencies says is never auto-merged.
• tests/Update-GalleryModulePin.Tests.ps1 — 10 cases against an in-process HttpListener on a loopback port.
• src/docs/Capabilities/dependency-updates/design.md — extended rather than adding a page, so no src/zensical.toml nav entry was needed and the generated indexes stay valid.

The pin stays in Invoke-PesterSuite.ps1. A single-key data file would be a dependency manifest in all but name, which #136's non-goals forbid, and a parameter default is no harder to rewrite. -PinPattern is what makes the script indifferent to where a pin lives.

Verification.

What	How	Result
Opens a PR when a newer version exists	Ran the workflow's own steps against the real Gallery with the pin set back to 6.0.0	Opened #157 — one file, one line, dependencies + powershell + update:patch + Maintenance, GUID untouched. Closed in the same session, branches deleted.
Does nothing when it does not	Same commands with the pin at 6.0.1	updated=false, working tree clean, open pull-request count unchanged at 12
Does not open a duplicate	Re-ran the step with the PR already open	"already open. Nothing to do", still exactly one PR
A breaking bump fails Test	Commit 71007fe pinned Pester to 5.7.1	Run 31266574992 — Test failed, every suite's #Requires rejected it. Reverted in c6ea08e.
Fires, stays quiet, ceiling, prerelease, paging, identity, hard failures	tests/Update-GalleryModulePin.Tests.ps1	10 cases, offline, ~5s
Full suite	.github/scripts/Invoke-PesterSuite.ps1	64 passed, 0 failed
PowerShell lint	Invoke-ScriptAnalyzer with .github/linters/.powershell-psscriptanalyzer.psd1	Clean on both new files
Workflow security	zizmor	Clean across both workflows
Docs	Update-DocumentationIndex.ps1 -Check, Test-DocumentationLink.ps1, markdownlint	Pass; 114 files scanned, all links resolve

Two bugs were found by this work and fixed in it: a Gallery reporting exactly one version unrolled to a bare [version] and crashed under Set-StrictMode; and the new tests relied on member enumeration over the script's mixed output, which passed in isolation and failed under the full suite. zizmor's artipacked audit also flagged the updater's checkout persisting credentials — rather than suppress it, the checkout now sets persist-credentials: false and the single push that needs a token supplies it itself.

Labels. dependencies, powershell, update:major, update:minor and update:patch did not exist in this repository and were created once with gh label create; the workflow applies them but does not create them.

Branch name deviation. maintenance-136-gallery-pin-updates rather than maintenance/136-…. The app's rename_branch tool strips / and fires once per session, so the <type>/<issue>-<slug> form in Branching and Merging is unreachable from an app session. Nothing in CI keys off the branch name.

Standards and framework alignment

Changed surface	Standards checked	Framework docs checked	Result
.github/scripts/** (PowerShell)	PowerShell (Scripts, Functions, Naming, Documentation), Dependencies	Dependency Updates design	Aligned
.github/workflows/**	GitHub Actions (least-privilege permissions, untrusted input, concurrency, pinned SHAs and runner)	Dependency Updates design	Aligned
tests/**	Testing, PowerShell Testing	—	Aligned
src/docs/**	Markdown, Documentation Model	Capability spec-and-design shape	Aligned

Implementation plan progress. All seven items of #136's plan are complete and ticked.

Issue convergence sweep. Scope: open issues touching .github/ dependency automation and the Dependency Updates capability. #136 is the only one this diff satisfies; no additional closing keywords are used.

Related issues

• Fixes Keep pinned PowerShell Gallery module versions current without Dependabot #136