PSModulePublisher

A project containing the necessary tools to ease publishing of PowerShell modules.

Introduction

This project provides PowerShell cmdlets and CI templates that other projects can utilize for building, testing, and publishing PowerShell modules.

Setup

PSModulePublisher can be used as a submodule for building, testing, and publishing PowerShell modules.

Submodule

Main project structure

PSModulePublisher requires main projects to adopt the following directory structure:

/build/                                             # Directory containing build files
/build/PSModulePublisher/                           # The root directory of PSModulePublisher as a submodule
/build/definitions/modulemanifest.ps1               # The module manifest definition file

/src/MyPowershellModule/                            # The module's root directory
/src/MyPowershellModule/MyPowershellModule.psm1     # The module .psm1 file
/src/MyPowershellModule/MyPowershellModule.psd1     # The module .psd1 file (optional)

/test/                                              # Directory containing test files (optional)
/test/test.ps1                                      # The test entrypoint script (optional)

Adding the submodule

Add PSModulePublisher as a submodule under the directory build in your main project:

# Add the submodule
git submodule add https://github.com/theohbrothers/PSModulePublisher.git build/PSModulePublisher

# Checkout ref to use
git --git-dir build/PSModulePublisher/.git checkout vx.x.x

# Commit the submodule
git commit -am 'Add submodule PSModulePublisher vx.x.x'

Module file

Ensure the main project contains the module file at the location src/MyPowershellModule/MyPowershellModule.psm1.

Module manifest definition file

The project sources from a definition file to generate a manifest used for publishing the module. Ensure that the file exists in your main project at the location build/definitions/modulemanifest.ps1 and that it contains the right properties and values relevant to your PowerShell module. Remember to update the definition prior to publishing your module.

The definition template can be found here.

CI remote templates

Decide on which CI provider to use in your main project based on those supported by this project. Then setup the CI file(s) for your main project, referencing relevant CI remote template(s) of this project from your main project's CI file(s).

Sample CI files can be found here.

Test files (Optional)

The project optionally runs an entrypoint script for tests at the location test/test.ps1. You can add the module's main tests steps in this file for tests to be run.

Sample test files can be found here.

CI settings

Configure the following CI settings for your project.

Secrets

PSGallery API Key

Add a secret variable NUGET_API_KEY containing your PSGallery API key to your main project's CI settings for publishing your module on PowerShell Gallery.

Environment variables

Project base directory

By default, PSModulePublisher uses the main project's root directory as the path for execution. To override the default location, set the environment variable PROJECT_BASE_DIR to contain a custom directory value in your CI environment before executing PSModulePublisher.

Usage

Development

The PowerShell cmdlet Invoke-PSModulePublisher is used for executing the project's build, test, and publish steps for PowerShell modules.

Parameters

Invoke-PSModulePublisher [[-Repository] <string>] [-DryRun] [<CommonParameters>]

Commands

To perform the project's build, test, and publish steps for a given module, simply define applicable environment variables for a given PowerShell module project before executing the cmdlet.

# Process applicable environment variables
$env:PROJECT_BASE_DIR="$(git rev-parse --show-toplevel)"

# Build and Test steps (Generates module manifest, Tests module via module manifest)
Invoke-PSModulePublisher

# Publish steps (Publishes module as a dry run)
Invoke-PSModulePublisher -Repository MyPSRepository -DryRun

# Publish steps (Publishes module)
Invoke-PSModulePublisher -Repository MyPSRepository

Note: Ensure the environment variable NUGET_API_KEY is defined prior to publishing PowerShell modules.

The individual cmdlets may also be used for executing the project's build, test, and publish steps independently.

Continuous Integration (CI)

The project includes PowerShell cmdlets and CI remote templates for executing the project's build, test, and publish steps for PowerShell modules.

via Templates

The CI process with the included CI templates is composed of the following steps:

Build

1. Display system info
2. Get PowerShell version
3. Process build variables
4. Generate module manifest

Test

1. Test module via module's manifest

Publish

1. Install publish dependencies (if applicable)
2. Publish module

Build and Test steps can be executed for every commit pushed. Simply configure your main project's CI file(s) and/or settings to allow so.

Publish steps will run only for tag refs. Ensure your main project's CI file(s) and/or settings are configured to run CI jobs for tag refs.

Tags must follow Semantic Versioning and be prepended with a lowercase v:

# Tag the commit to publish
git tag v1.0.12

# Push the tag
git push remotename v1.0.12

Use cases

For a basic use case, the CI process could simply comprise a single stage containing all the steps from Build, Test, and Publish.

In cases where the module needs to be tested across multiple operating systems and/or versions of PowerShell, two stages can be configured: The 1st stage containing multiple jobs executing Build and Test steps for building and testing the module; the 2nd stage containing a single job executing Build and Publish steps for publishing the module.

Refer to the sample CI files for some working examples.

via Cmdlets

The following are the parameters and environment variables supported by the provided PowerShell cmdlets for building, testing, and publishing PowerShell modules.

Parameters

Invoke-Build [<CommonParameters>]
Invoke-Test [-ModuleManifestPath] <string> [<CommonParameters>]
Invoke-Publish [-ModuleManifestPath] <string> [-Repository] <string> [-DryRun] [<CommonParameters>]

Environment variables

Build, Test, Publish

Name	Example value	Mandatory	Type
PROJECT_BASE_DIR	/path/to/my-project	false	string

Publish

Name	Example value	Mandatory	Type
NUGET_API_KEY	xxx	true	string

Commands

To execute build, test, and publish steps for a project, simply define applicable environment variables before executing the individual cmdlets within the CI environment to perform their respective functions.

# Process applicable environment variables
$env:PROJECT_BASE_DIR="$(git rev-parse --show-toplevel)"

# Build (Generates module manifest)
$moduleManifestPath = Invoke-Build

# Test (Tests module via module manifest)
Invoke-Test -ModuleManifestPath $moduleManifestPath

# Publish (Publishes module)
Invoke-Publish -ModuleManifestPath $moduleManifestPath -Repository PSGallery

Note: Ensure the environment variable NUGET_API_KEY is defined prior to publishing PowerShell modules.

Managing the submodule

Retrieving updates

To update the submodule:

git submodule update --remote build/PSModulePublisher

Using a specific tag

To use a specific tag of the submodule:

# Checkout ref to use
git --git-dir build/PSModulePublisher/.git checkout vx.x.x

# Bump PSModulePublisher to the same ref in CI file
vi azure-pipelines.yml

# Commit the submodule and CI file
git commit -am 'Bump PSModulePublisher to vx.x.x'

Best practices

• Use only tag refs of PSModulePublisher in your main project.
• Ensure your main project's CI file(s) is configured to use the CI templates of PSModulePublisher and that the ref used matches that of the PSModulePublisher submodule used in your main project.