Introduction

This guide shows you how to use PowerShell for CI. It describes how to use Pester, install dependencies, test your module, and publish to the PowerShell Gallery.

GitHub-hosted runners have a tools cache with pre-installed software, which includes PowerShell and Pester.

For a full list of up-to-date software and the pre-installed versions of PowerShell and Pester, seeGitHub-hosted runners.

Prerequisites

You should be familiar with YAML and the syntax for GitHub Actions. For more information, seeWriting workflows.

We recommend that you have a basic understanding of PowerShell and Pester. For more information, see:

• Getting started with PowerShell
• Pester

Adding a workflow for Pester

To automate your testing with PowerShell and Pester, you can add a workflow that runs every time a change is pushed to your repository. In the following example,Test-Path is used to check that a file calledresultsfile.log is present.

This example workflow file must be added to your repository's.github/workflows/ directory:

name:TestPowerShellonUbuntuon:pushjobs:pester-test:name:Pestertestruns-on:ubuntu-lateststeps:-name:Checkoutrepositorycodeuses:actions/checkout@v5-name:PerformaPestertestfromthecommand-lineshell:pwshrun:Test-Pathresultsfile.log|Should-Be$true-name:PerformaPestertestfromtheTests.ps1fileshell:pwshrun:|          Invoke-Pester Unit.Tests.ps1 -Passthru

• shell: pwsh - Configures the job to use PowerShell when running therun commands.

• run: Test-Path resultsfile.log - Check whether a file calledresultsfile.log is present in the repository's root directory.

• Should -Be $true - Uses Pester to define an expected result. If the result is unexpected, then GitHub Actions flags this as a failed test. For example:

  

• Invoke-Pester Unit.Tests.ps1 -Passthru - Uses Pester to execute tests defined in a file calledUnit.Tests.ps1. For example, to perform the same test described above, theUnit.Tests.ps1 will contain the following:

  Describe"Check results file is present" {    It"Check results file is present" {Test-Path resultsfile.log | Should-Be$true    }}

PowerShell module locations

The table below describes the locations for various PowerShell modules in each GitHub-hosted runner.

Installing dependencies

GitHub-hosted runners have PowerShell 7 and Pester installed. You can useInstall-Module to install additional dependencies from the PowerShell Gallery before building and testing your code.

You can also cache dependencies to speed up your workflow. For more information, seeDependency caching reference.

For example, the following job installs theSqlServer andPSScriptAnalyzer modules:

jobs:install-dependencies:name:Installdependenciesruns-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:InstallfromPSGalleryshell:pwshrun:|          Set-PSRepository PSGallery -InstallationPolicy Trusted          Install-Module SqlServer, PSScriptAnalyzer

Caching dependencies

You can cache PowerShell dependencies using a unique key, which allows you to restore the dependencies for future workflows with thecache action. For more information, seeDependency caching reference.

PowerShell caches its dependencies in different locations, depending on the runner's operating system. For example, thepath location used in the following Ubuntu example will be different for a Windows operating system.

steps:-uses:actions/checkout@v5-name:SetupPowerShellmodulecacheid:cacheruses:actions/cache@v4with:path:"~/.local/share/powershell/Modules"key:${{runner.os}}-SqlServer-PSScriptAnalyzer-name:InstallrequiredPowerShellmodulesif:steps.cacher.outputs.cache-hit!='true'shell:pwshrun:|      Set-PSRepository PSGallery -InstallationPolicy Trusted      Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop

Testing your code

You can use the same commands that you use locally to build and test your code.

Using PSScriptAnalyzer to lint code

The following example installsPSScriptAnalyzer and uses it to lint allps1 files in the repository. For more information, seePSScriptAnalyzer on GitHub.

lint-with-PSScriptAnalyzer:name:InstallandrunPSScriptAnalyzerruns-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:InstallPSScriptAnalyzermoduleshell:pwshrun:|          Set-PSRepository PSGallery -InstallationPolicy Trusted          Install-Module PSScriptAnalyzer -ErrorAction Stop-name:LintwithPSScriptAnalyzershell:pwshrun:|          Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues          $errors   = $issues.Where({$_.Severity -eq 'Error'})          $warnings = $issues.Where({$_.Severity -eq 'Warning'})          if ($errors) {              Write-Error "There were $($errors.Count) errors and $($warnings.Count) warnings total." -ErrorAction Stop          } else {              Write-Output "There were $($errors.Count) errors and $($warnings.Count) warnings total."          }

Packaging workflow data as artifacts

You can upload artifacts to view after a workflow completes. For example, you may need to save log files, core dumps, test results, or screenshots. For more information, seeStore and share data with workflow artifacts.

The following example demonstrates how you can use theupload-artifact action to archive the test results received fromInvoke-Pester. For more information, see theupload-artifact action.

name:UploadartifactfromUbuntuon: [push]jobs:upload-pester-results:name:RunPesteranduploadresultsruns-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:TestwithPestershell:pwshrun:Invoke-PesterUnit.Tests.ps1-Passthru|Export-CliXml-PathUnit.Tests.xml-name:Uploadtestresultsuses:actions/upload-artifact@v4with:name:ubuntu-Unit-Testspath:Unit.Tests.xmlif:${{always()}}

Thealways() function configures the job to continue processing even if there are test failures. For more information, seeContexts reference.

Publishing to PowerShell Gallery

You can configure your workflow to publish your PowerShell module to the PowerShell Gallery when your CI tests pass. You can use secrets to store any tokens or credentials needed to publish your package. For more information, seeUsing secrets in GitHub Actions.

The following example creates a package and usesPublish-Module to publish it to the PowerShell Gallery:

name:PublishPowerShellModuleon:release:types: [created]jobs:publish-to-gallery:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v5-name:Buildandpublishenv:NUGET_KEY:${{secrets.NUGET_KEY}}shell:pwshrun:|          ./build.ps1 -Path /tmp/samplemodule          Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose