Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/PSModule/Process-PSModule
Process a module from source code to published module.
https://github.com/PSModule/Process-PSModule
powershell powershell-module workflow
Last synced: 6 days ago
JSON representation
Process a module from source code to published module.
- Host: GitHub
- URL: https://github.com/PSModule/Process-PSModule
- Owner: PSModule
- License: mit
- Created: 2023-10-17T19:35:39.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-04T21:15:56.000Z (8 days ago)
- Last Synced: 2024-11-04T22:19:52.768Z (8 days ago)
- Topics: powershell, powershell-module, workflow
- Language: PowerShell
- Homepage: https://psmodule.io
- Size: 235 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# 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](https://testdriven.io/test-driven-development/) using [Pester](https://pester.dev) and [PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules)
- [GitHub Flow specifications](https://docs.github.com/en/get-started/using-github/github-flow)
- [SemVer 2.0.0 specifications](https://semver.org)
- [Continiuous Delivery practices](https://en.wikipedia.org/wiki/Continuous_delivery)
## 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](https://github.com/PSModule/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](https://github.com/PSModule/Build-PSModule/) - Compiles the repository into an efficient PowerShell module.
- [Test-PSModule](https://github.com/PSModule/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](https://github.com/PSModule/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
```yaml
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:
```yaml
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:
```yaml
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](https://github.com/marketplace/actions/deploy-github-pages-site).
## Compatibility
The action is compatible with the following configurations:
| OS | Shell |
| --- | --- |
| windows-latest | pwsh |
| macos-latest | pwsh |
| ubuntu-latest | pwsh |