Repository Creation Process

Important

This page is for module owners only. If you are an external contributor, skip to the contribution flow.

Important

Every repository created through this process MUST use AzAPI for every control-plane resource and supported data-plane operation. AzureRM is permitted only for a specific unsupported data-plane/non-ARM API operation under the narrow TFFR3 exception. The exception must be documented and applies only to that operation in the root module, submodules, examples, end-to-end tests, Terraform tests, fixtures, and documentation snippets.

Important

If this process is not followed exactly, it may result in your repository and any in-progress code being permanently deleted.

1. Add yourself to the Module Owners Team and Open Source orgs

If you have already completed these steps, skip to step 2.

Open the Open Source Portal and ensure your GitHub account is linked to your Microsoft account.
Open the Open Source Portal and ensure you are a member of the Azure and Microsoft organizations.
Request access via the Azure Verified Modules (AVM) Module Contributors access package. Approval adds you to the azure-verified-modules-module-contributors Entra group.

Info

Until your access request is approved, you can contribute by using JIT elevation.

2. Gather repository information

You’ll need the following from the module request issue:

Information	Description
Module name	Format: `avm-<type>-<name>` (e.g. `avm-res-network-virtualnetwork`)
Module owner GitHub handle	Your GitHub handle
Module owner display name	`Firstname Lastname`
Module description	Auto-prefixed with `Terraform Azure Verified <module-type> Module for ...`
Resource provider namespace	Resource modules only (e.g. `Microsoft.Network`)
Resource type	Resource modules only (e.g. `virtualNetworks`)
Alternative names	Optional comma-separated list
Secondary owner handle	Optional
Secondary owner display name	Optional

3. Create the repository

Prerequisites:

Clone and prepare

Use the repository creation tooling:

cd ~
git clone "https://github.com/Azure/azure-verified-modules-tools"
cd ./azure-verified-modules-tools/repository-management/repository-creation

Authenticate

gh auth login -h "github.com" -w -p "https"

Run the creation script

if(!(Test-Path -Path "./scripts/New-Repository.ps1")) {
    Write-Error "This script must be run from the repository-creation directory."
    exit 1
}

# Required Inputs
$moduleName = "<module name>" # e.g. avm-res-network-virtualnetwork
$moduleDisplayName = "<module description>"
$resourceProviderNamespace = "" # Leave empty for Pattern/Utility modules
$resourceType = "" # Leave empty for Pattern/Utility modules
$ownerPrimaryGitHubHandle = "<github handle>"
$ownerPrimaryDisplayName = "<display name>"

# Optional
$moduleAlternativeNames = ""
$ownerSecondaryGitHubHandle = ""
$ownerSecondaryDisplayName = ""

./scripts/New-Repository.ps1 `
    -moduleName $moduleName `
    -moduleDisplayName $moduleDisplayName `
    -resourceProviderNamespace $resourceProviderNamespace `
    -resourceType $resourceType `
    -ownerPrimaryGitHubHandle $ownerPrimaryGitHubHandle `
    -ownerPrimaryDisplayName $ownerPrimaryDisplayName `
    -moduleAlternativeNames $moduleAlternativeNames `
    -ownerSecondaryGitHubHandle $ownerSecondaryGitHubHandle `
    -ownerSecondaryDisplayName $ownerSecondaryDisplayName

Complete Open Source Portal Setup

The script will pause and prompt you to configure the Open Source Portal. Follow the link in the script output.

➕ If you see the Complete Setup link

Click Complete Setup and use the following settings:

Question	Answer
Classify the repository	Production
Assign a Service tree or Opt-out	Azure Verified Modules / AVM
Direct owners	Add yourself, `jaredholgate`, and `jatracey`. Add `azure-verified-modules-module-owners` as fallback security group. You add yourself temporarily so you can configure JIT in step 4; you will remove yourself afterwards.
Public open source licensed project?	Yes
What type of open source?	Sample code
License	MIT
All code created by your team?	Yes
Telemetry?	Yes, telemetry
Cryptography?	No
Project name	Azure Verified Module (Terraform) for ‘module name’
Project version	1
Project description	Azure Verified Module (Terraform) for ‘module name’. Part of AVM project - https://aka.ms/avm
Business goals	Create IaC module accelerating Azure deployment using Microsoft best practice.
Used in a Microsoft product?	Open source, can be leveraged in Microsoft services.
Security best practice?	Yes, use just-in-time elevation
Maintainer / Write permissions	Leave empty
Repository template / .gitignore	Uncheck both

Click Finish setup + start business review, then View repository, then Elevate your access.

➕ If you do NOT see the Complete Setup link

Go to the Compliance tab and fill out:
- Direct owners: Add yourself, jaredholgate, and jatracey. Add azure-verified-modules-module-owners as fallback. You add yourself temporarily so you can configure JIT in step 4; you will remove yourself afterwards.
- Classify the repository: Production
- Service tree: Azure Verified Modules / AVM
Go back to Overview and click Elevate your access if available.

Return to the terminal and type yes to complete repository configuration.

The script will automatically:

Create a PR to add module metadata to the repository-sync configuration.
Create a PR to install the Azure Verified Modules GitHub App.

4. Upgrade just-in-time access to JITv2

New repositories default to JIT v1. AVM repositories must be upgraded to JIT v2 and tied to the shared service-AVM-azure-verified-modules-module-owners rule, so that just-in-time elevation is governed centrally by the AVM team rather than by a repository-specific rule.

This is a one-off manual action in the Open Source Portal. You need Direct Owner access to the repository (configured in the previous step) to complete it.

Migrate the repository to JIT v2

Open the repository overview on the Open Source Portal: https://repos.opensource.microsoft.com/orgs/Azure/repos/<module name>.
In the right-hand sidebar, find the Improved Just-in-time (New) panel and click Next.
Review the concepts (Rule Version, Rule, Tie) and click Next.
Leave Require approval for elevation selected and click Upgrade <module name> now.

This migrates the repository to JIT v2 and creates a temporary repository-scoped starter rule. Reload the page and confirm the Just-in-time elevation section now shows JIT version: JIT v2.

Tie the repository to the shared AVM rule

On the repository overview, click Advanced JIT options, then select Propose a new tie.
Under Propose tying a new rule to this repository, enter the Rule ID service-AVM-azure-verified-modules-module-owners and click Review.
Confirm the details and click Create tie.

The tie is created in a pending approval state, so the temporary repository-scoped rule stays active until the tie is approved.

Info

The pending tie must be approved by an owner of the service-AVM-azure-verified-modules-module-owners rule (an AVM core team member). Ask the AVM core team to approve it. Once approved, just-in-time elevation for the repository is governed by the shared AVM rule and the temporary starter rule can be ignored.

Remove yourself as a Direct Owner

You were added as a Direct Owner so you could perform the JIT configuration above. Once you have finished both the JIT v2 upgrade and the shared-rule tie, remove your own account so that only jaredholgate and jatracey remain as Direct Owners.

On the Open Source Portal, open the repository’s Compliance tab.
Under Direct owners, remove your own account, leaving only jaredholgate and jatracey.

Info

Module owners retain day-to-day access through the azure-verified-modules-module-owners security group and just-in-time elevation, so you do not need to remain a Direct Owner.

5. Wait for the GitHub App and repository sync

After the app is installed, repository sync applies the shared repository configuration and managed files to complete the setup.