Bicep Module Registry

A module registry is a shared library for Bicep modules. Teams publish a module once and every project pulls it from the registry by name and version. Copying module files between repositories leads to outdated duplicates, and a registry ends that habit.

Picture a public library. An author writes a book once, the library stores it, and thousands of readers borrow the same copy. A new edition gets a new version number, and readers choose which edition to borrow.

How the Registry Flow Works

  Author                     Azure Container Registry            Consumers
 ┌──────────────┐  publish   ┌─────────────────────────┐  restore  ┌─────────────┐
 │ storage.bicep│ ─────────► │ bicep/modules/storage   │ ────────► │ Project A   │
 └──────────────┘            │   v1   v2   v3          │ ────────► │ Project B   │
                             └─────────────────────────┘           └─────────────┘

Bicep stores modules in an Azure Container Registry (ACR). The registry holds each version as a separate, numbered package.

Publish a Module

The az bicep publish command uploads a file. The target address starts with br:, which stands for Bicep registry.

az bicep publish \
  --file storage.bicep \
  --target br:myregistry.azurecr.io/bicep/modules/storage:v1

The account used for publishing needs permission to push to the registry.

Use a Module from the Registry

A consumer references the registry address where a local file path would normally appear.

module storage 'br:myregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storageName: 'stshopdata001'
    location: 'eastus'
  }
}

Shorten Addresses with Aliases

Long registry paths are tiring to type. A bicepconfig.json file defines a short alias.

{
  "moduleAliases": {
    "br": {
      "myorg": {
        "registry": "myregistry.azurecr.io",
        "modulePath": "bicep/modules"
      }
    }
  }
}

With the alias in place, the module line shrinks.

module storage 'br/myorg:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storageName: 'stshopdata001'
    location: 'eastus'
  }
}

Version Tags

Every publish carries a tag such as v1 or v2. Consumers pin one tag, so updates never surprise them. A new version reaches a project only when its owner edits the tag.

Practical Version Rules

Never overwrite a published tag. Publish a new tag for each change, and describe the change in the repository history.

Public Modules

Microsoft shares ready-made modules in a public registry under the br/public alias. Azure Verified Modules belong to this collection and cover many common resources. Check the module's documentation page for the current path and version before use.

// Pattern only: replace the path and version with values from the module page
module storage 'br/public:avm/res/storage/storage-account:<version>' = {
  name: 'storageDeploy'
  params: {
    name: 'stshopdata001'
  }
}

Restore Modules Locally

Bicep downloads registry modules into a local cache when it builds a file. The restore command fetches them ahead of time, which suits build servers that need predictable steps.

az bicep restore --file main.bicep

Why Teams Use a Registry

Central modules enforce company standards, such as required tags and approved network settings. A fix in one module reaches every project that upgrades its version tag. Security reviewers audit a single module instead of dozens of copies.

Summary

A Bicep module registry stores versioned modules in Azure Container Registry. Authors publish with az bicep publish, and consumers reference the br: address or a short alias from bicepconfig.json. Version tags protect projects from surprise changes, and public modules offer ready-made building blocks.