Azv Azure To Bicep

Discover resources in a live Azure scope, extract their full configuration, and generate deployment-ready Bicep templates with modular structure, user-editable parameter files, and dependency documentation for external resources.

Input: An Azure scope — a resource group name (primary) or a subscription ID with optional resource type filter. Optionally, a target environment hint (dev/prod) to influence default sizing in the parameter file.

Tools used: File system tools (read/write files), Terminal (for running az CLI commands and PowerShell 7 / pwsh shared scripts), Azure Best Practices MCP (azure-get_azure_bestpractices), Bicep Schema MCP (azure-bicepschema), and Azure Documentation MCP (azure-documentation).

Tool Preflight

Before discovery, verify the capabilities used by this workflow:

1. Call azure-get_azure_bestpractices with get_azure_bestpractices_get for general code generation guidance.
2. Call azure-bicepschema with bicepschema_get for every resource type whose API version or deployable schema is uncertain.
3. Use azure-documentation search and fetch for current service guidance when a schema call does not answer the question.

If a capability is unavailable, continue only when the matching shared reference plus Bicep CLI validation can provide the same check; report the fallback in the verification summary.

Output Budget Rules

Follow .github/skills/shared/procedures/output-budget.md strictly — this skill frequently handles 20-40+ resources and can hit the LLM response length limit. In addition to the shared rules:

• Build Bicep files directly. Write generated code to files. Do NOT echo full Bicep/bicepparam content in the response — show only file paths and a summary of what was generated.
• Delete intermediate files on the skill's own schedule. Intermediate extraction files (extract-*.json, resource-list-raw.json, and the temporary resource model JSON file) are never deliverables. Keep them available until Step 11 has written the README (it needs the resource counts and extraction stats), then delete them all in Step 12. Never leave the resource model JSON behind after the skill completes.

Fallback: pwsh Unavailable

If pwsh/powershell.exe or a shared script cannot be executed, use the fallback that matches the step you are on, then continue the workflow normally:

Stop only if Azure MCP is also unavailable, using the prerequisite message in .github/skills/shared/azure-resource-configs.md.

Steps

1. Check Azure Authentication

Run pwsh .github/skills/shared/scripts/Test-AzureAuth.ps1 — see .github/skills/shared/procedures/azure-authentication.md for the script contract. The script writes a JSON status object to stdout and exits non-zero when no Azure session is found. A non-zero exit code is a HARD GATE: present the authentication instructions from the contract doc and stop. (If pwsh or the script is unavailable, see "Fallback: pwsh Unavailable".)

2. Accept Inputs

Identify the Azure scope to discover resources from.

2a. Identify the Azure Scope

If the user specifies a resource group name:

• Use that resource group as the discovery scope
• Verify the resource group exists: run az group show --name <name> — if this fails, report an error and stop

If the user specifies a subscription ID:

• Use that subscription as the discovery scope
• Note: subscription-level discovery can produce many resources — the skill will apply filtering and warnings (see Step 4)

If no scope is specified:

• Ask the user:

Which Azure resource group should I generate Bicep templates from?

If you want subscription-level discovery, provide a subscription ID instead.

• Wait for user input

2b. Identify Optional Parameters

Target environment hint: If the user specifies a target environment (e.g., "generate for dev" or "this will be production"):

• Use this to influence default sizing in the .bicepparam comments (e.g., note the current size and suggest dev/prod alternatives)
• If not specified, default to documenting the current Azure configuration as-is

Resource type filters: If the user provides a resource type filter (e.g., "only compute and networking resources"):

• Map the filter to Azure resource type prefixes (e.g., Microsoft.Compute/*, Microsoft.Network/*)
• Apply these filters during discovery

Resource exclusions: If the user wants to exclude specific resources or types:

• Accept a list of resource names or type patterns to skip
• Apply exclusions during the filtering step

3. Discover Azure Resources

Enumerate all resources in the specified Azure scope.

3a. Resource group scope

Run the shared discovery script and write the resource model to a temporary JSON file in the output folder:

pwsh .github/skills/shared/scripts/Get-AzureResourceModel.ps1 -ResourceGroup <rg-name> -OutFile <output-folder>/resource-model.json

The script emits the shared resource model contract (id, name, type, location, tags, sku) documented in .github/skills/shared/azure-resource-model.md. Treat the emitted JSON as the source of truth for Steps 4-7. Do not print the model contents.

Display progress:

⏳ Discovering resources in resource group `<rg-name>`...

3b. Subscription scope

Run the same script with -SubscriptionId <sub-id> instead of -ResourceGroup. Pass user-specified resource type filters from Step 2b as a -ResourceTypeFilter parameter to the script if supported; otherwise filter the emitted JSON before writing to the temporary model file. These user filters are distinct from the Step 4 standard exclusion rules applied by -Mode bicep, which never handles user filters.

3c. Script/pwsh unavailable — MCP fallback

If pwsh/powershell.exe or the script cannot be executed, build the same resource model through Azure MCP as described in "Fallback: pwsh Unavailable" (list resources with mcp_azure_group_resource_list, then assemble the model shape by hand).

3d. Handle empty results

If no resources are found after discovery:

## No Resources Found

No resources were found in `<scope-name>`.

If you expected resources here, verify:
- The resource group name is spelled correctly
- You're connected to the correct subscription (`az account show`)
- Resources have been deployed to this scope
- The authenticated identity has read permissions on this resource group

• Stop execution

4. Filter Non-Deployable Resources

Run pwsh .github/skills/shared/scripts/Select-AzureResources.ps1 -InputFile <resource-model.json> -Mode bicep — see .github/skills/shared/procedures/resource-filtering.md for the script contract. The script applies the shared exclusion rules, writes the filtered resource model JSON to stdout, and should be treated as the source of truth for the remaining steps. (If pwsh or the script is unavailable, see "Fallback: pwsh Unavailable".)

If the script exits non-zero or produces unparseable output, report the error message to the user and stop. Do not proceed with an empty or partial resource list.

Also apply any user-specified exclusion filters from Step 2b.

If the filtered resource list is empty after all exclusion rules have been applied, stop and present:

All discovered resources were excluded by filtering rules. No Bicep templates can be generated.
Review the exclusion rules in `.github/skills/shared/procedures/resource-filtering.md` or adjust your resource type filter.

Display the filtered resource list:

• If the filtered count is 10 or fewer: display the full table inline with columns: #, Resource, Type, Location, SKU.
• If the filtered count exceeds 10: print only the count and a resource-type breakdown summary in the chat response. Create original-request.md in the output folder (recording the original user request and scope details at the top), then append the full resource table to it. Reference the file in the chat response.

5. Check for Large Scope

If the filtered resource count exceeds 30, print a warning that lists unique resource types with counts, then automatically proceed to generate all resources. Templates will be split into modules by category. Do not pause for user confirmation.

6. Deep Property Extraction

For each discovered resource, extract the full resource configuration from Azure.

6a. Extraction method

Prefer running the shared script over manual per-resource extraction:

pwsh .github/skills/shared/scripts/Get-AzureResourceModel.ps1 -ResourceGroup <rg> -Enrich -Mode bicep -StripReadOnly -OutFile <path>

-Enrich fetches full resource detail (az resource show per resource) and extracts per-resource-type properties using the mappings in .github/skills/shared/data/azure-property-paths.json (mcpTool preferred, fallback CLI command per resource type, plus armJsonPath/composite rules for individual properties). -Mode bicep also applies the Step 4 filtering rules automatically.

Generation boundary: Azure responses contain a mix of deployable configuration and computed state. Generate Bicep only from each model resource's deployableProperties, plus explicitly preserved deployable top-level values (location, tags, sku, kind, and managed identity configuration). Use the raw properties bag only for relationship discovery. Never serialize an unreviewed raw properties bag into generated Bicep.

If pwsh or the script is unavailable, see "Fallback: pwsh Unavailable" to enrich and extract properties by hand.

After all resources are extracted, print a single batch summary (e.g., ✅ Extracted 34 resources (3 partial, 2 skipped)). Do not print per-resource progress lines.

6b. Property filtering and secrets detection

The -StripReadOnly switch in the Step 6a command removes read-only, computed, and ARM-internal properties (provisioningState, resourceGuid, etag, timestamps, property-level id/name/type, identity.principalId, privateEndpointConnections, …) and flags secret-bearing properties. The rules live in .github/skills/shared/data/arm-readonly-properties.json.

If pwsh or the script is unavailable, apply the same rules by hand: strip the alwaysRemoveAnyDepth names at any depth and the alwaysRemoveAtRoot names at the root of each properties bag, apply removePaths, and never strip keepPaths (identity.type, identity.userAssignedIdentities) or the deployable sku, kind, location, and tags.

6c. Handling flagged secrets

The script writes an optional secrets array of dotted property paths on each affected resource (see .github/skills/shared/azure-resource-model.md). For every flagged path:

• Generate a @secure() parameter whose .bicepparam value uses readEnvironmentVariable() — see .github/skills/shared/bicep-best-practices.md
• Add it to the output summary as a "requires manual configuration" item

6d. Graceful fallback

If a resource-specific tool fails or is unavailable:

• Log a note: ⚠️ Could not fully extract <resource-name> (<resource-type>) — using list-level information
• Use the properties available from the initial discovery (Step 3)
• Mark the resource as "partially extracted" in the output
• Do not stop execution due to extraction failures