PSModule

A GitHub & PowerShell development framework

We empower PowerShell-savvy developers to effortlessly transform their ideas into impactful solutions. Our approach centers around a development framework that allows developers to focus on delivering value through their code. By leveraging the GitHub platform and PowerShell, we aim to automate the repetitive tasks, enabling developers — whether as consumers or contributors — to concentrate on coding without distractions.

Supported Platforms

This development framework is built to serve the needs of modern developers and environments. We prioritize supporting the latest Long-Term Servicing (LTS) version of PowerShell to ensure that we can leverage the most recent features and capabilities, keeping our framework aligned with the demands of today’s development landscape. We assume most of the users of this framework work on modern platforms and have access to the latest versions of PowerShell or seek to use it to develop solutions intended to run on modern systems, like GitHub Actions, Azure Functions on a developer machine.

The Trade-Off: Not Supporting Windows PowerShell

We’ve made a deliberate choice not to actively persure to support the older Windows PowerShell (5.1) version, as it limits our ability to use the newest PowerShell features. Where its low effort to support Windows PowerShell, we will do so, but we will not actively develop modules for it. While we recognize that some users may still rely on Windows PowerShell 5.1, they can run tools developed in this framework by installing PowerShell 7 alongside it or on remote systems. This decision ensures that this framework can focus on delivering new features for modern development without being constrained by legacy technology, which would otherwize require significant effort to develop and maintain, even if it is available in the newer versions of PowerShell.

Products and projects we focus on

Our framework is dedicated to advancing the tools and processes that empower modern development and operations teams, with a specific focus on GitHub as our primary toolstack. We concentrate on the following key areas:

PowerShell modules
GitHub Actions and Workflows
Serverless applications using Function Apps in Azure

PowerShell modules

About

A PowerShell module is a set of functions, scripts, and cmdlets that are bundled together in a single package. Modules are used to organize and distribute code in a way that is easy to use and share. They can be used to extend the functionality of PowerShell, automate tasks, and create reusable code that can be shared with others. We have created a framework that automates the process of creating, testing, and publishing PowerShell modules to the PowerShell Gallery. This framework is designed to make it easy for developers to create and share their PowerShell modules with the community.

How we do it in PSModule

Projects based on the Template-PSModule repository template will automatically have the necessary workflows and configurations set up to automate the process of creating, testing, and publishing PowerShell modules to the PowerShell Gallery. This includes workflows for building, testing, and releasing the module, as well as a configuration file for setting up the module's metadata and dependencies. Using custom properties we set RepoType to Module. We use branch policies to control the flow of changes to the main branch, and we use labels to control the versioning of the module when a pull request is merged.

Create a new project

Create a repository based on the template Template-PSModule. The module will by default use the name of the repository. See Process-PSModule for more info on choosing another name than the repository name.
Create a repository or organization secret called APIKEY holding the API key for the PowerShell Gallery.
Configure the settings you want for the repository including a branch policy for the main branch.
On a topic branch:
1. develop the code you want to add to your module.
2. delete the parts you do not need.
3. update the tests in the tests folder.
Create a PR. Add a label to the PR depending on what you want to do.
- Major - Will create a major release (vX.0.0) when merged. If specified with "Prerelease", a major version will be created using the prerelease tag (vX.0.0-<branchName>).
- Minor - Will create a minor release (vX.Y.0) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.0-<branchName>).
- Patch - Will create a minor release (vX.Y.Z) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.Z-<branchName>). A patch version bump is the default if nothing is specified for the PR.
- Prerelease - CI will create a prerelease of the module using the branch name as a prerelease tag in the version. This will create both a repository release and a prerelease version of the module on the PowerShell Gallery.
Once the PR is created, the Process-PSModule workflow will trigger.
When the PR is merged, a release will be created and the module will be published to the PowerShell Gallery with a stable version based on the version bump indicator the PR was was labeled with. Prerelease tags will be cleaned up on the repository.

Modules delivered on the PowerShell Gallery

Name	Description	Version
Admin	A PowerShell module working with the admin role.
AST	A PowerShell module for using the Abstract Syntax Tree (AST) to analyze any PowerShell code.
AzureDevOps	A PowerShell module to interact with the Azure DevOps REST API.
Context	A PowerShell module that manages contexts with secrets and variables.
DynamicParams	A PowerShell module that makes it easier to use dynamic params.
Fonts	A PowerShell module for managing fonts.
GitHub	A PowerShell module to interact with the GitHub API.
GoogleFonts	A PowerShell module to download and install fonts from GoogleFonts.
GraphQL	A PowerShell module to simplify working with a GraphQL APIs.
IPv4	A PowerShell module for managing IPv4 data
NerdFonts	A PowerShell module to download and install fonts from NerdFonts.
OpenAI	A PowerShell module for interacting with OpenAI
PATH	A PowerShell module to manage the PATH environment variable on Windows.
PowerShellGallery	A PowerShell module for interacting with the PowerShell Gallery.
PSSemVer	A PowerShell module adding a SemVer compatible class and functions.
PublicIP	A PowerShell module that helps getting info about your public IP.
Retry	A PowerShell module to create a retry mechanism around functions
Sodium	A PowerShell module for handling Sodium encrypted secrets.
Utilities	A PowerShell module with a collection of functions that should have been in PowerShell to start with.
WoW	A PowerShell module containing utilities for World of Warcraft.

PowerShell based Azure Function Apps

About

A PowerShell based Azure Function App is a serverless compute service that enables you to run event-driven code without having to manage the infrastructure. Azure Functions are ideal for processing data, integrating systems, and building simple APIs or microservices. They can be triggered by a variety of events, such as HTTP requests, timers, or messages from Azure services like Azure Storage, Event Grid, or Service Bus. We have created a framework that automates the process of creating, testing, and deploying PowerShell based Azure Function Apps to Azure. This framework is designed to make it easy for developers to create and deploy their Azure Function Apps without having to worry about the underlying infrastructure.

How we do it in PSModule

Projects based on the Template-FunctionApp repository template will automatically have the necessary workflows and configurations set up to automate the process of creating, testing, and deploying PowerShell based Azure Function Apps to Azure. This includes workflows for building, testing, and deploying the function app, as well as a configuration file for setting up the function app's metadata and dependencies. Using custom properties we set RepoType to FunctionApp. We use branch policies to control the flow of changes to the main branch, and we use labels to control the versioning of the module when a pull request is merged.

Create a new project

Create a repository based on the template Template-FunctionApp. The module will by default use the name of the repository.
Create a repository or organization secret called AZURE_CREDENTIALS, holding the credentials for the Azure service principal.
Configure the settings you want for the repository including a branch policy for the main branch.
On a topic branch:
1. develop the code you want to add to your function app.
2. delete the parts you do not need.
3. update the tests in the tests folder.
Create a PR. Add a label to the PR depending on what you want to do.
- Major - Will create a major release (vX.0.0) when merged. If specified with "Prerelease", a major version will be created using the prerelease tag (vX.0.0-<branchName>).
- Minor - Will create a minor release (vX.Y.0) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.0-<branchName>).
- Patch - Will create a minor release (vX.Y.Z) when merged. If specified with "Prerelease", a minor version will be created using the prerelease tag (vX.Y.Z-<branchName>). A patch version bump is the default if nothing is specified for the PR.
- Prerelease - CI will create a prerelease of the module using the branch name as a prerelease tag in the version. This will create both a repository release and a prerelease version of the module on the PowerShell Gallery.
Once the PR is created, the Process-FunctionApp workflow will trigger.
When the PR is merged, a release will be created and the function app will be deployed to Azure with a stable version based on the version bump indicator the PR was was labeled with. Prerelease tags will be cleaned up on the repository.

Function Apps we maintain

Name	Description	Version
GitHubApp	A GitHub app running on Azure Function App

PowerShell based GitHub Actions (composite action)

About

A composite action is a reusable action that is made up of one or more steps. Composite actions can be used to encapsulate common tasks or workflows that can be reused across multiple repositories. They are a great way to share code and best practices with the community, and they can help to streamline the development process by providing a consistent way to perform common tasks. We have created a framework that automates the process of creating, testing, and publishing PowerShell based GitHub Actions to the GitHub Marketplace. This framework is designed to make it easy for developers to create and share their GitHub Actions with the community.

How we do it in PSModule

Projects are based on the Template-Action repository template will automatically have the necessary workflows and configurations set up to automate the process of creating, testing, and deploying PowerShell based Azure Function Apps to Azure. This includes workflows for building, testing, and deploying the function app, as well as a configuration file for setting up the function app's metadata and dependencies. Using custom properties we set RepoType to FunctionApp. We use branch policies to control the flow of changes to the main branch, and we use labels to control the versioning of the module when a pull request is merged.

Create a new project

Create a repository based on the template Template-Action.

GitHub Actions on the GitHub Marketplace

Name	Description	Version
Auto‑Configure	Autmates the configuration of a GitHub repo
Auto‑Document	Automatically creates documentation for actions and workflows
Auto‑Release	Automatically creates releases based on pull requests and labels.
Build‑PSModule	Action that is used to build a PowerShell module.
Debug	Print info from the runner environment to logs
Download‑CIArtifact	Downloads an artifact from a CI workflow
Get‑AppJWT	A GitHub Action that gets a JWT for a GitHub App
Get‑IssueFormData	Get the data from a issue that was generated based on a issue form
GitHub‑Script	A GitHub Action used for running a PowerShell Script that uses the GitHub PowerShell module
Initialize‑PSModule	An action that is used to prepare the runner for PSModule framework.
Publish‑PSModule	Action that is used to publish a PowerShell module
Test‑PSModule	Test PowerShell modules with Pester and PSScriptAnalyzer.

Reusable workflows

About

Reusable workflows are a way to define a workflow in one repository and use it in multiple repositories. They can be used to automate common tasks, such as building, testing, and deploying code, and they can help to streamline the development process by providing a consistent way to perform these tasks across multiple repositories. We have created a framework that automates the process of creating, testing, and deploying reusable workflows in a organization. This framework is designed to make it easy for developers to create and share their workflows with the community.

How we do it in PSModule

Projects are based on the Template-Workflow repository template will automatically have the necessary workflows and configurations set up to automate the process of creating, testing, and deploying reusable workflows in a organization. This includes workflows for building, testing, and deploying the workflows, as well as a configuration file for setting up the workflows metadata and dependencies. Using custom properties we set RepoType to Workflow. We use branch policies to control the flow of changes to the main branch, and we use labels to control the versioning of the module when a pull request is merged.

Create a new project