🌟 [Major]: Standardize actions on GitHubVersion / GitHubPrerelease inputs for the bootstrap GitHub module

[MariusStorhaug]

A PSModule action runs its PowerShell through the shared GitHub-Script action, which installs the GitHub PowerShell module before the action's own script runs. The version of that bootstrap module can already be controlled through GitHub-Script's Version and Prerelease inputs, but the wrapping actions surface this capability inconsistently.

Across the action suite today:

• Most actions re-expose the control as Version / Prerelease (Get-PesterCodeCoverage, Get-PesterTestResults, Get-PSModuleSettings, Initialize-PSModule, Invoke-ScriptAnalyzer, Release-GHRepository, and Template-Action).
• Two actions do not expose it at all (Debug, Get-IssueFormData), so a workflow author cannot influence the module version for them.
• On actions that also wrap a primary tool, the name Version is ambiguous: on Invoke-Pester and Invoke-ScriptAnalyzer it reads like "the Pester / PSScriptAnalyzer version" but actually pins the background GitHub module.

Request

Current experience

A workflow author who wants to pin the GitHub module used by an action has to know that a given action happens to expose Version, that the name refers to the bootstrap module rather than the tool the action is named after, and that some actions do not expose it at all. On Invoke-Pester the confusion is acute — setting Version looks like it selects Pester, but it selects the GitHub module instead.

Desired experience

Every action that installs the GitHub module exposes the same, clearly-named pair of inputs to control it:

• GitHubVersion — the version (or version range) of the GitHub module to install.
• GitHubPrerelease — whether prerelease versions are allowed.

This frees Version / Prerelease to mean the action's own tool wherever one exists (Pester for Invoke-Pester, PSScriptAnalyzer for Invoke-ScriptAnalyzer), and gives a single, predictable name for the bootstrap module across the whole suite. This is the convention Invoke-Pester has already adopted in PSModule/Invoke-Pester#71 (Version/Prerelease now drive Pester; the bootstrap module moved to GitHubVersion/GitHubPrerelease); the remaining actions should follow it.

Acceptance criteria

• Every PSModule action that installs the GitHub module via GitHub-Script exposes GitHubVersion and GitHubPrerelease, with identical meaning on every action.
• On actions that wrap a primary tool, Version / Prerelease refer to that tool, never to the GitHub module.
• GitHubVersion accepts an exact version or a NuGet version range; GitHubPrerelease toggles prereleases.
• Leaving GitHubVersion unset preserves today's behavior (latest GitHub module) — no forced version change for existing callers beyond the input rename.
• Template-Action demonstrates the convention so newly generated actions inherit it automatically.

Important

This is a breaking change for the actions that currently expose Version / Prerelease for the module. A caller that passes Version: / Prerelease: to control the GitHub module must rename those to GitHubVersion: / GitHubPrerelease: (mirroring the migration described in PSModule/Invoke-Pester#71). Adding the inputs to Debug and Get-IssueFormData is additive.

---

Technical decisions

Input naming. Each consuming action exposes GitHubVersion and GitHubPrerelease and forwards them to GitHub-Script's existing Version and Prerelease inputs. The GitHub-prefix disambiguates the bootstrap module from the action's own tool and matches the convention already shipped in PSModule/Invoke-Pester#71.

Version / Prerelease semantics. These names are reserved for the action's primary tool where one exists — Pester for Invoke-Pester (PSModule/Invoke-Pester#68, PSModule/Invoke-Pester#71) and PSScriptAnalyzer for Invoke-ScriptAnalyzer. Actions without a separate tool (Debug, Get-IssueFormData, Get-PesterCodeCoverage, Get-PesterTestResults, Get-PSModuleSettings, Initialize-PSModule, Release-GHRepository, Template-Action) expose only GitHubVersion / GitHubPrerelease.

GitHub-Script is unchanged. It keeps Version / Prerelease as the low-level primitive (already extended to accept NuGet ranges in PSModule/GitHub-Script#97). Only the wrapping actions carry the prefixed names, so the base action stays generic.

Default behavior stays "latest". An unset GitHubVersion continues to install the latest GitHub module, matching GitHub-Script's behavior and the default chosen in PSModule/Invoke-Pester#71. This keeps the change limited to the rename and avoids a behavioral shift for existing callers.

Alternative considered — pin a default version constraint. Rather than exposing an input, each action could hard-pin the GitHub module to a known-good version/range (as suggested by "or set these to a version constraint"). Deferred as the default because it changes behavior for every caller and creates a second thing to bump on each GitHub release (comparable to the SHA-pin drift tracked in #329). Exposing GitHubVersion lets a caller opt into pinning now; adopting a pinned default across the suite is a separate policy decision that can be layered on later and relates to the dependency model in #356.

Value syntax + doc fix. GitHubVersion accepts an exact version or a NuGet version range, resolved by Install-PSResource -Version. Template-Action's current input description ("The value must be an exact version") is stale and should be corrected to reflect range support.

Rollout order. Update Template-Action first (the canonical source new actions are generated from), then each action repository. Invoke-Pester is already handled by PSModule/Invoke-Pester#71 and only needs verification here.

Scope boundary. This issue covers the GitHub-module input naming only. Wiring an action's Version input to actually drive its primary tool is tracked separately — Pester by PSModule/Invoke-Pester#68; an equivalent for PSScriptAnalyzer in Invoke-ScriptAnalyzer should be filed as its own follow-up.

Related work. PSModule/Invoke-Pester#68, PSModule/Invoke-Pester#71, PSModule/GitHub-Script#97, PSModule/GitHub-Script#95, #356, #329, #328.

---

Implementation plan

Template and base

• Template-Action: rename Version → GitHubVersion and Prerelease → GitHubPrerelease; forward them to GitHub-Script's Version / Prerelease; correct the "must be an exact version" description to state that a NuGet range is accepted.

Actions — rename existing Version / Prerelease

• Get-PesterCodeCoverage
• Get-PesterTestResults
• Get-PSModuleSettings
• Initialize-PSModule
• Release-GHRepository
• Invoke-ScriptAnalyzer — update both GitHub-Script steps (the analyzer step and the aggregated-status step); reserve Version / Prerelease for a future PSScriptAnalyzer-version input (separate follow-up)

Actions — add the inputs (additive)

• Debug — add GitHubVersion / GitHubPrerelease and forward to GitHub-Script
• Get-IssueFormData — add GitHubVersion / GitHubPrerelease and forward to GitHub-Script

Already in progress

• Invoke-Pester — verify 🌟 [Major]: Version inputs now configure Pester Invoke-Pester#71 lands GitHubVersion / GitHubPrerelease consistent with this convention

Related surface (reusable workflow)

• Process-PSModule workflow.yml: rename its Version / Prerelease inputs (which today control the GitHub module) to GitHubVersion / GitHubPrerelease for consistency — breaking for module repositories that pass Version:, so coordinate the bump accordingly

Documentation

• Document the GitHubVersion / GitHubPrerelease convention (and the Version = primary-tool rule) so it is discoverable for action authors and consumers