ReadMe.md

PowerShell Script Module Repository Template

A template repository and module for creating new PowerShell script module repos quickly with boilerplate files and CI/CD workflows already defined.

✨ Features

Use this repo template or module for your new git repository to get the following features out-of-the-box:

• GitHub Actions workflows (Azure DevOps Pipelines YAML support coming soon) that:
  • Publish a prerelease version on every commit to the main branch, and a stable version once manually approved.
    • Can also manually trigger deployments of feature branches.
  • Version the module.
  • Run PSScriptAnalyzer to ensure best practices are followed.
  • Run build tests with Pwsh and PowerShell to ensure backward compatibility.
  • Run smoke tests on multiple platforms (Windows, Linux, MacOS) to ensure the module works as expected after being installed on all platforms.
  • Publish the module to the PowerShell Gallery (custom feed support coming soon).
  • Spell check all files in the repository.
  • Display test code coverage results on PRs.
• Visual Studio Code tasks to easily run Pester tests and PSScriptAnalyzer locally.
• A .devcontainer for use with Visual Studio Code's Dev Containers extension and GitHub Codespaces.
• Boilerplate repository files, such as ReadMe, License, Changelog, .gitignore, .editorconfig, PR and Issue templates, and more.

This template/module does not require any additional modules or dependencies to be installed on your machine, or force you to learn a new build framework or language.

I plan on creating a dedicated video tutorial for this module and template, but until then you can watch the demo portion of this presentation that shows setting it up and using it, and talks about some of the benefits it provides.

🚀 Get started

There are two ways to create your new PowerShell module repository:

1. Use the New-PowerShellScriptModuleRepository cmdlet to create a new repository, or
2. Create a new repository from this template in GitHub.

Both of these methods are described in more detail below.

Once the repository is created, follow the instructions in the repo's ReadMe file to complete the setup. The non-transformed instructions can also be viewed here.

📂 Method 1: Use the New-PowerShellScriptModuleRepository cmdlet

Step 1: Install the ScriptModuleRepositoryTemplate module from the PowerShell Gallery:

Install-Module -Name ScriptModuleRepositoryTemplate -Scope CurrentUser

Step 2: Create the new repository files:

New-PowerShellScriptModuleRepository -RepositoryDirectoryPath 'C:\MyRepoName' -ModuleName 'MyModuleName' -OrganizationName 'My Name'

The above command will create a new directory at C:\MyRepoName with the boilerplate files and workflows for publishing your module already set up.

You can then perform a git init in that directory and push it to where you want your git repository hosted (e.g. Azure DevOps or GitHub).

To complete the setup, follow the instructions in the module repo's ReadMe file.

📄 Method 2: Create repository from GitHub template

If your repository will be hosted on GitHub, you can follow the steps below:

🗍 Step 1: Create a new repo from this template

The official docs for creating a new repository from a template can be found here. In short, the steps are:

1. Click the Use this template button at the top of the repository and choose Create a new repository.
2. Name your new repository (including your module's name is a good idea) and give it a description.
3. Click the Create repository button.
4. You should now have the new repository in your account with the name you chose.
5. Clone your new repository to your local machine to start making changes to it.

🤖 Step 2: Replace repo template information

Run the _InitializeRepository.ps1 script to update the repository files with your module's information. You will be prompted to enter some information, such as:

• Your module's name (no spaces)
• Your name or organization name (may contain spaces)

Once the script completes, most of the repo files will be replaced. You should commit the changes.

To complete the setup, follow the instructions in the repo's new ReadMe file (that replaced this one).

📋 Create your own template (optional)

Not happy with some of the default template configurations? Maybe you don't like the .editorconfig settings, or want it to publish to your own internal PowerShell Gallery feed by default? You can derive your own template from this repository and use it for your future modules, minimizing the custom changes you need to make every time you create a new repo.

To create your own template:

1. Fork this repository on GitHub.
2. In GitHub, from your repo's Settings tab under the General section, rename the repository to reflect that it is a template and check the box to make it a Template repository.
3. Modify the template repo files with whatever customizations you want.
4. If you are introducing more replacement tokens in the files, you will need to update the Set-TemplateTokenValuesInAllRepositoryFiles function in the ScriptModuleRepositoryTemplate.psm1 file to handle them.

You can now create new repositories from your GitHub template in the same way you would use this one.

If you want to be able to create new repositories from a module, you will need to publish your module under a different name.

⏪ Changelog

See what's changed in the module and template over time by viewing the changelog.

❤ Donate to support this module and template

Buy me a hot apple cider for providing this module and template open source and for free 🙂

TODO

Things to still do:

• Add support for Azure DevOps.
• Allow user to create single .psm1 file or Public/Private directory structure for separate files per function.
• Allow using a custom PowerShell Gallery feed URL.
• Have screenshots and/or recordings of manual steps to setup GitHub and Azure DevOps, since they involve clicking around in the UI. Perhaps link to this tutorial for Azure DevOps?
  • Perhaps we can automate this to avoid the manual steps altogether?
• Maybe support new deployments on tag creation.