PSScriptModule - PowerShell Script Module Template

A modern PowerShell module template with CI/CD, testing, semantic versioning, and automated publishing

A production-ready PowerShell module template with built-in CI/CD, testing, versioning, and publishing workflows using GitHub Actions.

💡 Why This Template?

Most PowerShell module repositories start the same way: a few scripts, some manual testing, and CI/CD added later—often inconsistently. This template flips that model.

PSScriptModule is opinionated by design.
It gives you a complete, production-grade foundation so you can focus on writing PowerShell code—not wiring pipelines.

What makes it different?

• CI/CD from day one
  Build, test, analyze, version, and publish automatically using GitHub Actions.

• Best practices baked in
  Module structure, testing, security scanning, and documentation follow proven PowerShell and DevOps conventions.

• Automation over ceremony
  Versioning, changelogs, releases, and publishing happen automatically based on your commits and pull requests.

• Works everywhere
  Tested on Windows, Linux, and macOS, with optional devcontainer support for consistent environments.

• Scales with your project
  Suitable for prototypes, internal tooling, and fully open-source modules published to the PowerShell Gallery.

If you’ve ever thought “I just want to write PowerShell, not build pipelines”, this template is for you.

🎬 How to Use This Template

1. Click the "Use PowerShell Module Template" button below or use GitHub's "Use this template" button
2. Fill in your module name and description
3. Wait about 20 seconds for the automated bootstrap workflow to complete
4. Refresh the page to see your customized repository

📦 Features

When you create a module from this template, you get a fully wired, production-ready PowerShell module from day one. But wait, there’s more!

✅ CI/CD Ready

• End-to-end GitHub Actions workflows for build, test, release, and publishing
• Dependency management with intelligent caching for faster pipelines
• Cross-platform validation on Windows, Linux, and macOS
• Automated publishing to PowerShell Gallery and NuGet.org

✅ Development Environment

• Opinionated VS Code setup (settings and recommended extensions)
• Pre-configured build, run, and debug tasks
• Devcontainer support for consistent, sandboxed development environments

✅ Version Management

• Semantic versioning powered by GitVersion
• GitHub Flow–based release strategy
• Commit-driven version bumps using +semver: keywords
• Automatic changelog generation from merged pull requests

✅ Code Quality and Testing

• Pester-based unit testing framework
• Code coverage reporting
• Built-in security scanning with PSScriptAnalyzer, InjectionHunter, and CodeQL

✅ Project Documentation

• Markdown-based help generation using PlatyPS
• Auto-generated external help for Get-Help
• Structured, comprehensive documentation in the /docs directory

📂 Project Structure

PSScriptModule/
├── 📄 .devcontainer/                // Devcontainer configuration for VS Code
├── 📄 .github/                      // GitHub Actions workflows and issue templates
│   ├── 📁 workflows/                // CI/CD pipeline definitions
│   └── 📁 ISSUE_TEMPLATE/           // Issue and pull request templates
├── 📄 .vscode/                      // VS Code workspace settings and recommended extensions
├── 📄 PSScriptModule.build.ps1      // Invoke-Build script with all build tasks
├── 📄 requirements.psd1             // PSDepend configuration for dependencies
├── 📄 gitversion.yml                // GitVersion configuration
├── 📁 src/                          // Source code
│   ├── 📄 PSScriptModule.psd1       // Module manifest
│   ├── 📁 Classes/                  // Classes definitions
│   ├── 📁 Public/                   // Public functions (exported)
│   └── 📁 Private/                  // Private functions (internal only)
├── 📁 tests/                        // Test suites
│   ├── 📁 PSScriptAnalyzer/         // Static code analysis tests
│   └── 📁 InjectionHunter/          // Security vulnerability tests
├── 📁 docs/                         // Markdown documentation

🚀 Getting Started

Prerequisites

Required:

• PowerShell 7.0+
• Visual Studio Code with PowerShell extension (recommended)
• Git for version control

Optional dependencies:

• GitHub Copilot for enhanced development experience
• Docker or Rancher Desktop for consistent development environments in devcontainers
• PowerShell Gallery account for publishing

Quick Start

1. Click on the "Use this template" button above to create your own repository from this template. Personalize it by updating the name, description, and visibility.

2. Clone your new repository locally:

   git clone https://github.com/YourUsername/YourModuleName.git
   cd YourModuleName

3. Install dependencies:

   Note: If using the devcontainer (.devcontainer/ folder), dependencies are pre-installed. Skip this step.

   # Install PSDepend if not already installed
   Install-Module -Name PSDepend -Scope CurrentUser -Force
   
   # Install all project dependencies
   Invoke-PSDepend -Path ./requirements.psd1 -Install -Import -Force

4. Run build and test tasks:

   # Run default build (Clean + Build)
   Invoke-Build
   
   # Run all tests
   Invoke-Build Test

5. You are now ready to start developing your PowerShell module!

Next Steps

After setup, customize your module:

1. Update Module Manifest (src/YourModuleName.psd1):

   • Set Author, CompanyName, Copyright
   • Update Description and Tags

   Note: Do not change ModuleVersion, RootModule, or FunctionsToExport - it is managed automatically

2. Start Developing:

   • Add functions to src/Public/ (exported) or src/Private/ (internal)
   • Create corresponding .Tests.ps1 files

3. Push your changes and open a pull request to trigger CI/CD workflows

📘 Documentation

Comprehensive documentation is available in the docs/ directory:

• 🚀 Getting Started Guide - Initial setup, prerequisites, and your first function
• 🛠️ Development Guide - Creating functions, building, testing, and generating help
• 🔄 CI/CD & Publishing Guide - Automated pipelines, versioning, and PowerShell Gallery publishing

🤝 Contributing

Contributions are welcome! Whether it’s bug fixes, improvements, or ideas for new features, your input helps make this template better for everyone. Please see CONTRIBUTING.md for details on:

• Pull request workflow
• Code style and conventions
• Testing and quality requirements

⭐ Support This Project

If this template saves you time or helps your projects succeed, consider supporting it:

• ⭐ Star the repository to show your support
• 🔁 Share it with other PowerShell developers
• 💬 Provide feedback via issues or discussions
• ❤️ Sponsor ongoing development via GitHub Sponsors

---

Built with ❤️ by Warehouse Finds