Reusable pipeline templates and conventions: PSScriptAnalyzer and Pester in CI
Template files with parameters, naming, steps shared across applications, pre-deploy checks and PowerShell quality gates in CI.
With about fifteen PowerShell applications, every pipeline that reinvents its own build and test steps quickly becomes a source of drift. I factor the common parts into reusable YAML templates and stick to a few conventions. The result: a new pipeline is 30 lines instead of 300.
File layout
pipelines/
templates/
steps-lint.yml # PSScriptAnalyzer
steps-test.yml # Pester + publish results
steps-checkout.yml # multi-repo checkout + cleanup
steps-deploy-batch.yml
apps/
export/build.yml
export/schedule.yml
variables/
dev.yml acc.yml prd.yml
A template only contains steps (or jobs). It decides neither the trigger nor the environment: the calling pipeline assembles those.
A template with parameters
# templates/steps-test.yml
parameters:
- name: testPath
type: string
default: 'Tests'
- name: minCoverage
type: number
default: 0
steps:
- pwsh: |
Install-Module Pester -MinimumVersion 5.0 -Force -SkipPublisherCheck -Scope CurrentUser
$cfg = New-PesterConfiguration
$cfg.Run.Path = '${{ parameters.testPath }}'
$cfg.Run.PassThru = $true
$cfg.TestResult.Enabled = $true
$cfg.TestResult.OutputPath = 'TestResults.xml'
$r = Invoke-Pester -Configuration $cfg
if ($r.FailedCount -gt 0) { throw "$($r.FailedCount) test(s) failed" }
displayName: 'Pester'
- task: PublishTestResults@2
condition: always()
inputs:
testResultsFormat: NUnit
testResultsFiles: '**/TestResults.xml'
And the call:
steps:
- template: ../../templates/steps-lint.yml
- template: ../../templates/steps-test.yml
parameters:
testPath: 'apps/export/Tests'
Two details: condition: always() on the publish step, otherwise you lose the results exactly when tests fail; and the explicit throw, because a Pester failure does not fail the step by itself.
PSScriptAnalyzer
- pwsh: |
Install-Module PSScriptAnalyzer -Force -Scope CurrentUser
$issues = Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning
$issues | Format-Table RuleName, Severity, ScriptName, Line -AutoSize
if ($issues) { throw "$($issues.Count) analyzer finding(s)" }
displayName: 'PSScriptAnalyzer'
I block on Error and Warning, not on Information: otherwise the team ends up disabling the check.
Naming conventions
| Item | Convention |
|---|---|
| Template files | steps-<action>.yml, one role per file |
| Pipelines | <action>.yml next to the application (build, deploy, schedule) |
| Variable groups | vg-<team>-<environment> |
| Service connections | one per environment and scope, explicit name |
| Artifacts | <app>-package, version in the file name |
Checks before deploy
Before pushing to Batch, a step verifies that the ZIP exists, the version file is present, the shared module loads (Import-Module) and the deploy command is available. Each check fails early with a clear message rather than three minutes later inside the Azure API.
Pitfalls and lessons learned
- No
default: ''for an optional string parameter: the UI makes it required. Use a sentinel value ('auto','latest'). - Template parameters are resolved at compile time (
${{ }}), runtime variables ($(var)) later: do not mix them in a compile-time condition. - An over-generic template becomes unreadable. I factor what is repeated three times, not before.
- A template that throws on a missing name (an
'auto'never replaced) prevents deploying to an empty path. - Tests live next to the code they test, in a
Tests/folder; the template only runs them. - On self-hosted agents, clean the workspace at job level when you check out several repositories.