Azure App Onboard

MicrosoftOfficialCreated by Microsoft

Skill
Workflow
Cloud and DevOps
MIT
Low risk
Has scripts

From the author

End-to-end orchestrator: from a business idea, app idea, or existing app to running Azure deployment with cost estimates and pre-deploy approval. Analyzes your app, auto-detects the right Azure services, scaffolds infrastructure code, and deploys — tailored to your app, not a template. Handles moving existing apps to Azure without rewriting or with minimal changes. WHEN: bring your app to Azure, plan my app, cost to run, is my code ready to deploy, deploy my app to the cloud, deploy all my services, what Azure services do I need, plan my Azure deployment, deploy my new app to Azure, one-click deploy, I have an app and want it on Azure, migrate my app to Azure, help me get started, build an app, no code yet, starter project. DO NOT USE FOR: use azd for deployment(use azure-deploy), optimizing existing costs (use cost-optimization), code readiness checks only (use azure-app-onboard-prereq).

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Azure App Onboard is a comprehensive workflow agent designed to take a business idea or an existing codebase and transition it to a running Azure deployment. It automates the entire lifecycle from initial discovery and architecture planning to infrastructure scaffolding and final deployment. The skill is built to be intelligent and tailored, analyzing the specific requirements of your application rather than relying on generic templates. It includes built-in approval gates for both the architecture plan and the final deployment, ensuring you maintain control over costs and resource configuration throughout the process.

What it does

Analyzes your application code or business idea to determine the optimal Azure service stack.
Generates custom infrastructure-as-code (IaC) files tailored to your specific application needs.
Provides detailed cost estimates for the proposed Azure infrastructure before deployment.
Executes the deployment of resources directly to your Azure subscription.
Handles the migration of existing applications to Azure with minimal code changes.
Provides a structured, step-by-step onboarding experience for developers of all experience levels.

When to use it

When you have an application and want to deploy it to Azure but are unsure which services to use.
When you need to migrate an existing application to the cloud without a complete rewrite.
When you require a cost estimate for your infrastructure before committing to a deployment.
When you need guided, end-to-end assistance for setting up a new Azure project.
When you want to verify if your current codebase is ready for a cloud deployment.

Advantages

Eliminates guesswork by auto-detecting the right Azure services for your specific stack.
Reduces manual effort by automating the scaffolding of infrastructure-as-code.
Ensures transparency with mandatory approval gates for architecture and deployment.
Provides cost visibility early in the planning phase.
Supports a wide range of scenarios from greenfield projects to existing app migrations.

Usage examples

“I have a Python web app and want to deploy it to Azure. Can you help me get started?”: The agent will initiate the discovery phase, scan your codebase, propose an architecture, and guide you through the deployment process.
“I need to move my existing application to Azure, but I'm not sure what services I need. Can you plan this for me?”: The agent will analyze your app's requirements, suggest the appropriate Azure services, and provide a cost estimate for your approval.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/azure-app-onboard/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip azure-app-onboard.zip -d .agents/skills

Documentation by Microsoft

Azure App Onboard

⛔ Every repo goes through the full pipeline (Steps 1–10). No exceptions. Do not skip steps, refuse, or short-circuit based on what you recognize. Follow the Workflow table below sequentially — read each step's references before acting.

Quick Reference

Property	Value
Best for	Developers who know what to build but not which Azure services to use
Inputs	Business idea or existing codebase, budget/scale preferences (optional)
Outputs	Architecture plan, cost estimate, IaC files, deployed Azure resources
Phases	Discover → Architect → Scaffold → Deploy (self-contained, no external skill calls)

When to Use This Skill

Deploy existing code without knowing which Azure services to use
Check if your existing code is ready to deploy to Azure
Move an existing app to Azure without rewriting or with minimal changes
Get cost estimates before committing to infrastructure
Understand architecture decisions and rejected alternatives
Get answers to Azure architecture or service selection questions (e.g., "What database should I use?")
Get guided Azure onboarding without prior experience

When NOT to Use

Scenario	Use Instead
Run `azd up` or execute an existing deployment	`azure-deploy`
Optimize existing Azure spend	`cost-optimization` from the optional `azure-cost` plugin
Generate Bicep/Terraform for a known architecture	`azure-prepare`
Validate infrastructure or run preflight checks	`azure-validate`
Troubleshoot a running Azure deployment	`azure-diagnostics`
Deploy to or manage AKS/Kubernetes directly	`azure-kubernetes`
Look up or list existing Azure resources	`azure-resource-lookup`

If cost-optimization is unavailable, explain that it is provided by the optional azure-cost plugin and direct the user to their client's supported plugin installation flow; do not imply the handoff completed.

Pipeline Rules

⛔ You MUST read references/pipeline-rules.md at the start of every AppOnboard session. It contains approval gates, phase lifecycle, session artifacts, deploy-as-is, and security baseline rules.

Workflow

⛔ Deploy recovery: After deploy gate approval OR before any az deployment/az webapp deploy/az acr build — if you haven't read deploy/PHASE.md, read .copilot-azure/sessions/{id}/deploy-checklist.md first, then deploy/PHASE.md. ⛔ NEVER invoke {"skill": "azure-deploy"} — that is a DIFFERENT skill for a DIFFERENT workflow.

⛔ Post-scaffold transition (MANDATORY): Immediately after scaffold-manifest.json is written, YOUR NEXT ACTION MUST be Step 8 (Deploy Approval Gate) — NOT a summary report, NOT a "here are the generated files" message, NOT a completion signal. Confirm context.json has completedPhases: [...,"scaffold"] + currentPhase: "deploy" (update it yourself if the scaffold subagent didn't). Re-read approval-gates.md § Deploy Gate if evicted from context (scaffold reference loading is heavy), then present the exact prompt: "🚀 Ready to deploy? (Yes / Run manually / Edit plan / Cancel)". This gate is the LAST content in your response — wait for the user's reply.

#	Step	Action	Reference
1	Session check + Azure login	Create/resume session, verify Azure CLI auth, resolve subscription + user identity	⛔ You MUST read session-protocol.md
2	Scope triage	Check azd markers, triage question. Empty workspace or code-only (no infra) → Step 3 directly.	⛔ Read intent-gathering.md § Scope Triage
3	Prereq scan	⛔ Skip if `completedPhases` includes `"prereq"`. Otherwise: invoke `{"skill": "azure-app-onboard-prereq"}`. Write `prereq-output.json`, update `context.json`. Halt if: `overallHealth: "blocked"` OR `routeToSkill` set.
4	Gather intent	Present prereq results, confirm stack + Azure services, ask remaining questions.	⛔ Read intent-gathering.md § After Prereq Returns
5	Plan architecture	Write `prepare-plan.json`.	⛔ You MUST read prepare/PHASE.md
6	Scaffold approval gate	Display plan for user approval BEFORE generating any files.	⛔ Read approval-gates.md § Scaffold Gate
7	Scaffold	Generate IaC, self-review. Write `scaffold-manifest.json`. Update `context.json`.	⛔ You MUST read scaffold/PHASE.md
8	Deploy approval gate	Display validation summary. ⛔ After approval: FIRST read deploy-checklist.md → deploy/PHASE.md. NEVER `{"skill": "azure-deploy"}`.	⛔ Read approval-gates.md § Deploy Gate
9	Deploy	Execute IaC, health-check. Write `deploy-result.json`.	⛔ You MUST read deploy/PHASE.md
10	Handoff	Surface deployment identity, cleanup commands, next steps.	⛔ You MUST read `handoff-protocol.md`

Error Handling

Error	Remediation
Phase fails	Halt, report phase + error. User decides: retry, skip, abort.
MCP server unavailable	Skip affected checks, add disclaimer to `costEstimate.assumptions[]` and every approval gate.
Missing RBAC	Report required role + `az role assignment` command.

Shared references: MCP tools (cross-phase tool parameters) | IaC resources (Azure resource docs for troubleshooting)

Files

ATTRIBUTION.mdAdded by AutoGineer983 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md6.6 KiB
deploy/PHASE.md7.5 KiB
deploy/references/approval-gate-template.md2.9 KiB
deploy/references/blocked-patterns.md5.7 KiB
deploy/references/code-deployment-appservice.md4.6 KiB
deploy/references/code-deployment-container-apps.md8.4 KiB
deploy/references/code-deployment-swa.md5.7 KiB
deploy/references/database-post-deploy.md4.5 KiB
deploy/references/deploy-checklist-template.md10.1 KiB
deploy/references/deploy-safety.md4.5 KiB
deploy/references/deploy-schemas.tsScript3.5 KiB
deploy/references/error-classification.md3.6 KiB
deploy/references/health-check-patterns.md5.5 KiB
deploy/references/mcp-tools.md5.5 KiB
deploy/references/portal-links.md3.1 KiB
deploy/references/preflight-checks.md4.4 KiB
deploy/references/subagent-preflight.md5.1 KiB
prepare/PHASE.md6.4 KiB
prepare/references/deploy-strategy.md6.8 KiB
prepare/references/mcp-tools.md5.6 KiB
prepare/references/naming-patterns.md4.6 KiB
prepare/references/prepare-schemas.tsScript7.0 KiB
prepare/references/pricing-guide-services.md8.4 KiB
prepare/references/pricing-guide.md4.0 KiB
prepare/references/service-mapping.md8.5 KiB
prepare/references/sku-matrix.md3.2 KiB
prepare/references/sku-quota-validation.md9.0 KiB
prepare/references/subagent-pricing.md2.5 KiB
prepare/references/subagent-quota.md3.5 KiB
prepare/references/validation-rubric.md2.3 KiB
references/approval-gates.md8.4 KiB
references/azd-template-routing.md4.7 KiB
references/handoff-protocol.md7.8 KiB
references/iac-resources.md2.6 KiB
references/intent-gathering.md2.2 KiB
references/mcp-tool-reference.md3.7 KiB
references/pipeline-rules-runtime.md3.5 KiB
references/pipeline-rules.md6.3 KiB
references/session-protocol.md8.0 KiB
references/session-schemas.tsScript5.2 KiB
references/subscription-resolution.md2.1 KiB
scaffold/PHASE.md14.2 KiB
scaffold/references/bicep-app-service.md5.4 KiB
scaffold/references/bicep-container-apps.md9.3 KiB
scaffold/references/bicep-patterns-data.md4.0 KiB
scaffold/references/bicep-patterns-security.md7.8 KiB
scaffold/references/bicep-patterns.md6.8 KiB
scaffold/references/bicep-swa.md757 B
scaffold/references/cicd-pipelines.md325 B
scaffold/references/dockerfile-generation.md4.1 KiB
scaffold/references/env-var-secrets.md4.1 KiB
scaffold/references/error-handling.md1.5 KiB
scaffold/references/iac-generation-rules.md6.6 KiB
scaffold/references/mcp-tools.md7.0 KiB
scaffold/references/rbac-roles.md3.8 KiB
scaffold/references/scaffold-healing-rules.md3.3 KiB
scaffold/references/scaffold-schemas.tsScript3.5 KiB
scaffold/references/self-healing.md2.3 KiB
scaffold/references/self-review-checklist.md9.0 KiB
scaffold/references/self-review-procedure.md2.3 KiB
scaffold/references/subagent-iac-gen.md9.5 KiB
scaffold/references/subagent-review.md3.5 KiB
scaffold/references/subagent-validate.md7.2 KiB
scaffold/references/terraform-patterns.md6.9 KiB
scaffold/references/validation-and-manifest.md5.1 KiB
scaffold/references/waf-checklist.md2.3 KiB
scaffold/scripts/scaffold-conformance.ps1Script12.8 KiB
scaffold/scripts/scaffold-conformance.shScript13.8 KiB

deploy/references/deploy-checklist-template.md

Deploy Checklist Template (compaction-safe — generated at Step 5b)

Long-running deploy sessions lose rules when the conversation compacts. At Step 5b, generate a checklist file tailored to this deployment. Write it to disk so it survives compaction — re-reading costs ~100 tokens.

Write to .copilot-azure/sessions/{id}/deploy-checklist.md using the create tool at Step 5b. Re-read via view after every long-running command (az deployment, az webapp deploy, az acr build), after each failed health check, and after any conversation compaction.

How to generate

Read prepare-plan.json to determine the service types, then build the checklist from the template below. Replace {placeholders} with real values and delete sections that don't apply (e.g., remove the App Service section for a Container Apps deploy).

# Deploy Checklist for {appName}
# RG: {rgName} | Sub: {subscriptionId} | Session: {sessionId}

## ⛔ Secret generation (BEFORE first az deployment)
- Auto-generate ALL `@secure()` params before first `az deployment sub create` — NEVER `ask_user`
- ⛔ On ANY retry OR redeploy (incl. after a conversation compaction): read the SAME `@secure()` value back from Key Vault (source of truth) or `deploy-audit.log` — NEVER regenerate. A secret that's both applied to a resource AND stored in KV desyncs if regenerated: e.g. a DB module re-applying `administratorLoginPassword` re-sets the server admin but not the KV secret the app reads → auth 500s while provisioning still reports success.

## ⛔ Read deploy/PHASE.md
- You MUST `view` deploy/PHASE.md BEFORE running any `az deployment` command
- Path: `plugin/skills/azure-app-onboard/deploy/PHASE.md`
- If you have not read it in this conversation (or since the last compaction), read it NOW
- It covers preflight checks, portal links, what-if, SCM lifecycle, deploy-result.json schema, audit logging, and health checks — skip it and none of these happen

## After every `az` command
- Append 2 lines to `deploy-audit.log`: `{timestamp} | {command} | started` then `{timestamp} | {command} | succeeded/failed`

## After IaC deployment (Step 6)
- Verify 5 tags: `az group show -n {rgName} --query tags`
- ⛔ Do NOT set startup command or app settings via CLI — they are already in Bicep from scaffold. If `az webapp show` doesn't reflect them yet, wait 30s and re-check (ARM propagation delay). Do NOT run `az webapp config` imperatively.
  Required: app-onboard-skill, app-onboard-session-id, created-at, environment, deployed-by
- Verify portal link is still correct if healing changed the deployment name

## Code deploy — App Service (delete if not using App Service)
- ⛔ **Deploy command: `az webapp deploy --type zip`** (Entra-capable, supports `--async`). NEVER `az webapp deployment source config-zip` — it needs SCM basic auth and is disallowed.
- Wait for stabilization: `az webapp show -g {rgName} -n {appName} --query state` → "Running"
- Verify `SCM_DO_BUILD_DURING_DEPLOYMENT=true` is active before deploy (ARM timing can delay)
- If build reports "0 seconds" but app needs deps: re-set the setting, wait 10s, retry
- If 0s persists after 2 retries: fall back to Kudu `/api/zipdeploy`
- Python: if no `antenv/` after deploy, use Kudu `/api/zipdeploy` immediately (OneDeploy may skip Oryx)
- Windows zip paths: normalize with `.Replace('\', '/')` before creating zip entries
- ⛔ Verify ORYX_DISABLE_COMPRESSION=true is set (prevents output.tar.zst extraction failures at startup — applies to ALL tiers, not just F1)
- Set WEBSITES_CONTAINER_START_TIME_LIMIT=1800 for safety
- TypeScript apps: verify `typescript` and `@types/*` are in `dependencies` (not devDependencies) — Oryx with NODE_ENV=production skips devDeps. Alternative: set app setting NPM_CONFIG_PRODUCTION=false
- Enable SCM before zip deploy, re-disable after: `az rest --method put` → allow:false → verify
- After deploy: check response body for Azure default page ("Your app service is up and running" = app didn't start)

## Code deploy — Container Apps (delete if not using Container Apps)
- Phase 2 is NOT optional — deploy actual image, don't leave placeholder
- Wait ~60s for RBAC propagation (AcrPull role) before code deploy
- BuildKit Dockerfiles: create Dockerfile.azure without --mount syntax
- Pass real image on EVERY Bicep redeploy: --parameters containerImage='{acr}/{app}:latest'
- KV secrets: `revision restart` does NOT refresh — must create new revision
- ACR build failures count toward healing counter
- Windows: append `--no-logs` to `az acr build` to avoid UnicodeEncodeError
- ⛔ After the revision is ready, run an explicit live HTTP probe against the ingress FQDN (`curl -sSfL`/`iwr` on `*.azurecontainerapps.io`) — this call IS the health check; capture the result into `deploy-result.json.endpoints[].healthStatus`.

## Code deploy — Static Web Apps (delete if not using SWA)
- ⛔ **Build before deploy (SPA only):** If the SWA component has a manifest (`package.json`) with a `build` script: detect the package manager from the lockfile, run install + build, then deploy the build output directory (not raw source). Plain HTML repos (no manifest): skip build, deploy source directly.
- ⛔ **Build-time env vars:** Before `npm run build`, set `VITE_API_BASE_URL` / `NEXT_PUBLIC_API_URL` / `REACT_APP_API_URL` to the deployed backend URL from `deploy-result.json.endpoints[]`. These are baked into the JS bundle at build time — runtime SWA env vars have no effect on client-side code.
- If frontend config references cloud SDK endpoints (AWS API Gateway, GCP), update with deployed Azure backend URLs from `deploy-result.json.endpoints[]` before `swa deploy`
- Use `swa deploy` (NOT `az staticwebapp deploy` — doesn't exist)
- `--app-name {swaName}` is mandatory
- Store token in $env:SWA_CLI_DEPLOYMENT_TOKEN — never as CLI arg

## During healing / retries
- ⛔ REGION LOCK: Deploy region MUST match plan region ({region}). Any region change → RE-PRESENT deploy approval gate with old and new region. Do NOT silently switch. After approval: update `prepare-plan.json.services[].region`, `deploymentVariables.location`, AND append attempt number to `naming.suffix` (e.g., `edd6` → `edd602`). Recompute ALL resource names from the new suffix before redeploying — globally unique names (App Service, Key Vault) from the old region may be soft-deleted and unavailable.
- ⛔ IaC-only: NEVER use `az containerapp update --image`, `az webapp update`, `az appservice plan delete`, or `az group create` — fix the Bicep and redeploy via `az deployment sub create`
- ⛔ IaC-only for app-managed roles: NEVER `az role assignment create` for AcrPull or KV Secrets User — Bicep-managed (deterministic GUID), so an imperative grant collides on redeploy (`RoleAssignmentExists`). Missing app role = fix the Bicep module and redeploy. (Deployer/subscription-scope 403s are the ONLY exception — see [`error-classification.md`](error-classification.md).)
- ⛔ **On error: read [`error-classification.md`](error-classification.md)** to classify the failure and follow the prescribed remediation. Do NOT ad-hoc heal without reading the classification.
- ⛔ **Never weaken a security control to unblock** — do NOT flip `require_secure_transport`/TLS, HTTPS-only, KV purge protection, or auth OFF to make a failing deploy pass. A DB TLS handshake failure = fix the client SSL config (prereq `W-MYSQL-SSL`) or ask the user; never downgrade the server.
- Count ALL attempts in deploy-result.json.healingAttempts[]
  After 3: STOP and ask user ("Yes / I have a suggestion / Stop")
- NEVER run `az group delete` — track in orphanedResourceGroups[]
- ⛔ **RG deletion timeout:** If you ran `az group delete --no-wait`, wait max 2 minutes then `ask_user`: "Resource group deletion is slow. Wait longer / Proceed without cleanup / Cancel." Do NOT poll indefinitely.
- Region/SKU/service changes require re-approval gate

## Before handoff (Step 8)
- ⛔ Read [`deploy-schemas.ts`](deploy-schemas.ts) for exact DeployResult field names
- Finalize `deploy-result.json` — overwrite skeleton IN PLACE (keep exact field names, do NOT rename): status (lowercase `succeeded`/`failed`), resourceGroupName, subscriptionId, deploymentNames (all used), resourceIds, endpoints, healthStatus (worst across endpoints), duration.completedUtc, resourceResults from `az deployment operation list`. Read back to verify.
- ⛔ `deployment-summary.md` — generate from `deploy-result.json` fields (Status, Health, Portal Links, Cleanup). NOT a separate data source.
- ⛔ `context.json` — add "deploy" to completedPhases, set currentPhase to null, update lastModifiedUtc. VERIFY by reading back.
- SCM re-disabled (App Service) or image param set (Container Apps)
- If prereq found migration frameworks: run migrations before declaring healthy

## Artifact verification (Step 8 — MANDATORY)
⛔ Before returning to orchestrator, verify ALL artifacts exist by reading each one back:
1. `deploy-result.json` — MUST contain (exact names): `status` (lowercase `succeeded`/`failed`), `resourceGroupName`, `subscriptionId`, `deploymentNames[]`, `resourceIds[]`, `endpoints[]`, `healthStatus`, `duration.completedUtc`, `resourceResults[]`. Missing/renamed fields → rewrite with real values NOW
2. `deploy-audit.log` — MUST exist with ≥2 entries (started + result for at least 1 command). Missing → reconstruct from memory
3. `deployment-summary.md` — MUST contain Status, Health, Portal Links sections. Missing → generate from deploy-result.json
4. `context.json` — MUST have `"deploy"` in `completedPhases`, `currentPhase: null`, updated `lastModifiedUtc`
5. ⛔ **Endpoint completeness** — EVERY service in `prepare-plan.json.services[]` that hosts application code MUST have a corresponding entry in `deploy-result.json.endpoints[]` with code deployed and a valid `healthStatus` (`healthy`, `degraded`, `unreachable`, `unknown`). If ANY compute endpoint is missing or has code not deployed, set `partial: true` and `status: "failed"`. A deployment with undeployed user components is NOT `"succeeded"`.

If ANY artifact is missing or incomplete, write it NOW — do NOT return to orchestrator without all 5 checks passing.

⛔ **Then STOP — return to orchestrator. No further CLI commands or skill invocations.**

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills · .github/plugins/azure-skills/skills/azure-app-onboard · commit 0696600

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from .github/plugins/azure-skills/LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

microsoft/azure-skills

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download azure-app-onboard.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Microsoft

Azure App Onboard

Quick Reference

When to Use This Skill

When NOT to Use

Pipeline Rules

Workflow

Error Handling

Files

deploy/references/deploy-checklist-template.md

Deploy Checklist Template (compaction-safe — generated at Step 5b)

How to generate

Requirements and compatibility

Security

Attribution and licence

Related skills

Shipping And Launch

Quantized Export

Deployment Pipeline Design

Gitops Workflow

Spark Environment Setup

Cloud Infrastructure Deployment Engineer

Download ZIP