Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
# Every job calls Tests/test-local.ps1 for one stage, so `./Tests/test-local.ps1` locally runs the same checks.
# The build job (Sampler/ModuleBuilder) produces output/<ModuleName>/<version>/; the Pester jobs test that built
# module under both Windows PowerShell 5.1 and PowerShell 7, because the module must work on both.
# Publishing to the PowerShell Gallery is manual for now (see AGENTS.md). No module name is hard-coded here.
# Publishing to the PowerShell Gallery is done by release.yml (see AGENTS.md). No module name is hard-coded here.
#
# Security note: never interpolate ${{ github.* }} / ${{ matrix.* }} values directly into a
# run: script. Pass them through env: instead.
Expand Down
171 changes: 171 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
# Release: publishes the module to the PowerShell Gallery and creates the GitHub Release.
#
# Real release: push a tag v<ModuleVersion> (for example v0.5.0) that points at a commit on master.
# Dry run: "Run workflow" (workflow_dispatch) on any branch. It checks, builds, tests and packages, and then
# stops: nothing is published and no release is created.
#
# What a release does, in order:
# 1. check tag = ModuleVersion in the manifest, CHANGELOG.md has a dated section for the version, the version
# is not on the Gallery yet, and the tagged commit is on master (Build/Get-ReleaseInfo.ps1)
# 2. build build and run every stage of Tests/test-local.ps1 (the same checks as CI, both PowerShell editions)
# 3. package pack the build into a .nupkg, push it to a temporary folder repository and import the saved
# package on both editions (Build/Test-ReleasePackage.ps1)
# 4. publish Publish-PSResource -NupkgPath of that exact .nupkg, after checking its SHA256. Runs in the
# "psgallery" environment, which holds the PSGALLERY_API_KEY secret and should require the owner's
# approval.
# 5. release GitHub Release for the tag, with the CHANGELOG section as its notes
#
# A Gallery version can never be replaced, so everything that can fail is checked before step 4.
# No module name is hard-coded here.
#
# Security note: never interpolate ${{ github.* }} values directly into a run: script. Use env: or the
# default GITHUB_* environment variables instead.

name: Release

on:
push:
tags:
- 'v*'
workflow_dispatch:

permissions:
contents: read

# Dry runs and tag runs queue separately: a group keeps only one waiting run, so a dry run in the same group
# could cancel a waiting release.
concurrency:
group: release-${{ github.event_name }}
cancel-in-progress: false

jobs:
build:
name: Check, build and test
runs-on: windows-latest
defaults:
run:
shell: pwsh

steps:
- name: Checkout Repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
fetch-depth: 0

- name: Check the release
run: |
$Params = @{ NotesPath = 'release-notes.md' }
if ($env:GITHUB_EVENT_NAME -eq 'push') {
$Params.Tag = $env:GITHUB_REF_NAME
git merge-base --is-ancestor HEAD origin/master
if ($LASTEXITCODE -ne 0) { throw "Tag $env:GITHUB_REF_NAME does not point at a commit on master." }
} else {
$Params.AllowUnreleased = $true
}
$Info = ./Build/Get-ReleaseInfo.ps1 @Params
$Info | Select-Object ModuleName, Version, Tag, DryRun, NotesSource | Format-List

- name: Build and test
run: ./Tests/test-local.ps1

- name: Package and check the package
run: |
$Release = Join-Path 'output' 'release'
$Package = ./Build/Test-ReleasePackage.ps1 -PackagePath $Release
Move-Item -Path 'release-notes.md' -Destination $Release
$Package | Select-Object ModuleName, Version, Functions, PackageName, PackageSha256 |
ConvertTo-Json | Set-Content -Path (Join-Path $Release 'release.json')

$Mode = if ($env:GITHUB_EVENT_NAME -eq 'push') { 'Release' } else { 'Dry run (nothing is published)' }
@(
"## $($Package.ModuleName) $($Package.Version)"
''
"- Mode: $Mode"
"- Commit: $env:GITHUB_SHA"
"- Functions: $($Package.Functions)"
"- Package: $($Package.PackageName), SHA256 $($Package.PackageSha256)"
''
'### Release notes'
''
(Get-Content -Path (Join-Path $Release 'release-notes.md') -Raw)
) | Add-Content -Path $env:GITHUB_STEP_SUMMARY

- name: Upload Release Artifact
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: release
path: output/release/
if-no-files-found: error
retention-days: 30

publish:
name: Publish to the PowerShell Gallery
if: github.event_name == 'push'
needs: build
runs-on: windows-latest
environment:
name: psgallery
url: https://www.powershellgallery.com/packages/${{ github.event.repository.name }}
defaults:
run:
shell: pwsh

steps:
# No checkout: this job only handles the files the build job tested.
- name: Download Release Artifact
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: release
path: release

- name: Publish
env:
PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
run: |
if (-not $env:PSGALLERY_API_KEY) { throw 'The PSGALLERY_API_KEY secret is not set in the psgallery environment.' }
$Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json
if ("v$($Release.Version)" -ne $env:GITHUB_REF_NAME) {
throw "The built version $($Release.Version) does not match tag $env:GITHUB_REF_NAME."
}
# Publish the .nupkg the build job checked, and only if it is byte-for-byte that file
$Package = Join-Path 'release' $Release.PackageName
$Hash = (Get-FileHash -Path $Package -Algorithm SHA256).Hash
if ($Hash -ne $Release.PackageSha256) {
throw "The package hash $Hash does not match the checked package $($Release.PackageSha256)."
}
Publish-PSResource -NupkgPath $Package -Repository PSGallery -ApiKey $env:PSGALLERY_API_KEY
Write-Host "Published $($Release.ModuleName) $($Release.Version) ($($Release.PackageName), SHA256 $Hash)"

- name: Wait until the Gallery lists the version
run: |
$Release = Get-Content -Path 'release/release.json' -Raw | ConvertFrom-Json
foreach ($Attempt in 1..20) {
$Found = Find-PSResource -Name $Release.ModuleName -Version $Release.Version -Repository PSGallery `
-ErrorAction SilentlyContinue
if ($Found) { Write-Host "The Gallery lists $($Found.Name) $($Found.Version)"; exit 0 }
Start-Sleep -Seconds 30
}
# The publish itself succeeded; the Gallery can take longer to validate and index a package.
Write-Warning 'The Gallery does not list the version yet. Check the package page before announcing it.'

github-release:
name: Create the GitHub Release
if: github.event_name == 'push'
needs: publish
runs-on: ubuntu-latest
permissions:
contents: write

steps:
- name: Download Release Artifact
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: release
path: release

- name: Create Release
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file release/release-notes.md
31 changes: 25 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,28 @@ Tooling: PowerShell 7 for the build; Pester 5.7.1+, PSScriptAnalyzer, platyPS 0.
| PSScriptAnalyzer | Zero analyzer errors in `source/` |
| Docs drift | `Build/Update-Help.ps1` leaves no diff |

`.github/workflows/pr-validation.yml` warns when a PR doesn't update `CHANGELOG.md`. Publishing to the PowerShell
Gallery is manual and needs the owner's explicit go: build, then
`Publish-Module -Path output/<ModuleName>/<version> -NuGetApiKey <key>` (publish the built folder, not `source/`).
`.github/workflows/pr-validation.yml` warns when a PR doesn't update `CHANGELOG.md`.

### Releasing

`.github/workflows/release.yml` publishes to the PowerShell Gallery. A Gallery version can never be replaced, and
every step below needs the owner's explicit go.

1. Release PR: set `ModuleVersion` in `source/<ModuleName>.psd1` (three parts), rename the CHANGELOG's
`## [Unreleased]` notes to `## [<version>] - <yyyy-MM-dd>` (leave an empty `[Unreleased]` above it) and update
the compare links at the bottom. Merge it.
2. Dry run: run the **Release** workflow by hand (`gh workflow run release.yml`). It checks, builds, tests and
packages, and publishes nothing. Locally: `./Build/Get-ReleaseInfo.ps1`, then `./Tests/test-local.ps1`, then
`./Build/Test-ReleasePackage.ps1`.
3. Tag the merged commit on `master` as `v<version>` and push the tag. The workflow fails before building unless
the tag equals `ModuleVersion`, the CHANGELOG has the dated section, the version is not on the Gallery and the
commit is on `master`.
4. The `publish` job waits for the owner's approval in the `psgallery` environment, which holds the
`PSGALLERY_API_KEY` secret. Agents never see or handle that key. The job publishes the `.nupkg` the package
check tested, after comparing its SHA256. After the publish, the workflow creates the GitHub Release from the
CHANGELOG section.

If the publish succeeded and a later job failed, re-run only the failed job; never re-run the publish.

## Architecture

Expand Down Expand Up @@ -142,8 +161,8 @@ Enforced by `.PSScriptAnalyzerSettings.psd1` and `.editorconfig`:
| --- | --- | --- |
| PowerShell 7.6, Core only | PowerShell 3.0+, runs on 5.1 and 7 | MSPs run it from RMM agents on Windows PowerShell 5.1 |
| Sampler `test` task, Pester 6 | `Tests/test-local.ps1`, Pester 5.7 | Must run the suite under Windows PowerShell 5.1 |
| `Tests/Unit/{Module,Public,Private}`, one file per function | Four suite files under `Tests/` | Not split yet |
| `Tests/Unit/{Module,Public,Private}`, one file per function | Four module suite files (plus `Release.Tests.ps1`) under `Tests/` | Not split yet |
| `docs/` (help, examples, media) | `Docs/` (platyPS), `Examples/`, `Media/` at the root | `docs/` = `Docs/` on Windows |
| Changelog release task | Release notes by hand | The task cannot parse this CHANGELOG's 4-part versions |
| Changelog release task | `Build/Get-ReleaseInfo.ps1` reads the notes | The task cannot parse this CHANGELOG's 4-part versions |
| PlatyPS 1.x → `docs/help` | platyPS 0.14 via `Build/Update-Help.ps1` (+ MAML) | `Get-Help` on 5.1 uses the MAML |
| Tag-driven publish workflow | Manual `Publish-Module` | Owner publishes by hand |
| Sampler `publish` task | `release.yml` with `Publish-PSResource` | Publishes the exact `.nupkg` the package check installed and imported |
155 changes: 155 additions & 0 deletions Build/Get-ReleaseInfo.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
<#
.SYNOPSIS
Checks that the repository is ready to release a version and returns the version and its release notes.

.DESCRIPTION
Used by .github/workflows/release.yml before anything is built. It fails (throws) unless:
- the tag is v<major>.<minor>.<patch> and equals the ModuleVersion in the source manifest
- CHANGELOG.md has a dated section for that version: ## [0.5.0] - 2026-01-31
- the section has text
- that version is not already on the PowerShell Gallery (a published version can never be replaced)

Without -Tag it is a dry run for the version in the manifest. A dry run only warns when the version is
already on the Gallery, and with -AllowUnreleased it takes the notes from the [Unreleased] section when the
version has no section yet.

The Gallery check fails when the Gallery cannot be reached: no answer is not treated as "not published".

.PARAMETER Tag
The git tag being released, for example v0.5.0. Leave empty for a dry run.

.PARAMETER AllowUnreleased
Dry run only: use the [Unreleased] section when CHANGELOG.md has no section for the version.

.PARAMETER SkipGalleryCheck
Do not ask the PowerShell Gallery whether the version already exists.

.PARAMETER NotesPath
Write the release notes (the CHANGELOG section without its heading) to this file.

.PARAMETER ManifestPath
The source manifest. Defaults to the only .psd1 in source/.

.PARAMETER ChangelogPath
Defaults to CHANGELOG.md in the repository root.

.EXAMPLE
./Build/Get-ReleaseInfo.ps1 -Tag v0.5.0 -NotesPath output/release-notes.md

.EXAMPLE
./Build/Get-ReleaseInfo.ps1 -AllowUnreleased -SkipGalleryCheck
#>
[CmdletBinding()]
param(
[string]$Tag,

[switch]$AllowUnreleased,

[switch]$SkipGalleryCheck,

[string]$NotesPath,

[string]$ManifestPath,

[string]$ChangelogPath
)

$ErrorActionPreference = 'Stop'
$RepoRoot = Split-Path -Parent $PSScriptRoot

if (-not $ManifestPath) {
$Found = @(Get-ChildItem -Path (Join-Path $RepoRoot 'source') -Filter '*.psd1' -File)
if ($Found.Count -ne 1) { throw "Expected one module manifest in source/, found $($Found.Count)." }
$ManifestPath = $Found[0].FullName
}
if (-not $ChangelogPath) { $ChangelogPath = Join-Path $RepoRoot 'CHANGELOG.md' }

$ModuleName = [IO.Path]::GetFileNameWithoutExtension($ManifestPath)
$Version = [string](Import-PowerShellDataFile -Path $ManifestPath).ModuleVersion
if ($Version -notmatch '^\d+\.\d+\.\d+$') {
throw "ModuleVersion '$Version' in the manifest must have three parts (major.minor.patch)."
}

if ($Tag) {
if ($AllowUnreleased) { throw '-AllowUnreleased is for dry runs only; do not combine it with -Tag.' }
if ($Tag -notmatch '^v\d+\.\d+\.\d+$') { throw "Tag '$Tag' must look like v1.2.3." }
if ($Tag -ne "v$Version") {
throw "Tag '$Tag' does not match ModuleVersion '$Version' in the manifest. Fix the manifest or the tag."
}
}

# Split the changelog into sections by their '## [name]' headings
$Lines = @(Get-Content -Path $ChangelogPath)
$Sections = [ordered]@{}
$Current = $null
foreach ($Line in $Lines) {
if ($Line -match '^## \[(?<Name>[^\]]+)\](?<Rest>.*)$') {
$Current = $Matches.Name
$Sections[$Current] = @{
Heading = $Line
Rest = $Matches.Rest
Body = New-Object System.Collections.Generic.List[string]
}
} elseif ($Line -match '^\[[^\]]+\]:\s') {
$Current = $null # link definitions at the end of the file
} elseif ($Current) {
$Sections[$Current].Body.Add($Line)
}
}

$NotesSource = $Version
if ($Sections.Contains($Version)) {
if ($Sections[$Version].Rest -notmatch '^ - \d{4}-\d{2}-\d{2}\s*$') {
throw "CHANGELOG heading '$($Sections[$Version].Heading)' needs a date: ## [$Version] - yyyy-MM-dd"
}
} elseif (-not $Tag -and $AllowUnreleased -and $Sections.Contains('Unreleased')) {
$NotesSource = 'Unreleased'
} else {
throw "CHANGELOG.md has no '## [$Version] - yyyy-MM-dd' section. Move the [Unreleased] notes under it first."
}

$Notes = ($Sections[$NotesSource].Body -join "`n").Trim()
if (-not $Notes) { throw "CHANGELOG section [$NotesSource] is empty." }

$AlreadyPublished = $null
if (-not $SkipGalleryCheck) {
# Ask the Gallery for this exact package version: 200 = it exists (unlisted versions too), 404 = it does not.
# Any other answer, or none, fails the check instead of counting as "not published".
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072
$Uri = "https://www.powershellgallery.com/api/v2/Packages(Id='$ModuleName',Version='$Version')"
try {
Invoke-WebRequest -Uri $Uri -UseBasicParsing | Out-Null
$AlreadyPublished = $true
} catch {
$Status = 0
if ($_.Exception.Response) { $Status = [int]$_.Exception.Response.StatusCode }
if ($Status -ne 404) {
throw ("Could not check the PowerShell Gallery for $ModuleName $Version (HTTP $Status): " +
$_.Exception.Message)
}
$AlreadyPublished = $false
}
if ($AlreadyPublished) {
$Message = "$ModuleName $Version is already on the PowerShell Gallery. A version cannot be replaced; " +
'raise ModuleVersion for the next release.'
if ($Tag) { throw $Message }
Write-Warning $Message
}
}

if ($NotesPath) {
$NotesFolder = Split-Path -Parent $NotesPath
if ($NotesFolder -and -not (Test-Path $NotesFolder)) { New-Item -ItemType Directory -Path $NotesFolder | Out-Null }
[IO.File]::WriteAllText($ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($NotesPath),
$Notes + "`n", (New-Object System.Text.UTF8Encoding($false)))
}

[pscustomobject]@{
ModuleName = $ModuleName
Version = $Version
Tag = "v$Version"
DryRun = -not $Tag
NotesSource = $NotesSource
AlreadyPublished = $AlreadyPublished
Notes = $Notes
}
Loading
Loading