Process-PSModule

A workflow for the PSModule process, stitching together the Initialize, Build, Test, and Publish actions to create a complete CI/CD pipeline for PowerShell modules. The workflow is used by all PowerShell modules in the PSModule organization.

Specifications and practices

Process-PSModule follows:

• Test-Driven Development using Pester and PSScriptAnalyzer
• GitHub Flow specifications
• SemVer 2.0.0 specifications
• Continiuous Delivery practices

How it works

The workflow is designed to be trigger on pull requests to the repository's default branch. When a pull request is opened, closed, reopened, synchronized (push), or labeled, the workflow will run. Depending on the labels in the pull requests, the workflow will result in different outcomes.

• Test-PSModule - Tests the source code using PSScriptAnalyzer, PSModule source code tests suites. This runs on 4 different environments to check compatibility.
  • PowerShell 7.x on Windows, Ubuntu and macOS.
  • Windows PowerShell 5.1 on Windows.
• Build-PSModule - Compiles the repository into an efficient PowerShell module.
• Test-PSModule - Tests the compiled module using PSScriptAnalyzer, PSModule module tests and custom module tests from the module repository. This runs on 4 different environments to check compatibility.
  • PowerShell 7.x on Windows, Ubuntu and macOS.
  • Windows PowerShell 5.1 on Windows.
• Publish-PSModule - Publishes the module to the PowerShell Gallery, docs to GitHub Pages, and creates a release on the GitHub repository.

To use the workflow, create a new file in the .github/workflows directory of the module repository and add the following content.

Workflow suggestion

name: Process-PSModule

on:
  pull_request:
    branches:
      - main
    types:
      - closed
      - opened
      - reopened
      - synchronize
      - labeled

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: write
  pull-requests: write

jobs:
  Process-PSModule:
    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v2
    secrets: inherit

Usage

Inputs

Name	Type	Description	Required	Default
Name	string	The name of the module to process. This defaults to the repository name if nothing is specified.	false	N/A
Path	string	The path to the source code of the module.	false	src
ModulesOutputPath	string	The path to the output directory for the modules.	false	outputs/modules
DocsOutputPath	string	The path to the output directory for the documentation.	false	outputs/docs
PublishDocs	boolean	Whether to publish the documentation using MkDocs and GitHub Pages.	false	true
SiteOutputPath	string	The path to the output directory for the site.	false	outputs/site
SkipTests	string	Defines what types of tests to skip. Allowed values are 'All', 'SourceCode', 'Module', 'None', 'macOS', 'Windows', 'Linux'.	false	None
TestProcess	boolean	Whether to test the process.	false	false
Version	string	The version of the 'GitHub' module to use. Defaults to latest version.	false	N/A
Prerelease	boolean	Whether to use a prerelease version of the 'GitHub' module.	false	false

Secrets

The following secrets are required for the workflow to run:

Name	Location	Description	Default
GITHUB_TOKEN	github context	The token used to authenticate with GitHub.	${{ secrets.GITHUB_TOKEN }}
APIKey	GitHub secrets	The API key for the PowerShell Gallery.	N/A

Permissions

The action requires the following permissions:

If running the action in a restrictive mode, the following permissions needs to be granted to the action:

permissions:
  contents: write      # Create releases
  pull-requests: write # Create comments on the PRs
  statuses: write      # Update the status of the PRs from the linter

Publishing to GitHub Pages

To publish the documentation to GitHub Pages, the action requires the following permissions:

permissions:
  pages: write    # Deploy to Pages
  id-token: write # Verify the deployment originates from an appropriate source

For more info see Deploy GitHub Pages site.

Compatibility

The action is compatible with the following configurations:

OS	Shell
windows-latest	pwsh
macos-latest	pwsh
ubuntu-latest	pwsh