Getting Started with ModuleForge

ModuleForge scaffolds a production-ready PowerShell module structure - including CI/CD pipelines, Pester test stubs, and semantic versioning - so you can focus on writing functions rather than plumbing.


Prerequisites

Local tools

Requirement Minimum Version
PowerShell 7.6+ (the current LTS)
Git Any recent version
Pester 6.0+
PSScriptAnalyzer 1.25+
Microsoft.PowerShell.PSResourceGet 1.1.1+ (included with PowerShell 7.4 and newer)

Your pipelines don’t depend on what you have installed locally: they install the versions pinned in your project’s BuildDependencies.psd1. See Build Dependencies.

A terminal and any text editor will do, but VSCode is assumed in the step-by-step tutorials.

Platform account (pick one)

Platform What you need
GitHub A GitHub account and a repository (public or private)
Azure DevOps An Azure DevOps organisation and project, with an Artifacts feed and build service permissions configured - see Azure DevOps Prerequisites

Runner / agent setup

GitHub Actions - the scaffolded workflows use ubuntu-latest (GitHub-hosted runners). No setup is required for most cases. If you need Windows-specific behaviour or a private network, configure a self-hosted runner and update the runs-on: value in the generated workflow files.

Azure DevOps - the scaffolded pipelines also target ubuntu-latest. If your organisation does not have Microsoft-hosted agents enabled, or you need a specific environment, you will need to provision a self-hosted agent and update the pool: in the generated pipeline YAML.


Install ModuleForge

# PowerShell 7.4 and newer include PSResourceGet. On anything older, bootstrap it first:
# Install-Module Microsoft.PowerShell.PSResourceGet -Force

Install-PSResource -Name Pester, PSScriptAnalyzer, ModuleForge

Scaffold a New Module

From your (already-initialised) git repository root:

# Create the folder structure, build config and CI/CD workflows in one step
New-MFProject -ModuleName 'MyModule' -Description 'What my module does' -Scaffold GitHub

Use -Scaffold AzureDevOps for Azure DevOps pipelines, or -Scaffold GitHub,AzureDevOps for both. You can also add the CI scaffold later, or to an existing project, with Add-MFGithubScaffold or Add-MFAzureDevOpsScaffold.

Optional: Project Rules. To check your code against your own standards as well as the default lint, add the ready-made rule sets. One checks for Constrained Language Mode compatibility, the other that every public function has a help example:

Add-MFProjectRules

See Project Rules for what they do, and how to add your own.

Commit the scaffolding back to main before doing anything else - the CI workflows need to exist on the default branch before they can run.

chore: initialise ModuleForge project with scaffolding and workflows

What Gets Created

MyModule/
├── source/
│   ├── functions/          ← exported functions (.ps1 + .Tests.ps1)
│   ├── private/            ← internal helpers (not exported)
│   ├── classes/            ← PowerShell classes
│   ├── enums/              ← enum definitions
│   ├── validationClasses/  ← custom [ValidateScript] types
│   └── resource/           ← non-code files bundled with the module
├── scripts/                ← scripts the pipelines run, which you can run locally too
├── buildTest/              ← tests of the published module, for the optional Build Test
├── BuildDependencies.psd1  ← the module versions your pipelines install
├── moduleForgeConfig.xml   ← build and publish configuration
└── .github/workflows/      ← CI/CD workflows (GitHub), or .azuredevops/pipelines/ (Azure DevOps)

Files ending .example in the workflows or pipelines folder are optional extras, such as Build Test and Project Rules. Rename one to remove .example and enable it.

Each function gets its own file. Each function file gets its own FunctionName.Tests.ps1 alongside it - Pester picks these up automatically.


Development Workflow

flowchart TD
    A([Start a new module]) --> B[Write your functions]
    B --> C[Run tests locally\nInvoke-Pester]
    C --> D[Commit and open a PR]
    subgraph CI
        D --> E[Pester + PSScriptAnalyzer\nrun automatically]
        E --> F[Review and merge]
    end
    subgraph CD
        F --> G[Trigger Build and Release\nvia GitHub Actions]
        G --> H[Module published\nto Artifacts feed]
    end
    H --> B

The CI pipelines run automatically on every PR. The Build and Release step is triggered manually - you decide when a version is ready to ship and what kind of version bump it gets.

PSScriptAnalyzer runs on every PR as a soft gate - it reports findings but does not block a merge. The results are posted as a PR comment, grouped by severity: Error, Warning, and Information. Errors represent genuine problems (undefined variables, syntax issues); Warnings are style and best-practice concerns worth addressing; Information is advisory. The weighting is intentional - not everything flagged demands action, but the highest-severity items are surfaced first so you can prioritise. Treat the report as a code review prompt rather than a hard stop.


Writing Your First Function

Add a .ps1 file to source/functions/ and a matching .Tests.ps1 alongside it:

# source/functions/Get-Greeting.ps1
function Get-Greeting {
    <#
        .SYNOPSIS
            Returns a greeting string.
        .EXAMPLE
            Get-Greeting -Name 'World'
    #>
    [CmdletBinding()]
    param(
        [string]$Name = 'World'
    )
    process {
        "Hello, $Name!"
    }
}
# source/functions/Get-Greeting.Tests.ps1
BeforeAll {
    . $PSCommandPath.Replace('.Tests.ps1', '.ps1')
}

Describe 'Get-Greeting' {
    It 'returns the default greeting' {
        Get-Greeting | Should -Be 'Hello, World!'
    }
    It 'uses the provided name' {
        Get-Greeting -Name 'PowerShell' | Should -Be 'Hello, PowerShell!'
    }
}

Always run tests locally before committing. Two options:

Run a specific test file directly with Pester:

Invoke-Pester .\source\functions\Get-Greeting.Tests.ps1

Or run the full test suite with code coverage - mirrors exactly what the CI pipeline does:

.\scripts\Invoke-MFPester.ps1

Invoke-MFPester.ps1 is a standalone script (added to your project by Add-MFProjectScripts) that discovers all *.Tests.ps1 files under source/functions/ and source/private/ (plus a root tests/ folder if you have one), runs them with code coverage enabled, and reports the results. Use this before opening a PR to confirm you’re in the same state the automated pipeline will see. On Constrained Language Mode systems, add -SkipCodeCoverage - coverage instrumentation cannot run there.

Looking for a house style for the code inside your functions? The PowerShell Style Recommendations page collects a set of optional, non-binding conventions (quoting, collections, function shape, cross-platform habits) you can adopt as a starting point.

Commit with the right prefix so your changelog generates correctly:

feat: add Get-Greeting function
test: add Pester tests for Get-Greeting

Next Steps

Goal Where to go
Full walkthrough - GitHub setup GitHub Getting Started Tutorial
Advanced features - enums, classes, private functions AstroCmdlets: An Advanced Tutorial
Azure DevOps setup Azure DevOps Tutorial
Your release rhythm, in practice Making the Most of Releases
Choosing version and release options Build and Release Guide
Installing from your private feed Using Private Package Feeds
Checking the module you published Testing the Published Module
All commit prefixes and their effects Commit Prefixes
Optional code style conventions PowerShell Style Recommendations
Full function reference Functions