ARM Templates to Bicep Migration Guide: Decompile, Manual Adjustment, Phased Migration, and What-If

Migrating from Azure's traditional IaC format, ARM templates, to its successor Bicep is already the de facto standard for new projects. This article lays out a practical guide for migrating existing ARM assets to Bicep in phases — focused on using az bicep decompile, applying manual adjustments, following a phased migration roadmap, and verifying with What-If.

Why Migrate to Bicep

Microsoft positions Bicep as the recommended IaC tool for Azure, so new projects should default to Bicep. Existing ARM assets are best migrated gradually (no big-bang rewrite needed).

How to Use az bicep decompile

Command to automatically convert existing ARM JSON to Bicep:

az bicep decompile --file template.json

The output is saved as a template.bicep file.

Post-conversion Verification Steps

1. Review warnings: BCP warnings indicate complex expressions or custom functions that need manual adjustment
2. Re-transpile and diff: converts back to ARM JSON; diff it against the original ARM JSON (they should match) az bicep build
3. What-If verification: az deployment group what-if previews the apply result and lets you verify there are no unexpected changes

Even for simpler templates, 80-90% conversion is automatic, with the remaining 10-20% requiring manual adjustment — that's the realistic pattern.

Cases That Require Manual Adjustment

Common cases that Bicep decompile cannot fully automate:

1. Replace ARM variables with Bicep var declarations (hand-optimize complex expressions)
2. Refactor copy loops into Bicep for loops (more readable)
3. Break nested templates into Bicep Modules (better reusability)
4. Replace user-defined functions with Bicep's userDefinedFunction (added in Bicep 2024)
5. Adjust symbolic names: replace ARM's resourceId function with Bicep resource symbol references
6. Optimize conditional resources to Bicep's if syntax
7. Add type annotations to outputs

Example: ARM copy loop → Bicep for loop

ARM (Before)

{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2023-01-01",
  "name": "[concat('stg', copyIndex())]",
  "copy": {
    "name": "storageLoop",
    "count": 3
  },
  ...
}

Bicep (After)

resource storage 'Microsoft.Storage/storageAccounts@2023-01-01' = [for i in range(0, 3): {
  name: 'stg${i}'
  ...
}]

Recommended Phased Migration Steps

Big-bang migration (converting everything at once) is not recommended. A phased approach is the standard.

Microsoft itself accepts continued use of existing ARM, so there's no need to force a full rewrite. Set the pace based on your team's Bicep proficiency and capacity.

Refactoring for Modularization

Refactor ARM nested templates and linked templates into Bicep Modules.

Recommended Directory Structure

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

Key Technologies

• Customize Azure Verified Modules (AVM) — Microsoft's officially verified Modules
• Publish and version-manage Modules through an internal Bicep Registry backed by Azure Container Registry
• Improve type safety with Bicep 2024 user-defined types
• Visualize dependencies with Bicep Visualizer (VS Code extension)

What-If Deployment Verification

Running What-If before any production deployment is essentially mandatory. In Bicep migration projects, the critical step is verifying with What-If that the new Bicep deployment matches the original ARM deployment.

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

Output Categories

• + Create: new resource
• - Delete: deletion
• ~ Modify: modification (with diff)
• = NoChange: no change
• * Deploy: deploy only (idempotent)

The modern best practice is to wire What-If into the CI/CD pipeline and run it automatically during pull request reviews.

Bicep Linter

az bicep lint runs static analysis on Bicep code.

Key Rules

• no-hardcoded-location: parameterize location instead of hardcoding it
• no-unused-parameters / no-unused-variables: detect unused elements
• no-loc-expr-outside-params: keep location expressions in parameters
• prefer-interpolation: prefer string interpolation over concat
• explicit-values-for-loc-params: require explicit parameter defaults
• protect-commandtoexecute-secrets: prevent secret exposure on the command line

Project-specific rules are configurable via bicepconfig.json. Running Lint in your CI/CD pipeline keeps code quality high. The VS Code Bicep extension surfaces Lint results in real time, giving developers instant feedback as they code.

CI/CD Pipeline Integration

Standard CI/CD pipeline pattern after Bicep migration:

1. Lint: az bicep lint
2. Build: az bicep build (generate ARM JSON, validation)
3. What-If: az deployment group what-if
4. Manual Approval (production environment)
5. Deploy: az deployment group create

See the Bicep tutorial for the full CI/CD integration pattern.

Migration Best Practices

1. Phased migration: avoid big-bang conversion and prioritize
2. Default new development to Bicep; migrate existing ARM gradually
3. az bicep decompile for auto-conversion, then manual adjustment
4. Optimize to idiomatic Bicep using symbolic names, for loops, and modularization
5. Always verify conversion results with What-If
6. Automate Lint / Build / What-If in the CI/CD pipeline
7. Leverage Azure Verified Modules (AVM)
8. Centrally manage Modules through an internal Bicep Registry
9. Use the VS Code Bicep extension for real-time development support
10. Spread Bicep skills through regular team study sessions

Related Certifications

• AZ-400 (DevOps Engineer Expert): Domain 3 covers Bicep integration in CI/CD pipelines in depth — the flagship certification for this area
• AZ-104 (Administrator): Domain 1 covers Bicep / ARM fundamentals
• AZ-204 (Developer Associate): IaC from the developer perspective
• AZ-305 (Solutions Architect Expert): IaC strategy selection from the architect perspective

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 sponsorship with Microsoft. Microsoft and Azure are trademarks of the Microsoft group of companies. Information is based on official public materials as of May 24, 2026. Always check the official pages for the latest information.