Repository Creation Process

Important

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

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.

  1. Open the Open Source Portal and ensure your GitHub account is linked to your Microsoft account.
  2. Open the Open Source Portal and ensure you are a member of the Azure and Microsoft organizations.
  3. Navigate to Core Identity and request access to the Azure Verified Module Owners Terraform entitlement.
Info

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

2. Gather repository information

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

InformationDescription
Module nameFormat: avm-<type>-<name> (e.g. avm-res-network-virtualnetwork)
Module owner GitHub handleYour GitHub handle
Module owner display nameFirstname Lastname
Module descriptionAuto-prefixed with Terraform Azure Verified <module-type> Module for ...
Resource provider namespaceResource modules only (e.g. Microsoft.Network)
Resource typeResource modules only (e.g. virtualNetworks)
Alternative namesOptional comma-separated list
Secondary owner handleOptional
Secondary owner display nameOptional

3. Create the repository

Prerequisites:

Clone and prepare

cd ~
git clone "https://github.com/Azure/avm-terraform-governance"
cd ./avm-terraform-governance/tf-repo-mgmt

Authenticate

# GitHub CLI
gh auth login -h "github.com" -w -p "https" -s "delete_repo" -s "workflow" -s "read:user" -s "user:email"

# Azure CLI (if not already logged in)
az login --scope https://graph.microsoft.com/.default --allow-no-subscriptions

Run the creation script

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

# Required Inputs
$moduleProvider = "azurerm" # Allowed: azurerm, azapi, azure
$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 `
    -moduleProvider $moduleProvider `
    -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:

QuestionAnswer
Classify the repositoryProduction
Assign a Service tree or Opt-outAzure Verified Modules / AVM
Direct ownersAdd yourself and jaredholgate or mawhi. Add avm-team-module-owners as fallback security group.
Public open source licensed project?Yes
What type of open source?Sample code
LicenseMIT
All code created by your team?Yes
Telemetry?Yes, telemetry
Cryptography?No
Project nameAzure Verified Module (Terraform) for ‘module name’
Project version1
Project descriptionAzure Verified Module (Terraform) for ‘module name’. Part of AVM project - https://aka.ms/avm
Business goalsCreate 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 permissionsLeave empty
Repository template / .gitignoreUncheck both

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

➕ If you do NOT see the Complete Setup link
  1. Go to the Compliance tab and fill out:
    • Direct owners: Add yourself and jaredholgate or mawhi. Add avm-team-module-owners as fallback.
    • Classify the repository: Production
    • Service tree: Azure Verified Modules / AVM
  2. 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 avm-terraform-governance repository.
  • Create an issue to install the Azure Verified Modules GitHub App.

4. Update the issue status

  1. Add the  Status: Repository Created 📄  label.
  2. Remove the  Status: Ready For Repository Creation 📝  label if present.

5. Wait for the GitHub App

Once installed (usually within 24 hours), the environment sync runs automatically at 15:30 UTC on weekdays to complete the repository setup.