Azure PowerShell task

Azure Pipelines

Use this task to run a PowerShell script within an Azure environment. The Azure context is authenticated with the provided Azure Resource Manager service connection.

YAML snippet

# Azure PowerShell
# Run a PowerShell script within an Azure environment
- task: AzurePowerShell@5
  inputs:
    #azureSubscription: Required. Name of Azure Resource Manager service connection
    #scriptType: 'FilePath' # Optional. Options: filePath, inlineScript
    #scriptPath: # Optional
    #inline: '# You can write your Azure PowerShell scripts inline here. # You can also pass predefined and custom variables to this script using arguments' # Optional
    #scriptArguments: # Optional
    #errorActionPreference: 'stop' # Optional. Options: stop, continue, silentlyContinue
    #failOnStandardError: false # Optional
    #azurePowerShellVersion: 'OtherVersion' # Required. Options: latestVersion, otherVersion
    #preferredAzurePowerShellVersion: # Required when azurePowerShellVersion == OtherVersion
    #pwsh: true # Optional. If true, then will use PowerShell Core pwsh.exe

Arguments

Argument Description
ConnectedServiceNameARM
Azure Subscription		 (Required) Name of an Azure Resource Manager service connection for authentication.
Argument alias: azureSubscription
ScriptType
Script Type		 (Optional) Type of the script: filePath or inlineScript
Default value: FilePath
ScriptPath
Script Path		 (Optional) Path of the script. Should be fully qualified path or relative to the default working directory.
Inline
Inline Script		 (Optional) Enter the script to execute.
Default value:
# You can write your Azure PowerShell scripts inline here.
ScriptArguments
Script Arguments		 (Optional) Additional parameters to pass to PowerShell. Can be either ordinal or named parameters. Not applicable for inline script option.
errorActionPreference
ErrorActionPreference		 (Optional) Select the value of the ErrorActionPreference variable for executing the script.
Default value: stop
FailOnStandardError
Fail on Standard Error		 (Optional) If this is true, this task will fail if any errors are written to the error pipeline, or if any data is written to the Standard Error stream.
Default value: false
TargetAzurePs
Azure PowerShell Version		 (Required) In case of Microsoft-hosted agents, the supported Azure PowerShell version. To pick the latest version available on the agent, select Latest installed version.
For self-hosted agents, you can specify preferred version of Azure PowerShell using "Specify version"
Default value: OtherVersion
Argument alias: azurePowerShellVersion
CustomTargetAzurePs
preferredAzurePowerShellVersion		 (Required when TargetAzurePs = OtherVersion)
Preferred Azure PowerShell Version needs to be a proper semantic version. For example, 1.2.3. Regex like 2.*,2.3.* is not supported.
Argument alias: preferredAzurePowerShellVersion
pwsh
Use PowerShell Core		 (Optional) If this is true, on Windows, the task will use pwsh.exe from your PATH instead of powershell.exe.
workingDirectory
Working Directory		 (Optional) Working directory where the script is run.

Samples

- task: AzurePowerShell@5
  inputs:
    azureSubscription: my-arm-service-connection
    scriptType: filePath
    scriptPath: $(Build.SourcesDirectory)\myscript.ps1
    scriptArguments:
      -Arg1 val1 `
      -Arg2 val2 `
      -Arg3 val3
    azurePowerShellVersion: latestVersion
    pwsh: true

Troubleshooting

Script worked locally, but failed in the pipeline

This typically occurs when the service connection used in the pipeline has insufficient permissions to run the script. Locally, the script runs with your credentials and would succeed as you may have the required access.

To resolve this issue, ensure the service principle/ authentication credentials have the required permissions. For more information, see Use Role-Based Access Control to manage access to your Azure subscription resources.

Error: Could not find the modules: '<module name>' with Version: '<version>'. If the module was recently installed, retry after restarting the Azure Pipelines task agent

Azure PowerShell task uses Azure/AzureRM/Az PowerShell Module to interact with Azure Subscription. This issue occurs when the PowerShell module is not available on the Hosted Agent. Hence, for a particular task version, Preferred Azure PowerShell version must be specified in the Azure PowerShell version options from the list of available versions. The installed software can be found in the Software table in Microsoft-hosted agents.

Service Connection Issues

To troubleshoot issues related to service connections, see Service Connection troubleshooting.

Open source

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