Bicep Contribution Guide

Important

While this page describes and summarizes important aspects of contributing to AVM, it may not reference All of the shared and language specific requirements.

Therefore, this contribution guide MUST be used in conjunction with the Bicep specifications. ALL AVM modules (Resource and Pattern modules) MUST meet the respective requirements described in these specifications!

Summary

This section lists AVM’s Bicep-specific contribution guidance.

Subsections of Bicep Modules

Prerequisites

You need a GitHub account. Microsoft FTEs must use a personal GitHub account linked to their Microsoft corporate identity and join the Azure organization. External contributors can use a fork without joining the organization.

Before you start contributing to the AVM, it is highly recommended that you complete the following Microsoft Learn paths, modules & courses:

Bicep

Git

Tooling

Required Tooling

To contribute to this project the following tooling is required:

  • Git

    If just installed, set your Git name and email:

    git config --global user.name "John Doe"
    git config --global user.email "johndoe@example.com"
  • PowerShell 7.4 or later

  • Avm.Authoring, installed from Microsoft Artifact Registry (MAR). PowerShell 7.4 or later and Microsoft.PowerShell.PSResourceGet 1.2.0 or later are required. If needed, install the latter from PowerShell Gallery and restart PowerShell:

    Install-PSResource -Name Microsoft.PowerShell.PSResourceGet `
      -Version 1.2.0 `
      -Repository PSGallery `
      -Scope CurrentUser

    Register MAR once, then install the module:

    Import-Module Microsoft.PowerShell.PSResourceGet -MinimumVersion 1.2.0
    Register-PSResourceRepository -Name MAR `
      -Uri 'https://mcr.microsoft.com' `
      -ApiVersion ContainerRegistry `
      -Trusted
    Install-PSResource -Name avm.authoring `
      -Repository MAR `
      -Scope CurrentUser
    Import-Module Avm.Authoring
    avm doctor

    To update from MAR, repeat Install-PSResource -Name avm.authoring -Repository MAR -Scope CurrentUser -Reinstall and start a new PowerShell session. avm update uses PowerShell Gallery, not MAR. The module downloads and caches its pinned Bicep CLI on demand; no separate Bicep installation is needed for those commands. See initializing and updating Bicep module files.

  • Visual Studio Code

The following tooling/extensions are recommended to assist you developing for the project:

Visual Studio Code Extensions

Desktop Tooling

  • GitHub Desktop
    • To enhance streamlined integration during interactions with upstream repositories, GitHub Desktop will automatically configure your local git repository to use the upstream repository as a remote.

Bicep Contribution Flow

This guide covers the end-to-end contribution flow for AVM Bicep modules. Whether you are a module owner or an external contributor, the core workflow is the same; the key differences are called out using tabs below.

Prerequisites

Follow the Bicep prerequisites to install Git, PowerShell, and Avm.Authoring. Review the Bicep specifications and composition guidance.

​

External contributors without upstream write access can contribute from a fork. You do not need to configure GitHub Actions, Azure credentials, or secrets in your fork for upstream PR checks.

Module owners and other Microsoft FTEs contribute through branches in the upstream Bicep registry repository, not forks. Module owners must obtain the AVM Module Contributors access package; see owner responsibilities.

Overview


---
config:
  nodeSpacing: 20
  rankSpacing: 20
  diagramPadding: 50
  padding: 5
  flowchart:
    wrappingWidth: 300
    padding: 5
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---

flowchart TD
  Z("1 - Fork [optional]")
    click Z "#1-fork-optional"
  A(2 - Branch)
    click A "#2-branch"
  B(3 - Implement your code change)
    click B "#3-implement-your-code-change"
  C(4 - Run avm pre-commit)
    click C "#4-run-avm-pre-commit"
  C2(5 - Run pr-check and test tiers locally)
    click C2 "#5-run-pr-check-and-test-tiers-locally"
  D(6 - Raise or Update PR)
    click D "#6-raise-or-update-pr"
  E("7 - Approve and monitor CI tests [owner]")
    click E "#7-approve-and-monitor-ci-tests"
  F{Tests passing?}
  G(8 - Review and merge PR)
    click G "#8-review-and-merge-pr"
  H(9 - Automated release)
    click H "#9-automated-release"
  Z --> A
  A --> B
  B --> C
  C --> C2
  C2 --> D
  D --> E
  E --> F
  F -->|no| B
  F -->|yes| G
  G --> H


1. Fork [optional]

​

Fork Azure/bicep-registry-modules on GitHub and clone your fork, or use the GitHub CLI:

gh repo fork Azure/bicep-registry-modules --clone
cd bicep-registry-modules

Keep your fork synchronized with upstream main before creating a branch.

Skip this step and clone the upstream repository:

git clone https://github.com/Azure/bicep-registry-modules.git
cd bicep-registry-modules

2. Branch

Create a branch from the latest upstream main in your upstream checkout or synchronized fork:

git checkout -b <your-branch-name>

3. Implement your code change

Follow the composition guidance and update the module’s source, changelog, and applicable tests. A new module requires an approved proposal before work starts.

Initialize a new module once

For an approved resource module, run this from the repository root, replacing the path with the approved module path:

$modulePath = 'avm/res/<provider>/<module>'
avm init `
  -Ecosystem bicep `
  -ModuleType resource `
  -Path $modulePath

Use the approved module type for a pattern or utility module. The command prompts for missing approved metadata in an interactive terminal and scaffolds missing source, metadata, version, changelog, and test files without overwriting existing files. For unattended use, provide required metadata with -InputObject. For an approved proposal without source, use the metadata-only process.

To initialize a child, set $childPath to its approved path and run:

$childPath = 'avm/res/<provider>/<module>/<child>'
avm init `
  -Ecosystem bicep `
  -ModuleType resource `
  -Path $childPath `
  -ChildModule

Children inherit root ownership; see the metadata rules and child publishing guide.

4. Run avm pre-commit

Update generated files after editing

Before regenerating an existing README with hand-written Notes, export its Notes if it has no README.notes.md sidecar. Do the same for each affected child README; the generator does not copy Notes from existing READMEs.

From the repository root, set the module path and run:

$modulePath = 'avm/res/<provider>/<module>'
avm pre-commit `
  -Ecosystem bicep `
  -Path $modulePath

This validates metadata, formats and checks Bicep, compiles main.json, and generates README.md for the module and its children. Review and commit the changes, and rerun after subsequent edits. Do not run it on a metadata-only proposal before its source exists. See Advanced Topics & FAQ for avm docs and existing Notes sections.

5. Run pr-check and test tiers locally

After committing generated changes, run the PR checks with a clean working tree:

avm pr-check `
  -Ecosystem bicep `
  -Path $modulePath

avm pr-check validates the module and checks generated-file drift; it does not replace the shared PR checks or run deployment tests.

The following test tiers are optional local checks and run separately from avm pr-check.

Unit testing

Run authored Pester unit tests, including child modules:

avm test unit `
  -Ecosystem bicep `
  -Path $modulePath `
  -Recurse

A missing unit suite is reported as skipped, not passed.

Integration testing

The optional integration tier uses Azure CLI to validate and preview deployments without deploying resources. Use an authorized test subscription and, for resource-group-scope tests, an existing test resource group:

avm test integration `
  -Ecosystem bicep `
  -Path $modulePath `
  -SubscriptionId '<test-subscription-id>' `
  -ResourceGroupName '<test-resource-group>' `
  -Location '<location>' `
  -Recurse

See the integration command reference for other deployment scopes and inputs.

Local e2e testing

To list available deployment tests without Azure access:

avm test e2e `
  -Ecosystem bicep `
  -Path $modulePath `
  -Recurse `
  -List

To run deployment tests locally, sign in to Azure PowerShell and Azure CLI with the same account, tenant, cloud, and selected test subscription. Use an explicitly authorized test subscription:

avm test e2e `
  -Ecosystem bicep `
  -Path $modulePath `
  -SubscriptionId '<test-subscription-id>' `
  -TenantId '<test-tenant-id>' `
  -Location '<location>' `
  -ResourceGroupPrefix 'avmtest' `
  -Recurse

Deployment tests can create, update, and remove Azure resources, incur costs, and register required providers or features. Additional inputs depend on the test and deployment scope; see the e2e command reference.

6. Raise or Update PR

Push your branch and open a PR targeting upstream main. Follow the PR template and provide a meaningful title and description. For a new module, link the PR on its proposal issue and notify its triager or @Azure/azure-verified-modules-tooling-contributors; after merge, update the issue with a Merged comment and notify them again.

​

Create the PR from your fork’s branch to main in Azure/bicep-registry-modules.

Create the PR from your upstream branch to main.

7. Approve and monitor CI tests

After the updated workflow is rolled out, PR validation and applicable unit and integration tests run automatically. Review their results and update your branch if checks fail. No fork workflow setup is required. If a test needs environment-specific inputs, coordinate custom CI parameters with maintainers.

Open a PR early and use these checks while iterating. When the contribution is ready for deployment tests, request an e2e label; delaying those tests avoids unnecessary cloud costs and runtime.

An authorized maintainer must apply at least one of these labels to a same-repository PR to run its automatic e2e tests:

  • PR: Run Required E2E Tests runs the applicable required scenarios for the module class. Resource modules require defaults and waf-aligned; pattern and utility modules require defaults only. A WAF-aligned scenario is optional for pattern and utility modules.
  • PR: Run All E2E Tests runs the required scenarios and all optional scenarios.

Every selected scenario must pass the single Report check status merge gate. Missing required scenarios produce a warning, but existing required scenarios cannot be ignored to bypass checks. Required scenario names and semantics are defined in BCPRMNFR1 and SNFR2. Manual dispatch is a separate operator path; merge queues are not supported.

​

Labels do not give a fork PR access to credentials. An authorized FTE must perform the release-branch handoff so the same-repository follow-up PR can run authenticated e2e tests and satisfy the merge gate.

For an upstream PR, apply the label for the required scenarios or the label that also includes optional scenarios. Keep a label on the PR for automatic e2e testing on subsequent updates.

Running e2e for external contributions

Immediately before the handoff, an FTE must review the source code, dependencies, and workflow changes for security at the exact current PR head. Review the new head again if it changes. Authenticate the GitHub CLI (gh) as an authorized FTE with upstream access, then run:

avm release-branch `
  --repository Azure/bicep-registry-modules `
  --pull-request 123

The command cannot verify which commit was reviewed. It captures the current head and stops if it changes during the handoff. It creates a release branch from main, retargets and merges the fork PR into that branch, opens a follow-up PR to main, and labels it PR: Run Required E2E Tests. An authorized maintainer may instead use PR: Run All E2E Tests to include optional scenarios. Restrict write access to the release branch and review any later changes before E2E testing or merging the follow-up PR. Use --whatif to preview; the command does not bypass repository protections.

If the handoff fails, inspect the fork PR and release branch before recovering manually; do not blindly rerun it. If E2E tests fail after a successful handoff, the original fork PR has been merged. Open a new fork PR containing the original changes and fixes, review its current head, and perform a new handoff. Inspect the existing follow-up PR and release branch before proceeding.

8. Review and merge PR

Address review feedback and request a re-review after updates. Authors cannot approve their own PRs.

​

Address review comments, update your branch, and request a re-review. An eligible repository team member merges the PR when required approvals and checks pass.

A new module requires AVM core team review before merging. For ordinary changes, any eligible BRM repository team member may approve and merge under repository rules. Changes to metadata.json require metadata code-owner review.

9. Automated release

After merge, the module release workflow runs on pushes to main and can also be started manually. It discovers pending releases, checks the changelog, and requests approval before creating scoped release tags. Module owners must verify both the release workflow and subsequent publication to the public Bicep registry; tag creation alone does not prove publication. Metadata-only changes must not trigger a module release.

Bicep Composition

Important

While this page describes and summarizes important aspects of the composition of AVM modules, it may not reference All of the shared and language specific requirements.

Therefore, this guide MUST be used in conjunction with the Bicep specifications. ALL AVM modules (Resource and Pattern modules) MUST meet the respective requirements described in these specifications!

Important

Before jumping on implementing your contribution, please review the AVM Module specifications, in particular the Bicep specification page, to make sure your contribution complies with the AVM module’s design and principles.

Directory and File Structure

Each Bicep AVM module of the Azure/bicep-registry-modules (BRM) repository must be implemented as per the structure described in BCPNFR23.

For an approved new module, run avm init from the root of the Bicep registry checkout. It creates the missing module and provider directories, metadata, Bicep source, version and changelog files, and root end-to-end test templates without overwriting existing files. For example, replace the path below with the approved resource module path:

$modulePath = 'avm/res/compute/<approved-module>'
avm init -Ecosystem bicep -ModuleType resource -Path $modulePath

Once you have implemented the source and tests, run avm pre-commit -Ecosystem bicep -Path $modulePath to build main.json and generate the README. See initializing and updating module files for the full local workflow. To register an approved proposal without creating main.bicep, follow the metadata-only proposal guide instead.

Code Styling

This section points to conventions to be followed when developing a Bicep template.

Casing

Use camelCasing as per BCPNFR8.

Input Parameters and Variables

Make sure to review all specifications of Category: Inputs/Outputs within the Bicep specification pages.

Tip

See examples in specifications SNFR14 and BCPNFR1.

Resources

Resources are primarily leveraged by resource modules to declare the primary resource of the main resource type deployed by the AVM module.

Make sure to review all specifications covering resource properties and usage.

Tip

See examples in specifications SFR1 and RMFR1.

Modules

Modules enable you to reuse code from a Bicep file in other Bicep files. As such, for resource modules they’re normally leveraged for deploying child resources (e.g., file services in a storage account), cross referenced resources (e.g., network interface in a virtual machine) or extension resources (e.g., role assignments in a key vault). Pattern modules, normally reuse resource modules combined together.

Make sure to review all specifications covering module properties and usage.

Tip

See examples in specifications BCPFR1 for resource modules and PMNFR2 for pattern modules.

Outputs

Make sure to review all specifications of Category: Inputs/Outputs within the Bicep specific pages.

Tip

See examples in specification RMFR7.

Interfaces

Note

This section is only relevant for contributions to resource modules.

To meet RMFR4 and RMFR5 AVM resource modules must leverage consistent interfaces for all the optional features/extension resources supported by the AVM module primary resource.

Please refer to the Bicep Interfaces page.
If the primary resource of the AVM resource module you are developing supports any of the listed features/extension resources, please follow the corresponding provided Bicep schema to develop them.

Deprecation

Breaking changes are sometimes not avoidable. The impact should be kept as low as possible. A recommendation is to deprecate parameters, instead of completely removing them for a couple of versions. The Semantic Versioning sections offers information about versioning AVM modules.

In case you need to deprecate an input parameter, this sample shows you how this can be achieved.

Note

Since all modules are versioned, nothing will change for existing deployments, as the parameter usage does not change for any existing versions.

Example-Scenario

An AVM module is modified, and the parameters will change, which breaks backward compatibility.

  • parameters are changing to a custom type
  • the parameter structure is changing
  • backward compatibility will be maintained

Existing input parameters used to be defined as follows (reducing the examples to the minimum):

// main.bicep:
param item object?

// main.test.bicep:
name: 'name'
item:
  {
    variant: 'Large'
    osType: 'Windows'
  }

Testing

Before you begin to modify anything, it is recommended to create a new test case (e.g. deprecated), in addition to the already existing tests, to make sure that the changes are not breaking backward compatibility until you decide to finally remove the deprecated parameters (see BCPRMNFR1 - Category: Testing - Expected Test Directories for more details about the requirements).

module testDeployment '../../../main.bicep' = [
  for iteration in ['init', 'idem']: {
    scope: resourceGroup
    name: '${uniqueString(deployment().name, resourceLocation)}-test-${serviceShort}-${iteration}'
    params: {
      name: '${namePrefix}${serviceShort}001'
      item: {
        variant: 'Large'
        osType: 'Linux'
      }
    }
  }
]

The test should include all previously used parameters to make sure they are covered before any changes to the new parameter layout are done.

Code Changes

The new parameter structure requires a change to the used parameters and moves them to a different location and looks like:

// main.bicep:
param item itemType?

type itemtype: {
  name: string // the name parameter did not change

  properties ={
    osType: 'Linux' | 'Windows'? // the new place for the osType

    variant: {
      size: string? // the new place for the variant size
    }?
  }

  // keep these for backward compatibility in the new type
  @description('Optional. Note: This is a deprecated property, please use the corresponding `properties.osType` instead.')
  osType: string? // the old parameter location

  @description('Optional. Note: This is a deprecated property, please use the corresponding `properties.variant.size` instead.')
  variant: string? // the old parameter location
}

The original parameter item is of type object and does not give the user any clue of what the syntax is and what is expected to be added to it. The tests could bring light into the darkness, but this is not ideal. In order to retain backward compatibility, the previously used parameters need to be added to the new type, as they would be invalid otherwise. Now that the new type is in place, some logic needs to be implemented to make sure the module can handle the different sources of data (new and old parameters).

resource <modulename> 'Microsoft.xy/yz@2024-01-01' = {
  name: name
  properties: {
    osType: item.?properties.?osType ?? item.?osType ?? 'Linux' // add a default here, if needed
    variant: {
      size: item.?properties.?variant.?size ?? item.?variant
    }
  }
}

By choosing this order for the Coalesce operator, the new format takes precedence over the old syntax. Also note the safe-dereference ensures that no null reference exception will occure if the property has optional parameters.

The tests can now be changed to adapt the new parameter structure for the new version of the module. They will not cover the old parameter structure anymore.

module testDeployment '../../../main.bicep' = [
  for iteration in ['init', 'idem']: {
    scope: resourceGroup
    name: '${uniqueString(deployment().name, resourceLocation)}-test-${serviceShort}-${iteration}'
    params: {
      name: '${namePrefix}${serviceShort}001'
      location: resourceLocation
      item:{
        osType: 'Linux'
        variant: {
          size: 'Large'
        }
      }
    }
  }
]

Summary

Changes to modules (resource or pattern) can bei implemented in two ways.

  1. Implement changes with backward compatibility

    In this scenario, you need to make sure that the code does not break backward compatibility by:

    • adding new parameters
    • marking other parameters as deprecated
    • create a test case for the old usage syntax
    • increase the minor version number of the module (0.x)
  2. Introduce breaking changes

    The easier way to introduce a new major version requires fewer steps:

    • adding new parameters
    • create a test case for the usage
    • increase the major version number of the module (x.0.0)
Note

Be aware that currently no module has been released as 1.0.0 (or beyond), which lets you implement breaking changes without increasing the major version.

Advanced Topics & FAQ

Custom CI parameters

Use GitHub Actions secrets or variables to supply environment-specific inputs to your main.test.bicep end-to-end tests, such as tenant-specific object IDs or credentials. This avoids hardcoding values specific to your local or centrally managed test environment. Never commit private values to test files.

These are additional template inputs, not Azure login credentials. Upstream CI uses OIDC with the avm-validation environment and its VALIDATE_CLIENT_ID, VALIDATE_TENANT_ID, and VALIDATE_SUBSCRIPTION_ID secrets.

Forks and upstream validation

Fork PRs cannot access upstream secrets or run credentialed E2E tests directly. When adding a required input, ask maintainers to configure the corresponding GitHub secret or variable in the upstream environment before merging your contribution. Share the parameter name and purpose, never its private value. An authorized FTE must perform the release-branch handoff for authenticated validation.

Setup

Declare the parameters in your main.test.bicep file and reference them as normal Bicep parameters. Keep an empty default for these string inputs so PSRule scans have a value for every parameter.

For example:

@description('Required. Credential supplied by the CI_MY_SECRET GitHub Actions secret.')
@secure()
param mySecret string = ''

@description('Optional. Non-sensitive label used by this test.')
param deploymentLabel string = ''

An authorized maintainer can add the corresponding values under Settings > Secrets and variables > Actions in the upstream repository, or under Settings > Environments > avm-validation for environment-scoped values:

GitHub Actions nameStore asTemplate parameterValue
CI_MY_SECRETSecretmySecretSet privately; do not put the value in source control or logs.
CI_DEPLOYMENT_LABELVariabledeploymentLabelFor example, the non-sensitive label avm-ci.

GitHub secret and variable names cannot contain hyphens. Prefer readable CI_ names for usual camelCase parameters; reserve CI__ for literal parameter names, including underscores.

With CI_, the CI strips the single prefix and removes all suffix underscores before matching. With CI__, it strips the double prefix and preserves suffix underscores. Both modes match actual declared test parameters case-insensitively and pass their canonical Bicep spelling. Only matching parameters are supplied.

These are alternative spellings; choose one name for each input:

GitHub Actions nameMatching template parameter
CI_ADMIN_MEMBERS_SECRETadminMembersSecret
CI_ADMINMEMBERSSECRETadminMembersSecret
CI__ADMIN_MEMBERS_SECRETadmin_members_secret, not adminMembersSecret
CI__ADMINMEMBERSSECRETadminMembersSecret
CI___NAME_name

Reserved name: CI_KEY_VAULT_NAME remains the existing vault selector and is excluded from template input mapping. To supply a test parameter named keyVaultName, use CI__KEYVAULTNAME.

String inputs, including secure strings, are used as supplied. For Boolean, integer, array, and object parameters (including secure objects), supply valid JSON matching the compiled template parameter type.

Protect sensitive inputs

Use GitHub secrets for private values, and variables only for clearly non-sensitive configuration. Keep @secure() on sensitive Bicep parameters. The CI converts secure strings to PowerShell SecureString values and parses secure objects into dictionaries, preserving the template’s ARM secureObject declaration. This also applies to inputs from GitHub variables. Neither @secure() nor these conversions make a GitHub variable’s stored value private.

How it works

Workflows use the resolved GitHub secrets and vars contexts. Both repository-scoped and environment-scoped values are supported; GitHub applies its own scope precedence within each context. Use the same GitHub spelling across scopes when overriding an input so GitHub can apply that scope precedence to the override.

After name resolution, values for the same template parameter are selected in this order:

CI_ secret > CI__ secret > CI_ variable > CI__ variable > CI- Key Vault secret.

Source priority comes first: a CI__ secret still beats a CI_ variable. Within one source category (secrets or variables), CI_ wins over CI__ when both resolve to the same parameter; for example, secret CI_FOO beats secret CI__FOO for foo.

Multiple aliases for the same parameter within a source category’s winning prefix remain ambiguous and fail. For example, secrets CI_ADMIN_MEMBERS_SECRET and CI_ADMINMEMBERSSECRET both resolve to adminMembersSecret through CI_; neither has priority over the other.

Names resolving to different declared parameters remain independent: CI_ADMIN_MEMBERS_SECRET supplies adminMembersSecret, while CI__ADMIN_MEMBERS_SECRET supplies admin_members_secret.

A configured empty winning value, including a CI_ value, still wins and does not trigger fallback to a lower-priority prefix or source.

The CI passes the resolved values through the PowerShell AdditionalParameters object to the applicable Test-Az*Deployment and New-Az*Deployment cmdlets. This is runtime deployment parameter injection, not source token substitution or a .bicepparam file mechanism.

Legacy Key Vault fallback

CI Key Vault support is deprecated

vars.CI_KEY_VAULT_NAME remains an optional fallback for existing setups. Using it emits a visible GitHub Actions deprecation warning, and support may be removed in a future release. Use GitHub Actions secrets or variables for new setups.

Existing setups can retain the CI_KEY_VAULT_NAME repository variable, the vault, and its CI--prefixed secrets. The legacy CI- suffix is matched literally and case-insensitively, unchanged by the GitHub naming rules. The CI identity still needs permission to list and read secrets, for example through the Key Vault Secrets User role. Matching Key Vault secrets are used only when no GitHub secret or variable supplies that parameter; keep the corresponding Bicep parameters secure.

Migrate existing inputs

  1. Inventory the CI- secrets used by your test parameters and identify every workflow that depends on the vault. Prefer the preview-only migration helper for this inventory.
  2. Map each source name to a readable GitHub CI_ name, or a CI__ name for literal underscores or a reserved-name conflict. For example, Key Vault secret CI-mySecret becomes GitHub secret CI_MY_SECRET, supplying mySecret.
  3. Copy each value privately to the intended repository or environment scope. Default to a GitHub secret; choose a variable only after confirming the value is non-sensitive. Coordinate corresponding upstream inputs with the maintainers.
  4. Confirm that all dependent workflows use the migrated inputs before removing CI_KEY_VAULT_NAME. Do not delete the vault or its secrets as part of this change without checking for other consumers.
Preview with the migration helper
Check workflow availability

The GitHub CI parameter support and migration helper were introduced in Azure/bicep-registry-modules#7339. Verify the implementation is available in your checkout and dependent workflows before applying a migration.

The Copy-CIKeyVaultSecretsToGitHub helper requires PowerShell 7.2 or later, an authenticated Az.KeyVault session, and the GitHub CLI authenticated to github.com. From a bicep-registry-modules checkout containing the helper, replace the placeholders and preview selected inputs:

. .\utilities\tools\Copy-CIKeyVaultSecretsToGitHub.ps1
Copy-CIKeyVaultSecretsToGitHub -VaultName '<vault-name>' -Repository '<owner>/<repo>' `
  -Environment 'avm-validation' `
  -SecretName 'CI-mySecret', 'CI-deploymentLabel' `
  -VariableName 'CI_DEPLOYMENT_LABEL'

For new entries, the helper generates readable names from camelCase and acronyms: CI-mySecret becomes CI_MY_SECRET, CI-deploymentLabel becomes CI_DEPLOYMENT_LABEL, and CI-managedHSMResourceId becomes CI_MANAGED_HSM_RESOURCE_ID. Literal underscores or reserved-name conflicts use CI__ spelling.

Without -Apply, the helper lists names and metadata only: it does not read secret values or change GitHub settings. -SecretName is a literal, case-insensitive allowlist of source CI- names; omitting it selects all CI- entries. -VariableName accepts either CI_ or CI__ aliases that resolve to selected source parameters explicitly confirmed as non-sensitive; all other values remain secrets. Prefer the planned readable output names, as in the example. Omit -Environment to target repository scope.

Review the preview and obtain explicit operator approval before adding -Apply to copy values. When selecting an existing destination entry of the same kind for a parameter, the helper also prefers CI_ over CI__. It skips the winning entry by default and reuses and overwrites only that entry when -Overwrite is explicitly specified. Any losing CI__ alias is left unchanged, not deleted. Ambiguity within the winning prefix and opposite-kind matches for the same parameter are blocked.

The helper never deletes entries and sends version-pinned values through standard input, not command arguments or files. Complete the workflow confirmation above before removing CI_KEY_VAULT_NAME.

Generated READMEs and Notes

To regenerate only the README from Bicep source and E2E examples, run:

avm docs `
  -Ecosystem bicep `
  -Path $modulePath

avm docs does not scaffold source files or compile main.json; use avm pre-commit for those tasks. For an existing hand-written ## Notes section without a README.notes.md sidecar, extract the Notes before regenerating:

avm docs export-notes -Path $modulePath
avm pre-commit `
  -Ecosystem bicep `
  -Path $modulePath

Run avm docs export-notes separately for each child README with authored Notes, using that child’s path. Commit the sidecars alongside regenerated READMEs. The generator does not copy Notes from existing READMEs; keep authored Notes in the sidecar and their images in the module’s src directory. Edit source descriptions and parameter decorators rather than generated README sections.

Module owner responsibilities

Follow the module owner responsibilities, team definitions, and Bicep specifications. Only Microsoft FTEs may be module owners. Each primary, secondary, and additional owner needs the AVM Module Contributors access package, managed through the shared @Azure/azure-verified-modules-module-contributors team.

Maintain approved handles in the root metadata.json owners array through the metadata review process. Reviewer routing uses those handles; it does not generate per-module CODEOWNERS entries. Monitor module issues and PRs, ensure compliance and timely reviews, and verify testing and publication.


Handover and adoption

For a handover, follow hot-swapping module owners: update root metadata in one change, obtain metadata code-owner approval, and ensure incoming owners have approved access. Do not remove shared access solely because one module changes owners. If no replacement is available, follow the orphaning process; to adopt an orphaned module, follow the adoption process.

Notifications

Configure GitHub notifications to receive team mentions and watched activity, and monitor bicep-registry-modules for issues and PRs affecting your modules. Microsoft FTEs can also consult the internal maintenance guidance.

Child Module Publishing

Child resources are resources that exist only within the scope of another resource. For example, a virtual network subnet cannot exist without a virtual network. The subnet is a child resource of the virtual network.

In the context of AVM, particularly AVM Bicep resource modules, child modules are modules deploying child resources. They are implemented within the scope of their corresponding parent resource modules. For example, the module avm/res/network/virtual-network/subnet deploys a virtual network subnet and is a child module of its parent virtual network module avm/res/network/virtual-network.

By default, child modules are not published to the public bicep registry independently from their parents. They need to be explicitly enabled for publishing to be directly referenced from the registry.

This page covers step-by-step guidelines to publish a bicep child module.

Important

The child module publishing process is currently in a pilot/preview phase. This means it may not be as smooth as the general module publishing.

The core team is currently working on additional automation, with the goal of improving efficiency in addressing child module publishing requests.

Note

Child module publishing currently only applies to resource modules.

Supporting child module publishing for other module categories, such as pattern and utility modules, is not planned at this time.

Quick guide

Use this section for a fast overview on how to publish a child module.
For a step-by-step explanation with detailed instructions, refer to the following sections.

  • Check prerequisites: Existing issue in AVM, assigned telemetry ID prefix, module registered in the MAR file.
  • Implement the required changes in a branch. Microsoft FTEs must use the upstream repository; external contributors may work in a fork:
    • Allowed list: Add the child module path to allowed-child-modules in the publishing allowed list if it is not already present.
    • Child module template: Ensure the child’s metadata.json contains its assigned telemetry prefix alongside main.bicep, then add the enableTelemetry parameter and avmTelemetry deployment.
    • Parent module template: In the main.bicep template of the child module direct parent, add a enableReferencedModulesTelemetry variable with a value of false, and pass it as the enableTelemetry value down to the child module deployment.
    • Version: Add the version.json file to the child module folder and set version to 0.1.
    • Changelog: Add a new CHANGELOG.md file to the child module folder and update the changelog of all its versioned parents with a new patch version, up to the top-level parent.
    • Generate module artifacts: Run avm pre-commit on the top-level parent module. It processes that module and its descendants, updating their compiled templates and READMEs. Test your changes and raise a PR.

Prerequisites

Before jumping into the implementation, make sure the following prerequisites are in place:

Bicep Child Module Proposal issue

Ensure there is an AVM issue open already, proposing the child module to be published. If not, please create one using the Bicep Child Module Proposal issue template.

Note

Please understand the difference between publishing an existing child module and extending a parent module with a not yet implemented child module functionality.

The Bicep Child Module Proposal issue primarily intends to cover the former, i.e. to publish a child module already existing in the BRM (Bicep Registry Modules) repository source code. However, the same issue allows also to request the development of the child module functionality, although the best way to address new functionality is to raise a feature request via the the AVM Module issue.

Telemetry ID prefix assigned

Follow the below steps to check the child module telemetry ID prefix.

Note

If the Bicep Child Module Proposal issue was just created, please allow a few days for the telemetry ID prefix to be assigned before reaching out.

Check telemetryIdPrefix in the child’s own metadata.json and keep it consistent with the child module source. Record only the assigned identifier through metadata review. Ownership is inherited from the root.

You can also look up the assigned prefix in the published index:

  1. Check the Bicep Resource Modules index, or the underlying module catalog JSON.
  2. Search for the child module name in the ModuleName field.
  3. Verify if the corresponding value exists in the TelemetryIdPrefix field. Note down the value as you will need it in the implementation phase.
  4. If not found, please reach out to the core team, mentioning the @Azure/azure-verified-modules-tooling-contributors via the Bicep Child Module Proposal issue.

If the identifier is missing or conflicts with the index, ask the core team to resolve it. Do not invent an identifier or copy the parent’s prefix.

Module registered in the MAR-file

Ensure that the child module is registered in the MAR file.
If not, please reach out to the core team, mentioning the @Azure/azure-verified-modules-tooling-contributors via the Bicep Child Module Proposal issue.

Metadata approval does not replace MAR registration or approval to publish the child module.

Note

The MAR-file can only be accessed by Microsoft FTEs. If you are missing access, please reach out to the parent module owner for help.

Implementation

The quickest way to get the child module published is to enable it yourself, contributing via a pull request to the BRM repository.

Note

Publishing a child module does not change the folder hierarchy of the parent and child modules. The child module remains in its existing location within the parent module’s folder structure. No files or folders need to be moved or reorganized.

Please follow the steps below:

  • Add the child module path to the allowed-child-modules array in the publishing allowed list, keeping alphabetical order. Validation requires a child module with a version.json file to be listed.

  • Update the child module main.bicep template to support telemetry, as per SFR4, SFR3 and BCPFR4

    • Add the enableTelemetry parameter with a default value of true. Place it as the last param declaration, immediately before the first var declaration.
      @description('Optional. Enable/Disable usage telemetry for module.')
      param enableTelemetry bool = true
    • Add the avmTelemetry deployment, referencing the template below. Ensure the child’s metadata.json exists alongside main.bicep before compiling and contains its assigned telemetryIdPrefix. Load only that property instead of hardcoding the prefix.
        var telemetryIdPrefix = loadJsonContent('metadata.json', 'telemetryIdPrefix')
      
        #disable-next-line no-deployments-resources
        resource avmTelemetry 'Microsoft.Resources/deployments@2025-04-01' = if (enableTelemetry) {
          name: '${telemetryIdPrefix}.${replace('-..--..-', '.', '-')}.${substring(uniqueString(deployment().name), 0, 4)}'
          properties: {
            mode: 'Incremental'
            template: {
              '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
              contentVersion: '1.0.0.0'
              resources: []
              outputs: {
                telemetry: {
                  type: 'String'
                  value: 'For more information, see https://aka.ms/avm/TelemetryInfo'
                }
              }
            }
          }
        }
  • Update the main.bicep template of the child module direct parent, as per BCPFR7.

    • Add the enableReferencedModulesTelemetry variable with a default value of false. Place it as the last var declaration, immediately before the first resource declaration.
      var enableReferencedModulesTelemetry = false
    • Pass the enableReferencedModulesTelemetry variable as the enableTelemetry value down to the child module deployment.
      enableTelemetry: enableReferencedModulesTelemetry
  • Add the version.json file to the child module folder and set version to 0.1.

    {
      "$schema": "https://aka.ms/bicep-registry-module-version-file-schema#",
      "version": "0.1"
    }
  • Determine all affected module paths. This includes the child module(s) and all parent modules up to the top-level module.

    Examples:

    • Child module to publish: avm/res/virtual-network/subnet

    • Affected modules:

      • avm/res/virtual-network/subnet
      • avm/res/virtual-network
    • Child module to publish: avm/res/storage/storage-account/blob-service/container/immutability-policy

    • Affected modules:

      • avm/res/storage/storage-account/blob-service/container/immutability-policy
      • avm/res/storage/storage-account/blob-service/container
      • avm/res/storage/storage-account/blob-service
      • avm/res/storage/storage-account
  • Update Changelogs

    • Add a new CHANGELOG.md file to the child module folder, with the following sample content. Make sure to replace the <avm/res/path/to/child-module> placeholder with the name of the child module.
      # Changelog
      
      The latest version of the changelog can be found [here](https://github.com/Azure/bicep-registry-modules/blob/main/<avm/res/path/to/child-module>/CHANGELOG.md).
      
      ## 0.1.0
      
      ### Changes
      
      - Initial version
      
      ### Breaking Changes
      
      - None
    • Check the list of affected modules. Update the changelog of all the affected modules with a version.json. Add a new patch version for each. Refer below for an example content section:
        ## <CurrentMajor>.<CurrentMinor>.<CurrentPatch+1>
      
        ### Changes
      
        - Publishing child module `<avm/res/path/to/child-module>`
      
        ### Breaking Changes
      
        - None
  • Run avm pre-commit on the top-level parent module to process the entire module family:

    $topLevelModulePath = 'avm/res/storage/storage-account'
    avm pre-commit -Ecosystem bicep -Path $topLevelModulePath
  • Raise a PR and verify the shared checks. An authorized maintainer must apply an E2E label to run deployment tests. For an external fork PR, an authorized FTE must perform the release-branch handoff.

Note

Existing tests for the parent module do not need to be updated when publishing a child module. The changes required for child module publishing (telemetry support, version file, and changelogs) do not affect the module’s test cases.

Tip

Reference This pull request as an example for proposing a child module for publishing.