Azure Bicep Tutorial: Syntax, Modules, What-If, and CI/CD Integration

Bicep is a declarative IaC DSL developed by Microsoft as the successor to Azure Resource Manager (ARM) templates. It went GA in 2021 and has rapidly become Microsoft Azure's official recommended IaC tool. This article walks through Bicep's core syntax, modularization, What-If deployments, CI/CD integration, and migration from ARM.

Why Bicep?

Key advantages of Bicep:

• Dramatically more concise and readable syntax than ARM JSON
• IntelliSense and type checking (via VS Code extension)
• Modularization support (ideal for large IaC)
• Immediate support for the latest Azure features (including preview features)
• No state management required (ARM handles it automatically)
• Free
• Automatic transpilation to ARM JSON (Bicep -> ARM JSON)

As of 2026, Bicep is the de facto standard for new Azure projects; ARM JSON is reserved for maintaining existing templates rather than new development.

Basic Syntax

Bicep uses declarative syntax. The key elements are:

• param: parameter declaration with type, default value, and allowed values
• var: variables and computed expressions
• resource: Azure resource definition with apiVersion
• module: invoke and reuse child templates
• output: export values to other templates
• targetScope: subscription / managementGroup / tenant scope

Simple Storage Account example

param storageAccountName string
param location string = resourceGroup().location

resource storage 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: {
    accessTier: 'Hot'
    allowBlobPublicAccess: false
    minimumTlsVersion: 'TLS1_2'
  }
}

output storageId string = storage.id
output storageEndpoint string = storage.properties.primaryEndpoints.blob

Type System

Bicep has a type system and types are specified explicitly.

• string: string
• int: integer
• bool: boolean
• array: array
• object: object
• Custom type (added in 2024): type myType = { name: string, age: int }

Modularization

Always modularize large IaC.

Recommended Directory Structure

infra/
├── main.bicep              # Entry point
├── main.parameters.json    # Environment-specific parameters
├── modules/
│   ├── network.bicep       # VNet / NSG / Subnet
│   ├── storage.bicep       # Storage Account / Container
│   ├── compute.bicep       # VM / App Service / AKS
│   └── identity.bicep      # Managed Identity / Key Vault
└── README.md

Module Invocation Example

module network 'modules/network.bicep' = {
  name: 'networkDeploy'
  params: {
    vnetName: vnetName
    addressPrefix: '10.0.0.0/16'
    location: location
  }
}

module compute 'modules/compute.bicep' = {
  name: 'computeDeploy'
  params: {
    vmName: vmName
    subnetId: network.outputs.appSubnetId
  }
  dependsOn: [
    network
  ]
}

Conditional Deployment and Loops

Conditional Deployment

param environment string

resource backup 'Microsoft.RecoveryServices/vaults@2023-01-01' = if (environment == 'prod') {
  name: 'rsv-prod'
  location: location
  sku: { name: 'Standard' }
}

Loops (for iteration)

param storageAccountNames array = [
  'stgapp001'
  'stgapp002'
  'stgapp003'
]

resource storageAccounts 'Microsoft.Storage/storageAccounts@2023-01-01' = [for name in storageAccountNames: {
  name: name
  location: location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
}]

What-If Deployment

What-If deployment previews what a Bicep / ARM template would change before actually deploying it. It is a mandatory step before production deployments.

Command

az deployment group what-if \
  --resource-group myRG \
  --template-file main.bicep \
  --parameters main.parameters.json

Output Categories

• + Create: newly created
• - Delete: deleted
• ~ Modify: modified (diff shown)
• = NoChange: unchanged
• * Deploy: deploy only (idempotent)

The modern best practice is to wire What-If into the CI/CD pipeline and run it automatically during the Pull Request review phase.

Bicep vs Terraform

CI/CD Integration

GitHub Actions pattern

name: Deploy Bicep
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: What-If
        uses: azure/CLI@v2
        with:
          inlineScript: |
            az deployment group what-if \
              --resource-group myRG \
              --template-file infra/main.bicep
      - name: Deploy
        uses: azure/arm-deploy@v2
        with:
          resourceGroupName: myRG
          template: infra/main.bicep
          parameters: infra/main.parameters.json

Standard pipeline stages: Lint -> Build -> What-If -> Manual Approval (Production) -> Deploy. See the Azure Pipelines YAML complete guide for details.

Migrating from ARM Templates

Automatic conversion tool for existing ARM JSON -> Bicep:

az bicep decompile --file template.json

This automatically converts ARM JSON into a Bicep file. The conversion is not perfect; cases that require manual adjustment include:

• Translating complex expressions and functions to Bicep syntax
• Optimizing Conditional / Loop syntax
• Splitting non-modularized templates into modules
• Publishing to the Public Registry or an internal Registry

Realistic migration strategy: new = Bicep, existing = convert only when needed -- a hybrid approach is recommended. Microsoft explicitly supports continued use of existing ARM templates, so a forced big-bang migration is not required.

Best Practices

1. Always modularize (per feature in a modules/ directory)
2. Environment-specific parameters (dev.parameters.json, prod.parameters.json)
3. Always run What-If before production deploys
4. Run static analysis with az bicep lint
5. Use Workload Identity Federation for CI/CD auth (no secrets required)
6. Follow resource naming conventions (CAF: Cloud Adoption Framework recommended patterns)
7. Apply tags (Environment, Owner, CostCenter, Project)
8. Reference Key Vault for secret parameters (@secure() decorator)
9. Leverage AVM (Azure Verified Modules) (Microsoft's official verified modules)
10. Visualize dependencies with Bicep Visualizer (VS Code extension)

Related Certifications

• AZ-104 (Administrator): Bicep / ARM fundamentals.
• AZ-204 (Developer Associate): IaC usage from a developer perspective.
• AZ-400 (DevOps Engineer Expert): Domain 3 covers Bicep integration in CI/CD pipelines (highest weight).
• AZ-305 (Solutions Architect Expert): IaC strategy from an architect perspective.
• AZ-120 (SAP on Azure): Automated Bicep deployment for ACSS.

Frequently Asked Questions

Technical information in this article is based on the Azure Bicep Documentation. This article is not an official Microsoft Corporation product and has no affiliation or endorsement relationship. Microsoft and Azure are trademarks of the Microsoft group of companies. Terraform is a trademark of HashiCorp. Information is based on official public materials as of May 24, 2026. Always verify the latest information on official pages.