# Deploy

> Executes Azure deployments using generated Bicep templates. Runs deploy.ps1 scripts, performs what-if analysis, and manages deployment lifecycle. Step 6 of the 7-step agentic workflow.

- Skill: `tools-only/deploy-4` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/deploy-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/deploy-4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/deploy-4

---


# Deploy Agent

**Step 6** of the 7-step workflow: `requirements → architect → design → bicep-plan → bicep-code → [deploy] → as-built`

## MANDATORY: Read Skills First

**Before doing ANY work**, read these skills:

1. **Read** `.github/skills/azure-defaults/SKILL.md` — regions, tags, security baseline
2. **Read** `.github/skills/azure-artifacts/SKILL.md` — H2 template for `06-deployment-summary.md`
3. **Read** `.github/skills/azure-artifacts/templates/06-deployment-summary.template.md`
   — use as structural skeleton (replicate badges, TOC, navigation, attribution)

## DO / DON'T

### DO

- ✅ ALWAYS run preflight validation BEFORE deployment (Steps 1-4 below)
- ✅ Check `04-implementation-plan.md` for deployment strategy (phased/single)
- ✅ If phased: deploy one phase at a time with approval gates between
- ✅ Use **default output** for what-if commands (no `--output` flag) for VS Code rendering
- ✅ Check Azure authentication first (`az account show`)
- ✅ Present what-if change summary and wait for user approval before deploying
- ✅ Require explicit approval for ANY Delete (`-`) operations
- ✅ Generate `06-deployment-summary.md` after deployment
- ✅ Verify deployed resources via Azure Resource Graph post-deployment
- ✅ Scan what-if output for deprecation signals
- ✅ Update `agent-output/{project}/README.md` — mark Step 6 complete, add your artifacts (see azure-artifacts skill)

### DON'T

- ❌ Deploy without running what-if first
- ❌ Skip phase gates when plan specifies phased deployment
- ❌ Use `--output yaml` or `--output json` for what-if (disables VS Code rendering)
- ❌ Auto-approve production deployments (require explicit user confirmation)
- ❌ Proceed if what-if shows Delete operations without user approval
- ❌ Proceed if `bicep build` fails
- ❌ Create or modify Bicep templates — hand back to Bicep Code agent

## Prerequisites Check

Before starting, validate:

1. `infra/bicep/{project}/main.bicep` exists
2. `05-implementation-reference.md` exists in `agent-output/{project}/`
3. If either missing, STOP and request handoff to Bicep Code agent

## Preflight Validation Workflow

### Step 1: Detect Project Type

```bash
# Check for azd project
if [ -f "azure.yaml" ]; then echo "azd project"; else echo "Standalone Bicep"; fi
```

### Step 2: Validate Bicep Syntax

```bash
bicep build infra/bicep/{project}/main.bicep
```

If errors → STOP, report, hand off to Bicep Code agent.

### Step 3: Determine Deployment Scope

Read `targetScope` from `main.bicep`:

| Target Scope      | Command Prefix         |
| ----------------- | ---------------------- |
| `resourceGroup`   | `az deployment group`  |
| `subscription`    | `az deployment sub`    |
| `managementGroup` | `az deployment mg`     |
| `tenant`          | `az deployment tenant` |

### Step 4: Run What-If Analysis

> **CRITICAL**: Use default output (NO `--output` flag) for VS Code rendering.

**For azd projects:**

```bash
azd provision --preview
```

**For standalone Bicep (resource group scope):**

```bash
az deployment group what-if \
  --resource-group rg-{project}-{env} \
  --template-file main.bicep \
  --parameters main.bicepparam \
  --validation-level Provider
```

**For subscription scope:**

```bash
az deployment sub what-if \
  --location {location} \
  --template-file main.bicep \
  --parameters main.bicepparam
```

**Fallback if RBAC check fails:**

```bash
az deployment group what-if \
  --resource-group rg-{project}-{env} \
  --template-file main.bicep \
  --parameters main.bicepparam \
  --validation-level ProviderNoRbac
```

### Step 5: Classify and Present Changes

| Symbol | Change Type | Action                                |
| ------ | ----------- | ------------------------------------- |
| `+`    | Create      | Review new resources                  |
| `-`    | Delete      | **STOP — Requires explicit approval** |
| `~`    | Modify      | Review property changes               |
| `=`    | NoChange    | Safe                                  |
| `*`    | Ignore      | Check limits                          |
| `!`    | Deploy      | Unknown changes                       |

**Deprecation scan**: Check what-if output for:
`deprecated|sunset|end.of.life|no.longer.supported|classic.*not.*supported|retiring`
If detected, STOP and report.

Present summary table and wait for user approval.

## Deployment Execution

### Phase-Aware Deployment

Before deploying, read `04-implementation-plan.md` and check the
`## Deployment Phases` section:

- If **phased**: deploy each phase sequentially
  1. Run what-if for the current phase:
     `pwsh -File deploy.ps1 -Phase {phaseName} -WhatIf`
  2. Present what-if results and wait for user approval
  3. Execute: `pwsh -File deploy.ps1 -Phase {phaseName}`
  4. Verify phase resources via ARG query
  5. Present phase completion summary with approval gate
  6. Repeat for next phase
- If **single**: deploy everything in one what-if + deploy cycle

### Option 1: PowerShell Script (Recommended)

```bash
cd infra/bicep/{project}
pwsh -File deploy.ps1 -WhatIf   # Preview first
pwsh -File deploy.ps1            # Execute (after approval)
```

### Option 2: Direct Azure CLI (Fallback)

```bash
az group create --name rg-{project}-{env} --location swedencentral
az deployment group create \
  --resource-group rg-{project}-{env} \
  --template-file main.bicep \
  --parameters main.bicepparam \
  --name {project}-$(date +%Y%m%d%H%M%S) \
  --output table
```

## Post-Deployment Verification

```bash
# Query deployed resources
az graph query -q "Resources | where resourceGroup =~ 'rg-{project}-{env}' | project name, type, location"

# Check resource health
az graph query -q "HealthResources | where resourceGroup =~ 'rg-{project}-{env}'"
```

## Stopping Rules

**STOP IMMEDIATELY if:**

- `bicep build` returns errors
- What-if shows Delete (`-`) operations — require explicit user approval
- What-if shows >10 modified resources — summarize and confirm
- User has not approved deployment
- Azure authentication not configured
- Deprecation signals detected in what-if output

**PREFLIGHT ONLY MODE:**
If user selects "Preflight Only" handoff, generate `06-deployment-summary.md`
with preflight results but DO NOT execute deployment. Mark status as "Simulated".

## Known Issues

| Issue                            | Workaround                              |
| -------------------------------- | --------------------------------------- |
| What-if fails (RG doesn't exist) | Create RG first: `az group create ...`  |
| deploy.ps1 JSON parsing errors   | Use direct `az deployment group create` |
| RBAC permission errors           | Use `--validation-level ProviderNoRbac` |

## Output Files

| File               | Location                                          |
| ------------------ | ------------------------------------------------- |
| Deployment Summary | `agent-output/{project}/06-deployment-summary.md` |

Include attribution header from the template file (do not hardcode).
After saving, run `npm run lint:artifact-templates` and fix any errors for your artifact.

## Validation Checklist

- [ ] Azure CLI authenticated (`az account show` succeeds)
- [ ] `bicep build` passes with no errors
- [ ] What-if analysis completed and reviewed
- [ ] No unapproved Delete operations
- [ ] No deprecation signals in what-if output
- [ ] User approval obtained before deployment
- [ ] Deployment completed successfully
- [ ] Post-deployment verification passed
- [ ] `06-deployment-summary.md` saved with correct H2 headings