PowerShell on Target Machines task

Azure Pipelines | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015

Use this task in a build or release pipeline to execute PowerShell scripts on remote machine(s).

This task can run both PowerShell scripts and PowerShell-DSC scripts:

  • For PowerShell scripts, the computers must have PowerShell 2.0 or higher installed.
  • For PowerShell-DSC scripts, the computers must have Windows Management Framework 4.0 installed. This is installed by default on Windows 8.1, Windows Server 2012 R2, and later.


In Microsoft Team Foundation Server (TFS) 2018 and previous versions, run and release pipelines are called definitions, runs are called builds, service connections are called service endpoints, stages are called environments, and jobs are called phases.


This task uses Windows Remote Management (WinRM) to access on-premises physical computers or virtual computers that are domain-joined or workgroup-joined.

To set up WinRM for on-premises physical computers or virtual machines

Follow the steps described in domain-joined

To set up WinRM for Microsoft Azure Virtual Machines

Azure Virtual Machines require WinRM to use the HTTPS protocol. You can use a self-signed Test Certificate. In this case, the automation agent will not validate the authenticity of the certificate as being issued by a trusted certification authority.

  • Azure Classic Virtual Machines. When you create a classic virtual machine from the Azure portal, the virtual machine is already set up for WinRM over HTTPS, with the default port 5986 already opened in the firewall and a self-signed certificate installed on the machine. These virtual machines can be accessed with no further configuration required. Existing Classic virtual machines can be also selected by using the Azure Resource Group Deployment task.

  • Azure Resource Group. If you have an Azure Resource Group already defined in the Azure portal, you must configure it to use the WinRM HTTPS protocol. You need to open port 5986 in the firewall, and install a self-signed certificate.

To dynamically deploy Azure Resource Groups that contain virtual machines, use the Azure Resource Group Deployment task. This task has a checkbox named Enable Deployment Pre-requisites. Select this to automatically set up the WinRM HTTPS protocol on the virtual machines, open port 5986 in the firewall, and install a test certificate. The virtual machines are then ready for use in the deployment task.

YAML snippet

# PowerShell on target machines
# Execute PowerShell scripts on remote machines using PSSession and Invoke-Command for remoting
- task: PowerShellOnTargetMachines@3
    #userName: # Optional
    #userPassword: # Optional
    #scriptType: 'Inline' # Optional. Options: filePath, inline
    #scriptPath: # Required when scriptType == FilePath
    #inlineScript: '# Write your powershell commands here.Write-Output Hello World' # Required when scriptType == Inline
    #scriptArguments: # Optional
    #initializationScript: # Optional
    #sessionVariables: # Optional
    #communicationProtocol: 'Https' # Optional. Options: http, https
    #authenticationMechanism: 'Default' # Optional. Options: default, credssp
    #newPsSessionOptionArguments: '-SkipCACheck -IdleTimeout 7200000 -OperationTimeout 0 -OutputBufferingMode Block' # Optional
    #errorActionPreference: 'stop' # Optional. Options: stop, continue, silentlyContinue
    #failOnStderr: false # Optional
    #ignoreLASTEXITCODE: false # Optional
    #workingDirectory: # Optional
    #runPowershellInParallel: true # Optional


Argument Description
Machines A comma-separated list of machine FQDNs or IP addresses, optionally including the port number. Can be:
- The name of an Azure Resource Group.
- A comma-delimited list of machine names. Example: dbserver.fabrikam.com,dbserver_int.fabrikam.com:5986,192.168.34:5986
- An output variable from a previous task.
If you do not specify a port, the default WinRM port is used. This depends on the protocol you have configured: for WinRM 2.0, the default HTTP port is 5985 and the default HTTPS port is 5986.
Admin Login The username of either a domain or a local administrative account on the target host(s).
- Formats such as username, domain\username, machine-name\username, and .\username are supported.
- UPN formats such as username@domain.com and built-in system accounts such as NT Authority\System are not supported.
Password The password for the administrative account specified above. Consider using a secret variable global to the build or release pipeline to hide the password. Example: $(passwordVariable)
Protocol The protocol that will be used to connect to the target host, either HTTP or HTTPS.
Test Certificate If you choose the HTTPS option, set this checkbox to skip validating the authenticity of the machine's certificate by a trusted certification authority.
Deployment - PowerShell Script The location of the PowerShell script on the target machine. Can include environment variables such as $env:windir and $env:systemroot Example: C:\FabrikamFibre\Web\deploy.ps1
Deployment - Script Arguments The arguments required by the script, if any. Example: -applicationPath $(applicationPath) -username $(vmusername) -password $(vmpassword)
Deployment - Initialization Script The location on the target machine(s) of the data script used by PowerShell-DSC. It is recommended to use arguments instead of an initialization script.
Deployment - Session Variables Used to set up the session variables for the PowerShell scripts. A comma-separated list such as $varx=valuex, $vary=valuey Most commonly used for backward compatibility with earlier versions of the release service. It is recommended to use arguments instead of session variables.
Advanced - Run PowerShell in Parallel Set this option to execute the PowerShell scripts in parallel on all the target machines
Advanced - Select Machines By Depending on how you want to specify the machines in the group when using the Filter Criteria parameter, choose Machine Names or Tags.
Advanced - Filter Criteria Optional. A list of machine names or tag names that identifies the machines that the task will target. The filter criteria can be:
- The name of an Azure Resource Group.
- An output variable from a previous task.
- A comma-delimited list of tag names or machine names.
Format when using machine names is a comma-separated list of the machine FQDNs or IP addresses.
Specify tag names for a filter as {TagName}:{Value} Example: Role:DB;OS:Win8.1
Control options See Control options

Version 3.x of the task includes the Inline script setting where you can enter your PowerShell script code.

Open source

This task is open source on GitHub. Feedback and contributions are welcome.

Q & A

Do I need an agent?

You need at least one agent to run your build or release. Get an agent for Linux, macOS, or Windows.

I'm having problems. How can I troubleshoot them?

See Troubleshoot Build and Release.

I can't select a default agent pool and I can't queue my build or release. How do I fix this?

See Agent pools.

I use TFS on-premises and I don't see some of these features. Why not?

Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.