Setting up PSRule

PSRule supports running within continuous integration (CI) systems or locally. It is shipped as a PowerShell module which makes it easy to install and distribute updates.

Task	Options
Run tests within CI pipelines	With GitHub Actions or Azure Pipelines or CLI or PowerShell
Run tests locally during development	With Visual Studio Code and CLI / PowerShell
Create custom tests for your organization	With Visual Studio Code and CLI / PowerShell

Tip

PSRule provides native integration to popular CI systems such as GitHub Actions and Azure Pipelines. If you are using a different CI system you can use the local install to run on MacOS, Linux, and Windows worker nodes.

With GitHub Actions

GitHub Action

Install and use PSRule with GitHub Actions by referencing the microsoft/ps-rule action.

Specific versionLatest stable v2Latest stable

GitHub Actions

- name: Analyze with PSRule
  uses: microsoft/ps-rule@v2.9.0

GitHub Actions

- name: Analyze with PSRule
  uses: microsoft/ps-rule@v2

GitHub Actions

- name: Analyze with PSRule
  uses: microsoft/ps-rule@latest

This will automatically install compatible versions of all dependencies.

Tip

The recommended approach is to pin to the latest specific version. Pinning to a specific version reduces the risk of new versions breaking your pipeline. You can easily update to the latest version by changing the version number. At such time, you can test the new version in a feature branch before merging to main.

Working with Dependabot

You can use Dependabot to automatically upgrade your PSRule action if you use a specific version. When new versions a released Dependabot will automatically add a pull request (PR) for you to review and merge.

.github/dependabot.yaml

#
# Dependabot configuration
#
version: 2
updates:

  # Maintain GitHub Actions
  - package-ecosystem: github-actions
    directory: '/'
    schedule:
      interval: daily

With Azure Pipelines

Extension

Install and use PSRule with Azure Pipeline by using extension tasks. Install the extension from the marketplace, then use the ps-rule-assert task in pipeline steps.

- task: ps-rule-assert@2
  displayName: Analyze Azure template files
  inputs:
    inputType: repository

This will automatically install compatible versions of all dependencies.

With CLI

PSRule can be installed from NuGet.org using the .NET CLI where the .NET 8.0 SDK is available. You can use this option to install on CI workers that are not natively supported.

To install PSRule as a global tool use the following command line:

dotnet tool install -g Microsoft.PSRule.Tool

To install a specific version use the following command line:

dotnet tool install -g Microsoft.PSRule.Tool --version 3.0.0-B0203

For a list of commands supported by the CLI, see PSRule CLI.

With PowerShell

PSRule can be installed locally from the PowerShell Gallery using PowerShell. You can use this option to install on CI workers that are not natively supported.

Prerequisites

Operating System	Tool	Installation Link
Windows	Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater.	link
Windows, MacOS, Linux	PowerShell version 7.4.x or greater.	link

Note

If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.

Installing PowerShell

PowerShell 7.x can be installed on MacOS, Linux, and Windows but is not installed by default. For a list of platforms that PowerShell 7.4 is supported on and install instructions see Get PowerShell.

Getting the modules

Module

PSRule can be installed or updated from the PowerShell Gallery. Use the following command line examples from a PowerShell terminal to install or update PSRule.

For the current userFor all users

To install PSRule for the current user use:

Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser

To update PSRule for the current user use:

Update-Module -Name 'PSRule' -Scope CurrentUser

Open PowerShell with Run as administrator on Windows or sudo pwsh on Linux.

To install PSRule for all users (requires admin/ root permissions) use:

Install-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers

To update PSRule for all users (requires admin/ root permissions) use:

Update-Module -Name 'PSRule' -Scope AllUsers

Pre-release versions

To use a pre-release version of PSRule add the -AllowPrerelease switch when calling Install-Module, Update-Module, or Save-Module cmdlets.

Tip

To install pre-release module versions, the latest version of PowerShellGet may be required.

# Install the latest PowerShellGet version
Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force

For the current userFor all users

To install PSRule for the current user use:

Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force
Install-Module -Name 'PSRule' -Repository PSGallery -Scope CurrentUser -AllowPrerelease

Open PowerShell with Run as administrator on Windows or sudo pwsh on Linux.

To install PSRule for all users (requires admin/ root permissions) use:

Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force
Install-Module -Name 'PSRule' -Repository PSGallery -Scope AllUsers -AllowPrerelease

Building from source

Source

PSRule is provided as open source on GitHub. To build PSRule from source code:

1. Clone the GitHub repository.
2. Run ./build.ps1 from a PowerShell terminal in the cloned path.

This build script will compile the module and documentation then output the result into out/modules/PSRule.

Development dependencies

The following PowerShell modules will be automatically install if the required versions are not present:

• PlatyPS
• Pester
• PSScriptAnalyzer
• PowerShellGet
• PackageManagement
• InvokeBuild

These additional modules are only required for building PSRule.

Additionally .NET SDK v8 is required. .NET will not be automatically downloaded and installed. To download and install the latest SDK see Download .NET 8.0.

Limited access networks

If you are on a network that does not permit Internet access to the PowerShell Gallery, download the required PowerShell modules on an alternative device that has access. PowerShell provides the Save-Module cmdlet that can be run from a PowerShell terminal to do this.

The following command lines can be used to download the required modules using a PowerShell terminal. After downloading the modules, copy the module directories to devices with restricted Internet access.

Runtime modulesDevelopment modules

To save PSRule for offline use:

Save-Module -Name 'PSRule' -Path '.\modules'

This will save PSRule into the modules sub-directory.

To save PSRule development module dependencies for offline use:

$modules = @('PlatyPS', 'Pester', 'PSScriptAnalyzer', 'PowerShellGet',
'PackageManagement', 'InvokeBuild')
Save-Module -Name $modules -Repository PSGallery -Path '.\modules';

This will save required developments dependencies into the modules sub-directory.

Tip

If you use additional rules modules such as PSRule for Azure you should also save these for offline use.

Note

If you are using Windows PowerShell you may need to bootstrap NuGet before you can install modules. The NuGet package provider is not installed in Windows PowerShell be default. For instructions see Bootstrapping NuGet.

Comments