Release automation runs on Process-PSModule v8 with a Zensical documentation site and a Pester 6 test suite

[Marius Storhaug (MariusStorhaug)]

Release automation for this module runs on the Process-PSModule v8 contract, so builds, tests, documentation publishing, and PowerShell Gallery releases follow the current pipeline and track the v8 major without a pin update for every patch release. The documentation site builds with Zensical from a configuration the pipeline reads, the test suite is written in the type-aware Pester 6 assertion syntax, and changes to the automation itself run through the same build, test, and publish path as changes to the module.

A contributor running the test suite needs Pester 6.1.0 or later within the 6 major, and anyone adjusting the documentation site edits its Zensical configuration rather than a MkDocs one.

Breaking: Pester 6.1 test framework floor

The test suite resolves its framework from the Pester module available on the machine that runs it, and the reusable test runner installs from the [6.1.0,7.0.0) range.

Test files require Pester 6.1.0 or later within the 6 major, so patch and minor releases resolve automatically while a new major stays a deliberate change.

#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.1.0'; MaximumVersion = '6.*' }

Field	Value	Effect
ModuleName	Pester	Names the framework the suite resolves.
ModuleVersion	6.1.0	Sets the lowest version that satisfies the suite.
MaximumVersion	6.*	Accepts any 6.x release and excludes the next major.

Changed: Zensical documentation site configuration

The pipeline builds the documentation site with Zensical and reads its configuration from .github/zensical.toml, docs/zensical.toml, or zensical.toml.

Site configuration lives in .github/zensical.toml, carrying the site identity, theme variant, colour palette, navigation and search behaviour, Markdown extensions, social links, and cookie-consent notice. The pipeline substitutes the repository owner and module name into the placeholder values and sets the output directory when it builds.

[project]
site_name = "-{{ REPO_NAME }}-"
repo_name = "-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"
repo_url = "https://github.com/-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-"

[project.theme]
variant = "classic"
language = "en"
logo = "Assets/icon.png"
favicon = "Assets/icon.png"

Key	Values	Effect	Default
site_name	Any string	Titles the published site.	-{{ REPO_NAME }}-, replaced with the module name
repo_url	Repository URL	Links the site header to the repository.	Built from the owner and module name
theme.variant	classic	Selects the Zensical theme variant.	classic
theme.features	Navigation and search feature flags	Enables instant navigation, section indexes, search suggestions and highlighting, and code copy buttons.	Nine flags enabled
theme.palette	Palette entries keyed by colour scheme	Offers automatic, dark, and light colour schemes with a toggle.	Follows the reader's system preference

Read more in the Process-PSModule repository setup guide.

Changed: Release automation on the Process-PSModule v8 contract

Publishing a module release writes to the PowerShell Gallery, GitHub Releases, and repository tags, so the automation needs credentials for each and no more permission than those operations require.

The caller workflow tracks the v8 major tag and supplies gallery and GitHub App credentials through the v8 secret contract, so a GitHub App installation token performs repository writes and the workflow token holds only read access to repository contents alongside the Pages and OIDC permissions the documentation site needs.

jobs:
  Process-PSModule:
    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
    secrets:
      PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
      GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
      GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}

Secret	Purpose	Source
PSGALLERY_API_KEY	Authenticates publishing to the PowerShell Gallery.	PSModule organisation secret
GitHubAppClientId	Identifies the GitHub App that performs repository writes.	SHELLY_CLIENT_ID organisation secret
GitHubAppPrivateKey	Signs the GitHub App installation token.	SHELLY_PRIVATE_KEY organisation secret
TestData	Carries caller-defined test secrets and variables.	Omitted — the suite needs none

Read more in the Process-PSModule guide to calling the workflow.

Changed: Stable releases publish from a default-branch push

A release-capable run mutates the PowerShell Gallery, GitHub Releases, and tags, so an interrupted run leaves those targets inconsistent.

A push to main produces the stable release, pull request events drive continuous integration, prereleases, and prerelease cleanup, and concurrency keys on the pull request number where one exists and the ref otherwise, so a pull request stays distinct from a default-branch push and a queued run waits for a release in flight instead of cancelling it.

Changed: Automation and test changes enter the release path

The build, test, and publish stages run only for a change that matches the repository's important-file patterns, and the shipped defaults match module source and the README alone.

Changes to the test suite, the workflow caller, the site configuration, and the settings file enter the build, test, and publish path alongside changes to module source, so a change to the automation is exercised by the pipeline it governs.

ImportantFilePatterns:
  - '^src/'
  - '^README\.md$'
  - '^tests/'
  - '^\.github/PSModule\.yml$'
  - '^\.github/zensical\.toml$'
  - '^\.github/workflows/'

Pattern	Matches
^src/	Module source compiled into the shipped artifact.
^README\.md$	The module landing page published with the documentation site.
^tests/	The Pester suite and its test data.
^\.github/PSModule\.yml$	Pipeline settings for this repository.
^\.github/zensical\.toml$	Documentation site configuration.
^\.github/workflows/	The workflow caller and any other repository workflow.

Changed: Type-aware assertions in the test suite

Pester 6 assertions are specialised by the type and shape of the value under test, and report a failure against the value they actually received.

The suite asserts through the Should-* family, so a failure names the offending value and the pipeline shaping behind it, and the suite passes with the classic assertion syntax disabled.

Technical details

.github/workflows/Process-PSModule.yml carries the caller body from the Process-PSModule v8 documentation, referencing workflow.yml@v8. The mutable major tag is deliberate for this caller, so the SHA-pinning convention that applies to third-party actions elsewhere in the repository does not apply here. Workflow permissions are contents: read, pages: write, and id-token: write; pull_request types include unlabeled alongside closed, opened, reopened, synchronize, and labeled. All three secrets the reusable workflow declares as required are mapped, and it declares no other required secret or input.

Template-PSModule currently ships a caller with job-level permissions and cancel-in-progress keyed on the event name, which differs from the form above. The published documentation on the default branch matches this caller, and v8.0.3 is the current release, so the documentation is followed as the source of truth.

.github/zensical.toml is byte-identical to the v8.0.3 template, which is the upstream default for a module repository and already matches every setting the previous MkDocs definition carried. Verified field by field: site identity, language, logo, favicon, all three palette entries including scheme, primary, accent, and toggle labels, both social links, and the consent title, description, and actions all match. Two deltas come from the template: the theme font selection is absent, since the Zensical classic variant sets its own typography, and content.code.copy is added to the feature list. Theme selection moves from theme.name = material to theme.variant = "classic", the repository icon to fontawesome/brands/github, and the palette toggle icons to the lucide set. site_dir is intentionally absent because the pipeline injects it after the [project] header, which requires that header to stay on its own line. The MkDocs configuration is removed; no v8 action or workflow reads it, and no reference to it remains in the repository.

.github/PSModule.yml sets ImportantFilePatterns, which replaces the defaults in full rather than extending them, so ^src/ and ^README\.md$ are repeated alongside the added paths. Verified that every file this change touches matches a pattern. VALIDATE_GITHUB_ACTIONS_ZIZMOR is disabled to match the current module template. The reference comment moves to the settings page because the README anchor it named no longer exists in v8. Every other setting in the file, including Test.CodeCoverage.PercentTarget, remains valid against the v8 settings contract.

tests/GoogleFonts.Tests.ps1 asserts with Should-NotBeNull in place of Should -Not -BeNullOrEmpty. Piping unwraps input, so an empty collection reaches the assertion as $null and fails it; this holds for @(), @(1), and multi-item input. Pester 6 offers no Should-NotThrow counterpart to Should-Throw, so the install assertion calls the command directly and an exception fails the test, surfacing the real exception rather than a wrapper message. The disabled bulk-install test carries the same syntax so it stays valid when enabled. Both public commands have tests, satisfying the FunctionTest framework check.

Validation: all three tests pass against Pester 6.1.0 with the module built and imported locally, run with Should.DisableV5 = $true so any classic assertion throws. That guard rejects a probe file asserting 1 | Should -Be 1, confirming it is not vacuous. Invoke-ScriptAnalyzer reports clean against .github/linters/.powershell-psscriptanalyzer.psd1. The Zensical configuration parses as TOML and the settings file as YAML.

.github/workflows/Update-FontsData.yml is unaffected and untouched. It runs PSModule/GitHub-Script with the repository's own GOOGLEFONTS_UPDATER_BOT_CLIENT_ID, GOOGLEFONTS_UPDATER_BOT_PRIVATE_KEY, and GOOGLE_DEVELOPER_API_KEY secrets and takes no part in the Process-PSModule caller contract.

Out of scope: module source, .github/dependabot.yml, Dependabot secret configuration, the Install-GoogleFont -Force defect, and the pinned Fonts and Admin dependency versions. The repository standard also expects CONTRIBUTING.md, SECURITY.md, SUPPORT.md, CODE_OF_CONDUCT.md, AGENTS.md, CLAUDE.md, .github/release.yml, and .github/pull_request_template.md, none of which this repository carries; no framework test enforces them, so they are left for separate changes.

Related references

• Supersedes Bump PSModule/Process-PSModule/.github/workflows/workflow.yml from 6.1.4 to 8.0.3 #295
• Supersedes 🩹 [Patch]: Pester 6 test dependency packages correctly #276
• Relates to ⚙️ [Maintenance]: Module automation runs on Process-PSModule v6.1.19 #270

[psmodule-s-shelly]

No Significant Changes Detected

This PR does not contain changes to files that would trigger a new release:

Pattern	Description
^src/	Matches files where path matches this pattern
^README\.md$	Matches files where path matches this pattern

Build, test, and publish stages will be skipped for this PR.

If you believe this is incorrect, please verify that your changes are in the correct locations.

[psmodule-s-shelly]

No Significant Changes Detected

This PR does not contain changes to files that would trigger a new release:

Pattern	Description
^src/	Matches files where path matches this pattern
^README\.md$	Matches files where path matches this pattern

Build, test, and publish stages will be skipped for this PR.

If you believe this is incorrect, please verify that your changes are in the correct locations.

[psmodule-s-shelly]

No Significant Changes Detected

This PR does not contain changes to files that would trigger a new release:

Pattern	Description
^src/	Matches files where path matches this pattern
^README\.md$	Matches files where path matches this pattern

Build, test, and publish stages will be skipped for this PR.

If you believe this is incorrect, please verify that your changes are in the correct locations.

[psmodule-s-shelly]

No Significant Changes Detected

This PR does not contain changes to files that would trigger a new release:

Pattern	Description
^src/	Matches files where path matches this pattern
^README\.md$	Matches files where path matches this pattern

Build, test, and publish stages will be skipped for this PR.

If you believe this is incorrect, please verify that your changes are in the correct locations.

[psmodule-s-shelly]

No Significant Changes Detected

This PR does not contain changes to files that would trigger a new release:

Pattern	Description
^src/	Matches files where path matches this pattern
^README\.md$	Matches files where path matches this pattern

Build, test, and publish stages will be skipped for this PR.

If you believe this is incorrect, please verify that your changes are in the correct locations.