Azure Stack Deploy Agent Skill

Azure Stack Deploy

Deploy a Git-Ape deployment artifact as a subscription-scoped Azure Deployment Stack (az stack sub create --action-on-unmanage deleteAll). The stack is the lifecycle owner of every resource the template creates — across resource groups and subscription scope — which makes destroy idempotent in a single call (see azure-stack-destroy).

This skill produces the same state.json schema (schemaVersion: "1.0") as the CI workflow at .github/workflows/git-ape-deploy.yml, so local deployments and pipeline deployments are interchangeable.

When to Use

• Local deployment from VS Code or terminal (the git-ape agent invokes this in Stage 3)
• Re-deploying an existing deployment ID after template edits — stacks are stateful, so this is an in-place update
• Any time you would otherwise run az deployment sub create against a Git-Ape template.json

Do NOT use for

• Tearing down / destroying an existing deployment — use azure-stack-destroy instead
• What-if preview / preflight validation without deploying — use azure-deployment-preflight instead
• Off-topic (non-Azure, non-deployment) requests
• Generating or editing ARM templates — use azure-prepare or another IaC authoring skill

Prerequisites

| Tool | Why |

|------|-----|

| az (Azure CLI ≥ 2.59) | az stack sub requires CLI ≥ 2.50; 2.59 has the latest stack flags |

| jq | State capture and JSON extraction |

| bash ≥ 4 OR PowerShell 7+ | Either runner works |

| Active az login | Skill exits early if no subscription is selected |

| Existing template.json (and optional parameters.json) under .azure/deployments/<id>/ | Source artifacts |

Procedure

1. Locate deployment artifacts

DEPLOYMENT_ID="deploy-20260506-001"
DEPLOYMENT_PATH=".azure/deployments/$DEPLOYMENT_ID"

[[ -f "$DEPLOYMENT_PATH/template.json" ]] || { echo "template.json missing"; exit 1; }

If parameters.json is present, location, project (or projectName), and environment are read from it. Defaults: eastus / unknown / dev.

2. Run the script

.github/skills/azure-stack-deploy/scripts/deploy-stack.sh \
  --deployment-id "$DEPLOYMENT_ID"

PowerShell equivalent:

.github/skills/azure-stack-deploy/scripts/deploy-stack.ps1 `
  -DeploymentId "$DEPLOYMENT_ID"

The script:

• Resolves location, project, environment from parameters.json (or defaults)
• Validates Azure CLI session (az account show)
• Calls az stack sub create with the canonical Git-Ape flag set:
• --action-on-unmanage deleteAll
• --deny-settings-mode none
• --description "Git-Ape deployment <id>"
• --tags managedBy=git-ape deploymentId=<id>
• --yes --verbose
• On stack failure, falls back to az deployment sub create and prints ⚠️ FALLBACK: no multi-RG idempotency, no soft-delete tracking so the trade-off is unambiguous
• On any deployment failure, dumps the per-operation failure list (az deployment operation sub list) inline so the root cause is visible without clicking into the Portal
• On success, queries az stack sub show --query "resources[].id" for the live managed-resource list, classifies each resource (type, scope, soft-deletable, purge-protected), and writes the extended state.json
• Updates metadata.json with status: "succeeded", deployMethod, and resourceGroups[]

3. Inspect output

✅ Deployment succeeded in 142s (method: stack)
State written to: .azure/deployments/deploy-20260506-001/state.json
Stack ID: /subscriptions/<sub>/providers/Microsoft.Resources/deploymentStacks/deploy-20260506-001

To destroy this deployment:
  /azure-stack-destroy deploy-20260506-001

What to tell the user after running

After the script returns, your reply MUST mention:

• The primitive used: az stack sub create --action-on-unmanage deleteAll (or fallback az deployment sub create)
• The stack ID (from state.json.stackId) — this is the single handle for destroy
• That state.json (schemaVersion 1.0) was written under the deployment folder
• The next-step destroy command: /azure-stack-destroy <deploymentId>

Arguments

| Flag (bash) | Param (pwsh) | Required | Description |

|-------------|--------------|----------|-------------|

| --deployment-id <id> | -DeploymentId <id> | yes | Folder name under .azure/deployments/ |

| --location <region> | -Location <region> | no | Override the location from parameters.json |

| --no-fallback | -NoFallback | no | Fail loudly if the stack call fails instead of falling back to az deployment sub create |

state.json schema (v1.0)

{
  "schemaVersion": "1.0",
  "deploymentId": "deploy-20260506-001",
  "timestamp": "2026-05-06T12:00:00Z",
  "status": "succeeded",
  "duration": "142s",
  "subscription": "<sub-id>",
  "location": "eastus",
  "project": "myapp",
  "environment": "dev",
  "resourceGroup": "rg-myapp-dev-eastus",
  "deployMethod": "stack",
  "stackId": "/subscriptions/<sub>/providers/Microsoft.Resources/deploymentStacks/deploy-20260506-001",
  "managedResources": [
    {
      "id": "/subscriptions/<sub>/resourceGroups/rg-myapp-dev-eastus/providers/Microsoft.KeyVault/vaults/kv-myapp-dev-eus",
      "type": "Microsoft.KeyVault/vaults",
      "scope": "resourceGroup",
      "softDeletable": true,
      "purgeProtected": true
    }
  ],
  "resourceGroups": ["rg-myapp-dev-eastus"],
  "subscriptions": ["<sub-id>"],
  "externalReferences": []
}

See website/docs/deployment/state.md for the full schema reference.

Soft-deletable resource types tracked

Microsoft.KeyVault/vaults, Microsoft.CognitiveServices/accounts, Microsoft.AppConfiguration/configurationStores, Microsoft.ApiManagement/service, Microsoft.MachineLearningServices/workspaces, Microsoft.RecoveryServices/vaults.

The destroy skill (azure-stack-destroy) consumes the softDeletable and purgeProtected fields to drive its purge sweep.

Failure modes

| Symptom | Likely cause | Recovery |

|---------|--------------|----------|

| Not logged in to Azure | az login missing | Run az login then retry |

| template.json missing | Wrong deployment ID | Check .azure/deployments/ contents |

| Stack create fails immediately | Region/policy blocks Deployment Stacks | Re-run without --no-fallback, accept the legacy path, or pick a supported region |

| Stack succeeds but state.json missing managed resources | az stack sub show race condition | Re-run — the script is idempotent (stacks de-duplicate on --name) |

Related

• azure-stack-destroy — the matching destroy skill (single source of truth: stackId)
• azure-deployment-preflight — what-if and permission checks BEFORE deploy
• azure-security-analyzer — security gate (BLOCKING) before deploy confirmation