Azure deployment preflight
Validate Bicep infrastructure before deployment by detecting the workflow, running syntax and preview commands, categorizing what-if changes, and writing a preflight-report.md with actionable issues.
When to invoke
- "Validate my Bicep deployment before I run it."
- "Preview what azd provision will change."
- "Run Azure what-if for this template."
- "Check whether I have permission to deploy this infrastructure."
- "Prepare for azd up or az deployment."
Prerequisites and context
| Tool or value |
Required for |
How to check or obtain |
az |
Standalone Azure CLI what-if |
az --version; az account show for subscription. |
azd |
Projects with azure.yaml |
azd version; azd env list for environments. |
bicep |
Local syntax validation |
bicep --version; fallback to Azure validation if absent. |
| Resource group |
az deployment group what-if |
Ask user or check existing .azure/ config. |
| Subscription |
All deployments |
az account show or ask user. |
| Location |
sub, mg, or tenant scope |
Ask user or use default from config. |
| Environment |
azd projects |
azd env list or user input. |
Procedure
- Detect project type: if
azure.yaml exists, use the azd workflow; otherwise use the Azure CLI workflow.
- Locate
.bicep files. For azd, check infra/ before the project root. For standalone deployments, use the user's file or search infra/, deploy/, and the root.
- Match parameter files in this order:
<filename>.bicepparam, <filename>.parameters.json, parameters.json, then parameters/<env>.json in the same area.
- Run syntax validation for each Bicep file:
bicep build <bicep-file> --stdout. Capture line and column errors, warnings, and build status. If bicep is not installed, note it and continue.
- Run the deployment preview. Continue after failures and capture every issue.
- Parse what-if change symbols and property changes.
- Write
preflight-report.md in the project root using references/REPORT-TEMPLATE.md.
Preview commands
| Workflow or scope |
Command |
azd default environment |
azd provision --preview |
azd named environment |
azd provision --preview --environment <env-name> |
resourceGroup target scope |
az deployment group what-if --resource-group <rg-name> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
subscription target scope |
az deployment sub what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
managementGroup target scope |
az deployment mg what-if --location <location> --management-group-id <mg-id> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
tenant target scope |
az deployment tenant what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider |
| RBAC fallback |
Retry with --validation-level ProviderNoRbac and state that full permission validation did not run. |
What-if interpretation
| Change type |
Symbol |
Meaning |
Report detail |
| Create |
+ |
New resource will be created |
Resource type, name, location. |
| Delete |
- |
Existing resource will be deleted |
Mark as high risk unless intentional. |
| Modify |
~ |
Properties will change |
Include property names and before/after values when available. |
| NoChange |
= |
Resource unchanged |
Count only unless the user asked for full inventory. |
| Ignore |
* |
Resource not analyzed because limits were reached |
Warn that the preview is incomplete. |
| Deploy |
! |
Resource will be deployed but changes are unknown |
Require manual inspection. |
Error handling
Continue validation even when errors occur; the report should contain all failures and warnings.
| Error type |
Action |
| Not logged in |
Note in report; suggest az login or azd auth login. |
| Permission denied |
Retry what-if with ProviderNoRbac; note missing RBAC validation. |
| Bicep syntax error |
Include every error; continue to other files. |
| Tool not installed |
Note in report and skip only that validation step. |
| Resource group not found |
Note in report; suggest creating it or selecting the correct group. |
Progressive disclosure and bundled resources
references/VALIDATION-COMMANDS.md: detailed command variants and flags.references/REPORT-TEMPLATE.md: required preflight-report.md structure.references/ERROR-HANDLING.md: detailed remediation guidance.
Command and scope vocabulary
Preserve Azure deployment terminology exactly when reporting: azd up, azd provision, az deployment, az deployment group, az deployment sub what-if, az deployment mg what-if, az deployment tenant what-if, --validation-level, --validation-level Provider, targetScope, Sub/MG/Tenant, JSON, line/column, success/failure, and create/modify/delete/unchanged.
Use concrete examples when they match the repository: infra/main.bicep, infra/main.bicepparam, and bicep build infra/main.bicep --stdout.
Output template
## Azure deployment preflight
**Status:** pass | issues found | blocked
**Report:** `preflight-report.md`
**Workflow:** azd | az cli
**Target scope:** resourceGroup | subscription | managementGroup | tenant | unknown
### Tools executed
| Tool | Command | Result |
| --- | --- | --- |
| Bicep | `bicep build <bicep-file> --stdout` | <pass/fail/skipped> |
| Preview | `<azd provision --preview or az deployment ... what-if>` | <pass/fail> |
### What-if summary
| Symbol | Count | Notes |
| --- | --- | --- |
| `+` | <count> | <created resources> |
| `~` | <count> | <modified resources> |
| `-` | <count> | <deleted resources> |
### Issues
- <severity>: <error, warning, permission gap, or missing input>
Quality gate
1---2name: azure-deployment-preflight3description: Validate Azure Bicep deployments before execution with syntax checks, azd preview, Azure CLI what-if, validation-level fallback, permission checks, and a preflight report. Use this skill when the user asks before azd up, azd provision, az deployment, Bicep deployment, infrastructure review, permission verification, or what-if change preview.4---56<!-- Generated from harness/github-copilot/skills/azure-deployment-preflight/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# Azure deployment preflight910Validate Bicep infrastructure before deployment by detecting the workflow, running syntax and preview commands, categorizing what-if changes, and writing a `preflight-report.md` with actionable issues.1112## When to invoke1314- "Validate my Bicep deployment before I run it."15- "Preview what azd provision will change."16- "Run Azure what-if for this template."17- "Check whether I have permission to deploy this infrastructure."18- "Prepare for azd up or az deployment."1920## Prerequisites and context2122| Tool or value | Required for | How to check or obtain |23| --- | --- | --- |24| `az` | Standalone Azure CLI what-if | `az --version`; `az account show` for subscription. |25| `azd` | Projects with `azure.yaml` | `azd version`; `azd env list` for environments. |26| `bicep` | Local syntax validation | `bicep --version`; fallback to Azure validation if absent. |27| Resource group | `az deployment group what-if` | Ask user or check existing `.azure/` config. |28| Subscription | All deployments | `az account show` or ask user. |29| Location | `sub`, `mg`, or `tenant` scope | Ask user or use default from config. |30| Environment | `azd` projects | `azd env list` or user input. |3132## Procedure33341. Detect project type: if `azure.yaml` exists, use the `azd` workflow; otherwise use the Azure CLI workflow.352. Locate `.bicep` files. For `azd`, check `infra/` before the project root. For standalone deployments, use the user's file or search `infra/`, `deploy/`, and the root.363. Match parameter files in this order: `<filename>.bicepparam`, `<filename>.parameters.json`, `parameters.json`, then `parameters/<env>.json` in the same area.374. Run syntax validation for each Bicep file: `bicep build <bicep-file> --stdout`. Capture line and column errors, warnings, and build status. If `bicep` is not installed, note it and continue.385. Run the deployment preview. Continue after failures and capture every issue.396. Parse what-if change symbols and property changes.407. Write `preflight-report.md` in the project root using `references/REPORT-TEMPLATE.md`.4142## Preview commands4344| Workflow or scope | Command |45| --- | --- |46| `azd` default environment | `azd provision --preview` |47| `azd` named environment | `azd provision --preview --environment <env-name>` |48| `resourceGroup` target scope | `az deployment group what-if --resource-group <rg-name> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |49| `subscription` target scope | `az deployment sub what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |50| `managementGroup` target scope | `az deployment mg what-if --location <location> --management-group-id <mg-id> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |51| `tenant` target scope | `az deployment tenant what-if --location <location> --template-file <bicep-file> --parameters <param-file> --validation-level Provider` |52| RBAC fallback | Retry with `--validation-level ProviderNoRbac` and state that full permission validation did not run. |5354## What-if interpretation5556| Change type | Symbol | Meaning | Report detail |57| --- | --- | --- | --- |58| Create | `+` | New resource will be created | Resource type, name, location. |59| Delete | `-` | Existing resource will be deleted | Mark as high risk unless intentional. |60| Modify | `~` | Properties will change | Include property names and before/after values when available. |61| NoChange | `=` | Resource unchanged | Count only unless the user asked for full inventory. |62| Ignore | `*` | Resource not analyzed because limits were reached | Warn that the preview is incomplete. |63| Deploy | `!` | Resource will be deployed but changes are unknown | Require manual inspection. |6465## Error handling6667Continue validation even when errors occur; the report should contain all failures and warnings.6869| Error type | Action |70| --- | --- |71| Not logged in | Note in report; suggest `az login` or `azd auth login`. |72| Permission denied | Retry what-if with `ProviderNoRbac`; note missing RBAC validation. |73| Bicep syntax error | Include every error; continue to other files. |74| Tool not installed | Note in report and skip only that validation step. |75| Resource group not found | Note in report; suggest creating it or selecting the correct group. |7677## Progressive disclosure and bundled resources7879- `references/VALIDATION-COMMANDS.md`: detailed command variants and flags.80- `references/REPORT-TEMPLATE.md`: required `preflight-report.md` structure.81- `references/ERROR-HANDLING.md`: detailed remediation guidance.8283## Command and scope vocabulary8485Preserve Azure deployment terminology exactly when reporting: `azd up`, `azd provision`, `az deployment`, `az deployment group`, `az deployment sub what-if`, `az deployment mg what-if`, `az deployment tenant what-if`, `--validation-level`, `--validation-level Provider`, `targetScope`, `Sub/MG/Tenant`, `JSON`, `line/column`, `success/failure`, and `create/modify/delete/unchanged`.8687Use concrete examples when they match the repository: `infra/main.bicep`, `infra/main.bicepparam`, and `bicep build infra/main.bicep --stdout`.8889## Output template9091```markdown92## Azure deployment preflight9394**Status:** pass | issues found | blocked95**Report:** `preflight-report.md`96**Workflow:** azd | az cli97**Target scope:** resourceGroup | subscription | managementGroup | tenant | unknown9899### Tools executed100| Tool | Command | Result |101| --- | --- | --- |102| Bicep | `bicep build <bicep-file> --stdout` | <pass/fail/skipped> |103| Preview | `<azd provision --preview or az deployment ... what-if>` | <pass/fail> |104105### What-if summary106| Symbol | Count | Notes |107| --- | --- | --- |108| `+` | <count> | <created resources> |109| `~` | <count> | <modified resources> |110| `-` | <count> | <deleted resources> |111112### Issues113- <severity>: <error, warning, permission gap, or missing input>114```115116## Quality gate117118- [ ] Project type was detected from `azure.yaml` or absence of it.119- [ ] Bicep files and matching parameter files were located and reported.120- [ ] `bicep build <bicep-file> --stdout` was run or its absence was documented.121- [ ] The correct `azd provision --preview` or `az deployment ... what-if` scope was selected.122- [ ] `--validation-level ProviderNoRbac` fallback was used only after permission failure and was reported.123- [ ] What-if symbols `+`, `-`, `~`, `=`, `*`, and `!` were interpreted correctly.124- [ ] `preflight-report.md` was created in the project root or the blocker is explicit.125- [ ] Referenced bundled resources exist and were used on demand.
paulasilvatech