{"meta":{"title":"Building and testing PowerShell","intro":"Learn how to create a continuous integration (CI) workflow to build and test your PowerShell project.","product":"GitHub Actions","breadcrumbs":[{"href":"/en/actions","title":"GitHub Actions"},{"href":"/en/actions/tutorials","title":"Tutorials"},{"href":"/en/actions/tutorials/build-and-test-code","title":"Build and test code"},{"href":"/en/actions/tutorials/build-and-test-code/powershell","title":"PowerShell"}],"documentType":"article"},"body":"# Building and testing PowerShell\n\nLearn how to create a continuous integration (CI) workflow to build and test your PowerShell project.\n\n## Introduction\n\nThis 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.\n\nGitHub-hosted runners have a tools cache with pre-installed software, which includes PowerShell and Pester.\n\nFor a full list of up-to-date software and the pre-installed versions of PowerShell and Pester, see [GitHub-hosted runners](/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software).\n\n## Prerequisites\n\nYou should be familiar with YAML and the syntax for GitHub Actions. For more information, see [Writing workflows](/en/actions/learn-github-actions).\n\nWe recommend that you have a basic understanding of PowerShell and Pester. For more information, see:\n\n* [Getting started with PowerShell](https://docs.microsoft.com/powershell/scripting/learn/ps101/01-getting-started)\n* [Pester](https://pester.dev)\n\n## Adding a workflow for Pester\n\nTo 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 called `resultsfile.log` is present.\n\nThis example workflow file must be added to your repository's `.github/workflows/` directory:\n\n```yaml\nname: Test PowerShell on Ubuntu\non: push\n\njobs:\n  pester-test:\n    name: Pester test\n    runs-on: ubuntu-latest\n    steps:\n      - name: Check out repository code\n        uses: actions/checkout@v6\n      - name: Perform a Pester test from the command-line\n        shell: pwsh\n        run: Test-Path resultsfile.log | Should -Be $true\n      - name: Perform a Pester test from the Tests.ps1 file\n        shell: pwsh\n        run: |\n          Invoke-Pester Unit.Tests.ps1 -Passthru\n```\n\n* `shell: pwsh` - Configures the job to use PowerShell when running the `run` commands.\n\n* `run: Test-Path resultsfile.log` - Check whether a file called `resultsfile.log` is present in the repository's root directory.\n\n* `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:\n\n  ![Screenshot of a workflow run failure for a Pester test. Test reports \"Expected $true, but got $false\" and \"Error: Process completed with exit code 1.\"](/assets/images/help/repository/actions-failed-pester-test-updated.png)\n\n* `Invoke-Pester Unit.Tests.ps1 -Passthru` - Uses Pester to execute tests defined in a file called `Unit.Tests.ps1`. For example, to perform the same test described above, the `Unit.Tests.ps1` will contain the following:\n\n  ```powershell\n  Describe \"Check results file is present\" {\n      It \"Check results file is present\" {\n          Test-Path resultsfile.log | Should -Be $true\n      }\n  }\n  ```\n\n## PowerShell module locations\n\nThe table below describes the locations for various PowerShell modules in each GitHub-hosted runner.\n\n<div class=\"ghd-tool rowheaders\">\n\n|                               | Ubuntu                                           | macOS                                             | Windows                                               |\n| ----------------------------- | ------------------------------------------------ | ------------------------------------------------- | ----------------------------------------------------- |\n| **PowerShell system modules** | `/opt/microsoft/powershell/7/Modules/*`          | `/usr/local/microsoft/powershell/7/Modules/*`     | `C:\\program files\\powershell\\7\\Modules\\*`             |\n| **PowerShell add-on modules** | `/usr/local/share/powershell/Modules/*`          | `/usr/local/share/powershell/Modules/*`           | `C:\\Modules\\*`                                        |\n| **User-installed modules**    | `/home/runner/.local/share/powershell/Modules/*` | `/Users/runner/.local/share/powershell/Modules/*` | `C:\\Users\\runneradmin\\Documents\\PowerShell\\Modules\\*` |\n\n</div>\n\n> \\[!NOTE]\n> On Ubuntu runners, Azure PowerShell modules are stored in `/usr/share/` instead of the default location of PowerShell add-on modules (i.e. `/usr/local/share/powershell/Modules/`).\n\n## Installing dependencies\n\nGitHub-hosted runners have PowerShell 7 and Pester installed. You can use `Install-Module` to install additional dependencies from the PowerShell Gallery before building and testing your code.\n\n> \\[!NOTE]\n> The pre-installed packages (such as Pester) used by GitHub-hosted runners are regularly updated, and can introduce significant changes. As a result, it is recommended that you always specify the required package versions by using `Install-Module` with `-MaximumVersion`.\n\nYou can also cache dependencies to speed up your workflow. For more information, see [Dependency caching reference](/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows).\n\nFor example, the following job installs the `SqlServer` and `PSScriptAnalyzer` modules:\n\n```yaml\njobs:\n  install-dependencies:\n    name: Install dependencies\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Install from PSGallery\n        shell: pwsh\n        run: |\n          Set-PSRepository PSGallery -InstallationPolicy Trusted\n          Install-Module SqlServer, PSScriptAnalyzer\n```\n\n> \\[!NOTE]\n> By default, no repositories are trusted by PowerShell. When installing modules from the PowerShell Gallery, you must explicitly set the installation policy for `PSGallery` to `Trusted`.\n\n### Caching dependencies\n\nYou can cache PowerShell dependencies using a unique key, which allows you to restore the dependencies for future workflows with the [`cache`](https://github.com/marketplace/actions/cache) action. For more information, see [Dependency caching reference](/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows).\n\nPowerShell caches its dependencies in different locations, depending on the runner's operating system. For example, the `path` location used in the following Ubuntu example will be different for a Windows operating system.\n\n```yaml\nsteps:\n  - uses: actions/checkout@v6\n  - name: Setup PowerShell module cache\n    id: cacher\n    uses: actions/cache@v4\n    with:\n      path: \"~/.local/share/powershell/Modules\"\n      key: ${{ runner.os }}-SqlServer-PSScriptAnalyzer\n  - name: Install required PowerShell modules\n    if: steps.cacher.outputs.cache-hit != 'true'\n    shell: pwsh\n    run: |\n      Set-PSRepository PSGallery -InstallationPolicy Trusted\n      Install-Module SqlServer, PSScriptAnalyzer -ErrorAction Stop\n```\n\n## Testing your code\n\nYou can use the same commands that you use locally to build and test your code.\n\n### Using PSScriptAnalyzer to lint code\n\nThe following example installs `PSScriptAnalyzer` and uses it to lint all `ps1` files in the repository. For more information, see [PSScriptAnalyzer on GitHub](https://github.com/PowerShell/PSScriptAnalyzer).\n\n```yaml\n  lint-with-PSScriptAnalyzer:\n    name: Install and run PSScriptAnalyzer\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Install PSScriptAnalyzer module\n        shell: pwsh\n        run: |\n          Set-PSRepository PSGallery -InstallationPolicy Trusted\n          Install-Module PSScriptAnalyzer -ErrorAction Stop\n      - name: Lint with PSScriptAnalyzer\n        shell: pwsh\n        run: |\n          Invoke-ScriptAnalyzer -Path *.ps1 -Recurse -Outvariable issues\n          $errors   = $issues.Where({$_.Severity -eq 'Error'})\n          $warnings = $issues.Where({$_.Severity -eq 'Warning'})\n          if ($errors) {\n              Write-Error \"There were $($errors.Count) errors and $($warnings.Count) warnings total.\" -ErrorAction Stop\n          } else {\n              Write-Output \"There were $($errors.Count) errors and $($warnings.Count) warnings total.\"\n          }\n```\n\n## Packaging workflow data as artifacts\n\nYou 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, see [Store and share data with workflow artifacts](/en/actions/using-workflows/storing-workflow-data-as-artifacts).\n\nThe following example demonstrates how you can use the `upload-artifact` action to archive the test results received from `Invoke-Pester`. For more information, see the [`upload-artifact` action](https://github.com/actions/upload-artifact).\n\n```yaml\nname: Upload artifact from Ubuntu\n\non: [push]\n\njobs:\n  upload-pester-results:\n    name: Run Pester and upload results\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Test with Pester\n        shell: pwsh\n        run: Invoke-Pester Unit.Tests.ps1 -Passthru | Export-CliXml -Path Unit.Tests.xml\n      - name: Upload test results\n        uses: actions/upload-artifact@v4\n        with:\n          name: ubuntu-Unit-Tests\n          path: Unit.Tests.xml\n    if: ${{ always() }}\n```\n\nThe `always()` function configures the job to continue processing even if there are test failures. For more information, see [Contexts reference](/en/actions/learn-github-actions/contexts#always).\n\n## Publishing to PowerShell Gallery\n\nYou 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, see [Using secrets in GitHub Actions](/en/actions/security-guides/using-secrets-in-github-actions).\n\nThe following example creates a package and uses `Publish-Module` to publish it to the PowerShell Gallery:\n\n```yaml\nname: Publish PowerShell Module\n\non:\n  release:\n    types: [created]\n\njobs:\n  publish-to-gallery:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - name: Build and publish\n        env:\n          NUGET_KEY: ${{ secrets.NUGET_KEY }}\n        shell: pwsh\n        run: |\n          ./build.ps1 -Path /tmp/samplemodule\n          Publish-Module -Path /tmp/samplemodule -NuGetApiKey $env:NUGET_KEY -Verbose\n```"}