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.
Process-PSModule follows:
- Test-Driven Development using Pester and PSScriptAnalyzer
- GitHub Flow specifications
- SemVer 2.0.0 specifications
- Continiuous Delivery practices
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@v1
secrets: inherit
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', 'Desktop', 'Core'. | false | None |
TestProcess |
boolean |
Whether to test the process. | false | false |
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 |
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
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.
The action is compatible with the following configurations:
OS | Shell |
---|---|
windows-latest | pwsh |
windows-latest | powershell |
macos-latest | pwsh |
ubuntu-latest | pwsh |