Consolidate framework scripts into the PSMA action library, then move stable releases to push-to-main

[MariusStorhaug]

Context

Reported bug: the Plan/version logic resolves a prerelease on merge to the default branch (e.g. GoogleFonts run 29202094727). The desired model is: a prerelease exists only while a PR is open; when a change lands on the default branch it must be a stable release or nothing — never a prerelease. The clean way to make that structural (rather than a conditional) is to drive stable releases from a push to main trigger (#84) instead of the pull_request: closed (merged) event.

Two ways to get there:

1. Implement push-to-main (Support running the workflow on push to main #84) on the current scattered actions, or
2. Consolidate the framework scripts into the PSMA action library first, then build push-to-main in one place.

Decision

Consolidate into PSMA first, then build #84 there. The reported bug is already neutralized by the architecture-independent stopgap Resolve-PSModuleVersion#11 ("prerelease only for open PRs"), so there is no pressure to rush #84 onto the old layout and port it twice.

Why consolidate first

#84 changes exactly the scripts PSMA will absorb, so doing it on the scattered repos is largely throwaway:

• Get-PSModuleSettings — ReleaseType/Run.* are keyed off isMergedPR (pull_request closed+merged); push-to-default needs new detection.
• Resolve-PSModuleVersion — version comes from PR labels; on push the PR must be resolved from the merge commit (GET /repos/{owner}/{repo}/commits/{sha}/pulls, verified working).
• Publish-PSModule — the blocker: both src/publish.ps1 and src/cleanup.ps1 hard-throw without a pull_request and derive everything from it (head ref as prerelease --target, PR number for comments, title/body for notes). This is where the prerelease-path (PR) vs stable-path (push) split belongs (see Publish-PSModule: Split Gallery publishing from GitHub Release creation #330).

In the scattered model the event→prerelease/stable routing is smeared across 3 action repos + workflow.yml + every consumer caller (3 releases, 3 pin bumps). In PSMA it is one main.ps1 dispatcher deciding the route once.

The PSMA library

PSModule/PSMA — "PSModule Actions: one library-backed action dispatched by Mode". One internal PS module holds all framework logic (settings/version/build/test/publish/docs/coverage/results); one composite action switches on Mode. Foundation: PR #1 initialize-psma-library (green, mergeable; currently working skeletons with PORT FROM: markers). Cross-repo action resolution is solved via the OIDC job_workflow_sha self-checkout (proven), so consumers pass nothing extra.

Plan

Phase 1 — land the PSMA foundation

• Merge PSMA PR Adding initial release to the workflow #1 (skeleton library + mode-dispatched action).

Phase 2 — port real logic into PSMA (one PR each, keep tests/fixtures — closes #347)

• Install-PSModuleHelpers (the shared leaf) → module private helpers
• Get-PSModuleSettings → Mode: Settings
• Resolve-PSModuleVersion → Mode: Version
• Build-PSModule → Mode: Build
• Test-PSModule / Get-PesterCodeCoverage / Get-PesterTestResults → test modes
• Document-PSModule → Mode: Docs
• Publish-PSModule → Mode: Publish (split Gallery publish vs GitHub Release — Publish-PSModule: Split Gallery publishing from GitHub Release creation #330/Separate GitHub Release creation from PowerShell Gallery publishing #210)

Phase 3 — re-point orchestration

• Point Process-PSModule reusable sub-workflows at PSMA (self-checkout via OIDC job_workflow_sha).

Phase 4 — push-to-main release model (#84) in PSMA

• Add push: branches: [main] to the caller template (+ consumers).
• On push: map merge commit → PR (labels/title/body/head ref) via the commits→pulls API.
• Route in the dispatcher: pull_request (open) → prerelease/preview; push to default → stable release; pull_request: closed → prerelease cleanup only.
• Retire the pull_request: closed (merged) release path.

Acceptance criteria

• A prerelease is only ever produced while a PR is open; a merge/push to the default branch never shows a prerelease.
• Stable releases are cut by push to main, with PR context resolved from the merge commit.
• Framework logic lives in one library (PSMA); the event→release routing exists in exactly one place.
• Existing consumers keep working with no extra inputs.

Related

• Support running the workflow on push to main #84 (push to main) · Refactor framework toward event-oriented architecture #79 (event-oriented architecture) · Publish-PSModule: Split Gallery publishing from GitHub Release creation #330 / Separate GitHub Release creation from PowerShell Gallery publishing #210 (split publish) · Move version calculation to a Plan job (Resolve-PSModuleVersion) so Build and Publish never calculate or mutate versions #326 / Move version generation from Publish to Build step #176 (version→Plan) · Consolidate test fixtures into a shared repository for all -PSModule actions #347 (shared fixtures) · Bring all action repositories into compliance with the GitHub Actions standard #360 (action compliance) · 🚀 [Feature]: Track downstream action-version bumps with a central tracking issue and per-consumer sub-issues #374 (track version bumps)
• Stopgap: 🪲 [Fix]: Only resolve a prerelease for open pull requests Resolve-PSModuleVersion#11
• Library: PSModule/PSMA + PR Adding initial release to the workflow #1

Captures the design decision from earlier research; opened for tracking. Adjust scope/order as needed.

[MariusStorhaug]

Update — approach refined and started.

The earlier PSMA skeleton (one mode-switch action) was replaced with a cleaner subfolder-actions approach:

1. Deleted the old PSMA and recreated it from the PSModule/Template-Action template.
2. Move framework actions into per-action folders (as-is) PSMA#1 (green, mergeable) moves the 9 framework actions into per-action folders as-is — each keeps its own action.yml + src/scripts + tests, so it stays usable as PSModule/PSMA/<Action>@<ref> during migration: Build-PSModule, Test-PSModule, Publish-PSModule, Get-PSModuleSettings, Resolve-PSModuleVersion, Install-PSModuleHelpers, Document-PSModule, Get-PesterCodeCoverage, Get-PesterTestResults.

Note: consolidating into one repo makes super-linter lint the whole tree at once (standalone repos only lint changed files), which surfaced the framework's intentional Write-Host logging — excluded via PSAvoidUsingWriteHost in the repo PSScriptAnalyzer settings.

Next: (a) move any inline action.yml logic into the ps1 files (mostly no-op — thin wrappers), (b) consolidate shared functions into a common PSMA module + a root main.ps1 dispatched by activity, then re-point the sub-workflows here.

[MariusStorhaug]

Phase 1 done ✅ — PSMA PR #1 merged (squash), so main now holds the 9 framework actions as per-action folders, and Auto-Release cut PSMA v0.0.1 (Latest; v0.0/v0 moving tags). Actions are now pinnable at PSModule/PSMA/<Action>@v0.0.1.

Next: the simplification — (a) move any inline action.yml logic into the ps1 files (mostly no-op — thin wrappers), then (b) consolidate shared functions into a common PSMA module + root main.ps1 dispatched by activity, and re-point the Process-PSModule sub-workflows at PSMA (@v0.0.1/tag) — proven working on the test/use-psma-actions branch (MariusTestModule PR #38 run was green).

[MariusStorhaug]

Tests-first baseline in place — PSModule/PSMA#2 (all checks green, mergeable) wires each folded action''s own tests into PSMA CI: Resolve-PSModuleVersion (Pester, 188 tests), Install-PSModuleHelpers (regression scripts), Get-PSModuleSettings (valid + invalid scenarios), Test-PSModule (Src-Default / Src-WithManifest / outputs fixtures across Linux/macOS/Windows). All pass, so the individual action tests are proven to work in the consolidated repo.

This is the safety net for step 5 (shared PSMA module + main.ps1 dispatcher), which will now refactor under a green suite. Advances #347 (colocated tests).