Guarded publish to PowerShell Gallery after GitHub Release

[blindzero]

Goal

Enable official distribution via PowerShell Gallery with a safe/guarded publish process.

Publishing to PSGallery lowers user friction (Install-Module IdLE) but must be protected because publishing is hard to undo and requires API key handling. Publish-Module / Publish-PSResource publish to NuGet-based galleries using an API key.

Scope

Trigger & flow

• Publish occurs after a GitHub Release is created (i.e., after Release automation: tag - build ZIP artifact - GitHub Release notes #13 packaging works).
• Trigger options (pick one; default below):
  • Default: workflow_dispatch (“Publish to PSGallery”) referencing a tag/release
  • Alternative: release: published event (still guarded via environment approval)

Guardrails (must-have)

• Use a GitHub Environment (e.g., psgallery-prod) with:
  • Required reviewers enabled (manual approval gate)
  • Secrets stored only in that environment (API key not available without approval)
  • Optional: prevent self-review (if desired) GitHub Docs
• Validate before publish:
  • Tag version vX.Y.Z matches module manifest ModuleVersion (same rule as Release automation: tag - build ZIP artifact - GitHub Release notes #13)
  • Only publish stable versions by default (no prerelease suffix unless explicitly enabled)

Packaging/source to publish

• Publish the module from the curated dist content produced by Release automation: tag - build ZIP artifact - GitHub Release notes #13 (so we don’t accidentally publish /tests, /.github, etc.).
• Include only module content required by PSGallery (module folder structure + manifest).
• Keep docs as non-module assets in GitHub Release ZIP, but do not publish docs as part of the module unless explicitly decided.

Publishing command/tooling

• Default: use Publish-Module (PowerShellGet v2) to publish the module folder to PSGallery using API key.
  Microsoft Learn
• Optional future enhancement: evaluate Publish-PSResource (PSResourceGet) if desired; note that it is intended as a successor combining Publish-Module/Publish-Script behaviors.

Version strategy

• Default: publish only stable vX.Y.Z.
• Optional: allow prerelease publishing (vX.Y.Z-preview.N) using PowerShellGet prerelease support.

Non-goals

• Code signing
• Multi-OS build matrix
• Automatic tag creation/version bumping
• Publishing to additional repositories beyond PSGallery

Acceptance Criteria

• A guarded GitHub Actions workflow exists to publish IdLE to PSGallery.
• Workflow requires manual approval via GitHub Environment required reviewers.
• PSGallery API key is stored as an environment secret and is not accessible without approval.
• Workflow validates tag version matches module manifest version; mismatch fails.
• Publish uses the curated dist/module content (no /tests, no /.github, no dev-only folders).
• Publishing succeeds for a stable tag and results in an installable module via PowerShellGet.
• (Optional) prerelease publishing is supported and documented if enabled.
  Microsoft Learn

[blindzero]

Missing pre-release behavior