BicepDeploy@0 - Bicep Deploy v0 task

The Bicep Deploy task is used to deploy and manage Azure resources using Bicep files. Bicep is a domain-specific language (DSL) that uses declarative syntax to deploy Azure resources. This task supports both standard Azure deployments and Azure Deployment Stacks, providing a simplified and more maintainable way to manage your Azure infrastructure as code.

The task handles:

• Creating or updating Azure resources using Bicep templates
• Validating Bicep templates before deployment
• Previewing changes with What-If operations
• Managing deployment stacks with lifecycle policies
• Deleting deployments and deployment stacks
• Installing and managing Bicep CLI versions automatically

The task supports:

• Native Bicep Support: Direct deployment from .bicep and .bicepparam files without requiring pre-compilation to ARM templates
• Deployment Stacks: Full support for Azure Deployment Stacks with deny settings, unmanaged resource policies, and lifecycle management
• Automatic Bicep CLI Management: Automatically downloads and caches the specified version of Bicep CLI
• Cross-Platform: Works with Windows, Linux, and macOS agents
• Multiple Deployment Scopes: Supports Resource Group, Subscription, Management Group, and Tenant scopes
• What-If Operations: Preview changes before applying them to your Azure environment
• Flexible Parameter Input: Support for inline YAML/JSON parameters and traditional parameter files
• Output Masking: Automatically mask sensitive outputs like secrets and connection strings

Syntax

# Bicep Deploy v0
# Deploy and Manage Azure Resources using Bicep Files.
- task: BicepDeploy@0
  inputs:
  # Azure Details
    type: 'deployment' # 'deployment' | 'deploymentStack'. Required. Execution type. Default: deployment.
    #operation: 'create' # 'create' | 'validate' | 'whatIf' | 'delete'. Required when type = deployment || (type = deploymentStack && operation != whatIf). Operation. Default: create.
    scope: 'resourceGroup' # 'resourceGroup' | 'subscription' | 'managementGroup' | 'tenant'. Required. Deployment scope. Default: resourceGroup.
    #name: # string. Deployment name. 
    azureResourceManagerConnection: # string. Alias: ConnectedServiceName. Required. Azure Resource Manager connection. 
    #subscriptionId: # string. Required when scope != tenant && scope != managementGroup. Subscription. 
    resourceGroupName: # string. Required when scope = resourceGroup. Resource group. 
    #location: # string. Optional. Use when scope != resourceGroup. Location. 
    #tenantId: # string. Required when scope = tenant. Tenant ID. 
    #managementGroupId: # string. Required when scope = managementGroup. Management group ID. 
  # Template
    #templateFile: # string. Template file. 
    #parametersFile: # string. Parameters file. 
    #parameters: # string. Override parameters. 
  # Deployment Stack Options
    #actionOnUnmanageResources: 'detach' # 'delete' | 'detach'. Required when type = deploymentStack. Action on unmanaged resources. Default: detach.
    #actionOnUnmanageResourceGroups: # 'delete' | 'detach'. Optional. Use when type = deploymentStack. Action on unmanaged resource groups. 
    #actionOnUnmanageManagementGroups: # 'delete' | 'detach'. Optional. Use when type = deploymentStack. Action on unmanaged management groups. 
    #denySettingsMode: 'none' # 'none' | 'denyDelete' | 'denyWriteAndDelete'. Required when type = deploymentStack. Deny settings mode. Default: none.
    #denySettingsExcludedActions: # string. Optional. Use when type = deploymentStack && denySettingsMode != none. Deny settings excluded actions. 
    #denySettingsExcludedPrincipals: # string. Optional. Use when type = deploymentStack && denySettingsMode != none. Deny settings excluded principals. 
    #denySettingsApplyToChildScopes: false # boolean. Optional. Use when type = deploymentStack && denySettingsMode != none. Apply deny settings to child scopes. Default: false.
    #bypassStackOutOfSyncError: false # boolean. Optional. Use when type = deploymentStack. Bypass stack out of sync error. Default: false.
  # Advanced
    #description: # string. Description. 
    #tags: # string. Optional. Use when type = deploymentStack. Tags. 
    #bicepVersion: # string. Bicep version. 
    #maskedOutputs: # string. Masked outputs. 
    #environment: 'azureCloud' # 'azureCloud' | 'azureChinaCloud' | 'azureGermanCloud' | 'azureUSGovernment'. Azure environment. Default: azureCloud.
    #whatIfExcludeChangeTypes: # string. Optional. Use when operation = whatIf. What-If exclude change types. 
    #validationLevel: # 'provider' | 'template' | 'providerNoRbac'. Optional. Use when type = deployment && (operation = validate || operation = whatIf). Validation level.

Inputs

type - Execution type
string. Required. Allowed values: deployment, deploymentStack (Deployment Stack). Default value: deployment.

Specifies the execution type: deployment or deploymentStack.

operation - Operation
string. Required when type = deployment || (type = deploymentStack && operation != whatIf). Allowed values: create (Create or update), validate, whatIf (What-If (preview changes)), delete. Default value: create.

Specifies the operation to perform. Deployment supports: create, validate, whatIf. Deployment Stack supports: create, validate, delete.

scope - Deployment scope
string. Required. Allowed values: resourceGroup (Resource Group), subscription, managementGroup (Management Group), tenant. Default value: resourceGroup.

Specifies the scope at which resources are deployed.

name - Deployment name
string.

Specifies the name of the deployment or deployment stack. If not provided, a default name will be generated.

azureResourceManagerConnection - Azure Resource Manager connection
Input alias: ConnectedServiceName. string. Required.

Select the Azure Resource Manager service connection.

subscriptionId - Subscription
string. Required when scope != tenant && scope != managementGroup.

Select the Azure subscription. Required if scope is subscription or resourceGroup.

resourceGroupName - Resource group
string. Required when scope = resourceGroup.

Provide the name of the resource group.

location - Location
string. Optional. Use when scope != resourceGroup.

Location to store deployment metadata. Required for subscription, managementGroup, and tenant scopes.

tenantId - Tenant ID
string. Required when scope = tenant.

Specifies the tenant ID. Required if scope is tenant.

managementGroupId - Management group ID
string. Required when scope = managementGroup.

Specifies the management group ID. Required if scope is managementGroup.

templateFile - Template file
string.

Specify the path to the Bicep template file (.bicep).

parametersFile - Parameters file
string.

Specify the path to the parameters file (.json or .bicepparam).

parameters - Override parameters
string.

Specify inline parameters as a JSON or YAML object. Example: {"param1": "value1", "param2": "value2"}.

actionOnUnmanageResources - Action on unmanaged resources
string. Required when type = deploymentStack. Allowed values: delete, detach. Default value: detach.

Specifies the action to take on resources not defined in the template.

actionOnUnmanageResourceGroups - Action on unmanaged resource groups
string. Optional. Use when type = deploymentStack. Allowed values: delete, detach.

Specifies the action to take on resource groups not defined in the template.

actionOnUnmanageManagementGroups - Action on unmanaged management groups
string. Optional. Use when type = deploymentStack. Allowed values: delete, detach.

Specifies the action to take on management groups not defined in the template.

denySettingsMode - Deny settings mode
string. Required when type = deploymentStack. Allowed values: none, denyDelete (Deny Delete), denyWriteAndDelete (Deny Write and Delete). Default value: none.

Specifies the mode of the deny settings to prevent unauthorized changes.

denySettingsExcludedActions - Deny settings excluded actions
string. Optional. Use when type = deploymentStack && denySettingsMode != none.

Comma-separated list of actions to exclude from deny settings.

denySettingsExcludedPrincipals - Deny settings excluded principals
string. Optional. Use when type = deploymentStack && denySettingsMode != none.

Comma-separated list of principal IDs to exclude from deny settings.

denySettingsApplyToChildScopes - Apply deny settings to child scopes
boolean. Optional. Use when type = deploymentStack && denySettingsMode != none. Default value: false.

When enabled, deny settings also apply to child scopes of managed resources.

bypassStackOutOfSyncError - Bypass stack out of sync error
boolean. Optional. Use when type = deploymentStack. Default value: false.

Bypass errors when the deployment stack is out of sync.

description - Description
string.

Description for the deployment or deployment stack.

tags - Tags
string. Optional. Use when type = deploymentStack.

Tags as JSON or YAML object. Example: {"Environment": "Development", "Owner": "TeamName"}.

bicepVersion - Bicep version
string.

Specify the version of Bicep to use (e.g., '0.38.5'). If not provided, the latest version will be used.

maskedOutputs - Masked outputs
string.

Comma-separated list of output names to mask values for (e.g., secrets).

environment - Azure environment
string. Allowed values: azureCloud (Azure Cloud), azureChinaCloud (Azure China Cloud), azureGermanCloud (Azure German Cloud), azureUSGovernment (Azure US Government). Default value: azureCloud.

Specifies the Azure environment to use.

whatIfExcludeChangeTypes - What-If exclude change types
string. Optional. Use when operation = whatIf.

Comma-separated list of change types to exclude from What-If operation (e.g., noChange, ignore).

validationLevel - Validation level
string. Optional. Use when type = deployment && (operation = validate || operation = whatIf). Allowed values: provider, template, providerNoRbac (Provider (No RBAC)).

Validation level for deployment operations.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

Prerequisites

Azure Subscription

To deploy to Azure, an Azure subscription must be linked to Azure Pipelines using a service connection:

1. Navigate to Project Settings → Service connections
2. Create a new service connection of type Azure Resource Manager
3. Choose authentication method:
   • Service Principal (automatic) - Recommended for most scenarios
   • Service Principal (manual) - For advanced configurations
   • Managed Identity - For Azure-hosted agents with managed identities
   • Workload Identity Federation - For enhanced security without secrets

For troubleshooting service connections, refer to the Azure RM endpoint documentation.

Agent Requirements

• Minimum Agent Version: 2.144.0
• Supported OS: Windows, Linux, macOS
• Node.js: Node.js 20 or higher (included in modern hosted agents)
• Bicep CLI: Automatically installed by the task (no manual installation required)

Deployment Outputs

The task automatically creates pipeline variables for all outputs defined in your Bicep template. These variables can be used in subsequent tasks.

• Defining Outputs in Bicep
• How Outputs Become Available
• Accessing Outputs in PowerShell
• Accessing Outputs in Bash

Defining Outputs in Bicep

Outputs are defined in the Bicep template using the output keyword. For example:

output storageAccountName string = storageAccount.name
output webAppUrl string = webApp.properties.defaultHostName
output intOutput int = 42
output objectOutput object = {
  key1: 'value1'
  key2: 'value2'
}

For detailed guidance, refer to the Bicep Outputs documentation.

How Outputs Become Available

After the deployment completes successfully, all outputs are set as output variables for the task step. To reference them in subsequent tasks, give the BicepDeploy step a name and use the syntax $(stepName.outputName).

Accessing Outputs in PowerShell

- task: BicepDeploy@0
  name: deploy
  displayName: 'Deploy Infrastructure'
  inputs:
    azureResourceManagerConnection: 'Azure-Connection'
    subscriptionId: '$(subscriptionId)'
    resourceGroupName: 'my-resource-group'
    templateFile: 'infra/main.bicep'

- task: PowerShell@2
  displayName: 'Use Deployment Outputs'
  inputs:
    targetType: 'inline'
    script: |
      Write-Host "Storage Account Name: $(deploy.storageAccountName)"
      Write-Host "Web App URL: $(deploy.webAppUrl)"

Accessing Outputs in Bash

- task: BicepDeploy@0
  name: deploy
  displayName: 'Deploy Infrastructure'
  inputs:
    azureResourceManagerConnection: 'Azure-Connection'
    subscriptionId: '$(subscriptionId)'
    resourceGroupName: 'my-resource-group'
    templateFile: 'infra/main.bicep'

- task: Bash@3
  displayName: 'Use Deployment Outputs'
  inputs:
    targetType: 'inline'
    script: |
      echo "Storage Account Name: $(deploy.storageAccountName)"
      echo "Web App URL: $(deploy.webAppUrl)"

Examples

Example 1: Basic Deployment

- task: BicepDeploy@0
  displayName: 'Deploy Bicep Template'
  inputs:
    azureResourceManagerConnection: 'Azure-Connection'
    subscriptionId: '$(subscriptionId)'
    resourceGroupName: 'my-resource-group'
    templateFile: 'infra/main.bicep'
    parametersFile: 'infra/main.bicepparam'

Example 2: Deployment Stack

- task: BicepDeploy@0
  displayName: 'Deploy with Stack Protection'
  inputs:
    type: 'deploymentStack'
    operation: 'create'
    name: 'production-stack'
    azureResourceManagerConnection: 'Azure-Connection'
    subscriptionId: '$(subscriptionId)'
    resourceGroupName: 'production-rg'
    templateFile: 'infra/main.bicep'
    parametersFile: 'infra/production.bicepparam'
    actionOnUnmanageResources: 'delete'
    denySettingsMode: 'denyWriteAndDelete'

Example 3: Subscription-Level Deployment

- task: BicepDeploy@0
  displayName: 'Deploy Subscription Resources'
  inputs:
    scope: 'subscription'
    azureResourceManagerConnection: 'Azure-Connection'
    subscriptionId: '$(subscriptionId)'
    location: 'eastus'
    templateFile: 'infra/subscription.bicep'
    parametersFile: 'infra/subscription.bicepparam'

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	2.144.0 or greater
Task category	Deploy