The PowerShell build runner is specifically designed to run PowerShell scripts.
The plugin responsible for PowerShell integration has been opensourced on GitHub: https://github.com/JetBrains/teamcity-powershell
On this page:
Since TeamCity 2017.1, TeamCity provides support for PowerShell on Linux and Mac OS: download a PowerShell package for your platform and install it on the TeamCity agent.
List of PowerShell versions supported by TeamCity. It is passed to
PowerShell run mode
Select the desired execution mode on a x64 machine:
Specify a version (e.g. 1.0, 2.0, etc.). It will be compared to the version installed on the agent, and an appropriate requirement will be added.
If the version field is left blank, no lower bound on the version requirement will be added, no
Select platform bitness:
Select a PowerShell edition to be used: (since TeamCity 2017.1)
Format stderr output as:
Specify how the error output is handled by the runner:
Specify the path to the build working directory.
Select whether you want to enter the script right in TeamCity, or specify a path to the script:
Script execution mode
Specify the PowerShell script execution mode. By default, PowerShell may not allow execution of arbitrary
Available if "Script execution mode" option is set to "Execute .ps1 script from external file". Specify here arguments to be passed into PowerShell script.
Additional command line parameters
Specify parameters to be passed to
Interaction with TeamCity
Attention must be paid when using PowerShell to interact with TeamCity through service messages.
PowerShell tends to wrap strings written to the console with commands like
Write-Error and similar (see TW-15080). To avoid this behavior, either use the
Write-Host command, or adjust the buffer length manually:
Due to this issue in PowerShell itself that causes zero exit code to be always returned to a caller, TeamCity cannot always detect whether the script has executed correctly or not. We recommend several approaches that can help in detecting script execution failures:
Manually catching exceptions and explicitly returning exit code
The PowerShell plugin does not use the cmd wrapper around
powershell.exe. It makes returning the explicit exit code possible.
- Setting Error Output to
Errorand adding a build failure condition
In case syntax errors and exceptions are present, PowerShell writes them to
stderr. To make TeamCity fail the build, set Error Output option to
Errorand add a build failure condition that will fail the build on any error output.
Failing build on certain message in build log
Add a build failure condition that will fail the build on a certain message (say "POWERSHELL ERROR") in the build log.
To properly handle non-ASCII output from PowerShell, the correct encoding must be set both on the PowerShell side and on the TeamCity side.
To set the output encoding for PowerShell to UTF-8, add the following line to the beginning of your PowerShell script:
- To set the encoding on the TeamCity agent side, either set the java launch option
-Dfile.encoding=UTF-8, or set the build configuration parameter
teamcity.runner.commandline.stdstreams.encoding value toUTF-8
The TeamCity PowerShell plugin uses temporary files as an entry point; these files are created in the build temporary folder and removed after the PowerShell build step is finished. To keep the files, set the
teamcity.dont.delete.temp.files configuration parameter to
The PowerShell support is implemented as an open-source plugin. For development links refer to the plugin's page.