Azure Deployment Standards

Naming Conventions

⚠️ CRITICAL: Always use the azure-naming-research skill to lookup CAF abbreviations and Azure naming constraints before suggesting or validating resource names.

Use consistent CAF-compliant naming patterns across all Azure resources:

Standard Format:

{resource-type-abbreviation}-{project}-{environment}-{region}[-{instance}]

Resource Groups:

• CAF abbreviation: rg
• Format: rg-{project}-{environment}-{region}
• Example: rg-webapp-prod-eastus
• Constraints: 1-90 chars, alphanumeric + hyphens + underscores + periods

Function Apps:

• CAF abbreviation: func
• Format: func-{project}-{environment}-{region}
• Example: func-api-dev-westus2
• Constraints: 2-60 chars, alphanumeric + hyphens, globally unique

Storage Accounts:

• CAF abbreviation: st
• Format: st{project}{env}{random} (lowercase, no hyphens, max 24 chars)
• Example: stwebappdev8k3m
• Constraints: 3-24 chars, lowercase alphanumeric only, globally unique
• Special: Use uniqueString(resourceGroup().id) for uniqueness

App Service Plans:

• CAF abbreviation: asp
• Format: asp-{project}-{environment}-{region}
• Example: asp-webapp-prod-eastus

Web Apps:

• CAF abbreviation: app
• Format: app-{project}-{environment}-{region}
• Example: app-webapp-prod-eastus
• Constraints: 2-60 chars, alphanumeric + hyphens, globally unique

SQL Servers:

• CAF abbreviation: sql
• Format: sql-{project}-{environment}-{region}
• Example: sql-webapp-prod-eastus
• Constraints: 1-63 chars, lowercase alphanumeric + hyphens, globally unique

SQL Databases:

• CAF abbreviation: sqldb
• Format: sqldb-{project}-{environment}
• Example: sqldb-webapp-prod

Cosmos DB:

• CAF abbreviation: cosmos
• Format: cosmos-{project}-{environment}-{region}
• Example: cosmos-webapp-prod-eastus
• Constraints: 3-44 chars, lowercase alphanumeric + hyphens, globally unique

Application Insights:

• CAF abbreviation: appi
• Format: appi-{project}-{environment}-{region}
• Example: appi-webapp-prod-eastus

Key Vaults:

• CAF abbreviation: kv
• Format: kv-{project}-{env}-{region}
• Example: kv-webapp-prod-eus (shortened region for length)
• Constraints: 3-24 chars, alphanumeric + hyphens, globally unique

Log Analytics Workspaces:

• CAF abbreviation: log
• Format: log-{project}-{environment}-{region}
• Example: log-webapp-prod-eastus
• Constraints: 4-63 chars, alphanumeric + hyphens, must start/end with alphanumeric

Container Apps Environments:

• CAF abbreviation: cae
• Format: cae-{project}-{environment}-{region}
• Example: cae-api-prod-eastus
• Constraints: 1-60 chars, alphanumeric + hyphens
• Note: Requires a Log Analytics workspace for app logs

Container Apps:

• CAF abbreviation: ca
• Format: ca-{project}-{environment}-{region}
• Example: ca-api-prod-eastus
• Constraints: 2-32 chars, lowercase alphanumeric + hyphens, must start with letter

Naming Workflow:

1. Before naming ANY resource:

   # Use the azure-naming-research skill
   /azure-naming-research {resource-type}
   
   # Example:
   /azure-naming-research "Azure Functions"
   
   # Returns: CAF abbreviation, length constraints, valid characters, scope

2. Construct name using pattern:

   {caf-abbrev}-{project}-{env}-{region}

3. Validate against constraints:
   • Length (min-max)
   • Character set (alphanumeric, hyphens, etc.)
   • Uniqueness scope (global, resource group, subscription)
   • Start/end character requirements
4. For globally unique resources (Storage, Functions, SQL, Cosmos, Key Vault):
   • Add random suffix if needed: {name}-${random}
   • Or use ARM's uniqueString() function in templates

Reference:

• CAF Abbreviations: https://learn.microsoft.com/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
• Naming Rules: https://learn.microsoft.com/azure/azure-resource-manager/management/resource-name-rules

Default Regions

Prefer these regions for deployments unless specified otherwise:

• Primary: East US
• Secondary: West US 2
• Europe: West Europe

Environment Tags

Always include these tags on all resources:

{
  "Environment": "dev|staging|prod",
  "Project": "project-name",
  "ManagedBy": "git-ape-agent",
  "CreatedDate": "YYYY-MM-DD"
}

ARM Template Standards

• Include parameters section for configurable values
• Use outputs section to return resource IDs and endpoints
• Apply Azure best practices via bestpractices service validation
• Include resource health monitoring configurations
• Always use /azure-rest-api-reference to look up resource properties and API versions before writing or modifying ARM template resources — never rely on memorized property names or schemas
• Subscription-level templates (subscriptionDeploymentTemplate.json) must use nested deployments with "expressionEvaluationOptions": { "scope": "inner" } — without this, reference() and resourceId() resolve at subscription scope, causing ResourceNotFound errors at deploy time
• All reference() calls inside nested templates must include explicit API versions (e.g., reference(resourceId(...), '2024-03-01'))
• Pass all parent-scope values (parameters, variables) as explicit parameters to nested templates — never reference parent variables directly from inner-scope templates

Deployment Workflow

Interactive Mode (VS Code / local CLI)

1. Requirements Gathering: Collect all necessary parameters before generating templates
2. Template Validation: Always validate ARM templates before deployment
3. User Confirmation: Echo deployment intent and wait for explicit approval
4. Deployment Execution: Invoke the azure-stack-deploy skill, which deploys as a subscription-scoped Azure Deployment Stack (az stack sub create --action-on-unmanage deleteAll). This is the same primitive used by the CI workflows so local and pipeline deployments produce identical state. The skill captures the stack ID, managed resources, soft-deletable resources, and resource groups into state.json (schemaVersion 1.0). It falls back to az deployment sub create only if Deployment Stacks are unavailable in the target subscription/region. Both bash (scripts/deploy-stack.sh) and PowerShell (scripts/deploy-stack.ps1) implementations are provided.
5. State Persistence: The deploy skill writes state.json and updates metadata.json with deployMethod (stack or subscription) and resourceGroups[]. Schema reference: website/docs/deployment/state.md.
6. Integration Testing: Run health checks on deployed resources
7. Destroy: Invoke the azure-stack-destroy skill (or @git-ape destroy deployment {deployment-id}). The skill mirrors the CI workflow exactly: az stack sub delete --action-on-unmanage deleteAll --bypass-stack-out-of-sync-error true (single command, idempotent across resource groups and subscription scope), purges any soft-deletable resources that are not purge-protected (Key Vault, Cognitive Services, etc.), then cleans the subscription deployment history entry to stay under the 800/scope limit. Both bash (scripts/destroy-stack.sh) and PowerShell (scripts/destroy-stack.ps1) implementations are provided.

Pipeline Mode (GitHub Actions)

Git-Ape provides three GitHub Actions workflows under .github/workflows/:

git-ape-plan.yml — Validate & Preview

Triggers: PR opened or updated with changes to .azure/deployments/**/template.json

What it does:

1. Detects which deployment directories changed in the PR
2. Logs into Azure via OIDC
3. Validates each ARM template (az stack sub validate)
4. Runs what-if analysis (az deployment sub what-if)
5. Reads the architecture diagram from the deployment directory
6. Posts a detailed plan as a PR comment (validation result + what-if + architecture)
7. Updates the comment on subsequent pushes (idempotent via HTML marker)

PR comment includes:

• Validation status (pass/fail with errors)
• Architecture diagram (from architecture.md)
• What-if analysis (resources to create/modify/delete)
• Next steps (approve + merge to deploy)

git-ape-deploy.yml — Execute Deployment

Triggers:

• Push to main with deployment file changes (PR merge)

What it does:

1. Detects deployment directories to execute
2. Logs into Azure via OIDC
3. Validates the template one more time (az stack sub validate)
4. Deploys as an Azure Deployment Stack (az stack sub create --action-on-unmanage deleteAll; falls back to az deployment sub create if stacks are unavailable)
5. Captures the stack ID, managed resources, soft-deletable resources, and resource groups into state.json
6. Runs integration tests (lists deployed resources, tests HTTP endpoints)
7. Commits state.json (extended schema, including stackId and managedResources[]) and metadata.json (deployMethod, resourceGroups[]) back to the repo
8. Posts deployment result as a PR comment

Why Deployment Stacks:

• The stack is the single unit of lifecycle — create, update, and destroy operate on it, not on the underlying RGs.
• deleteAll on unmanage guarantees destruction cleans up every managed resource across every scope (subscription, multiple RGs, role/policy assignments at sub scope) in one call. No orphans, idempotent re-runs.
• See Azure/git-ape#30 for the rationale.

Requires: GitHub environment azure-deploy (for environment protection rules)

Safety:

• Deployment only runs after merge to main, which requires PR approval via branch protection
• Deployments run sequentially (max-parallel: 1) to prevent conflicts
• In-progress deployments are never cancelled (cancel-in-progress: false)

git-ape-destroy.yml — Tear Down Resources

Triggers:

• Push to main with changes to metadata.json where status is destroy-requested (PR merge)
• Manual workflow dispatch with deployment ID + "destroy" confirmation (emergency fallback)

What it does:

1. Detects deployments where metadata.json status changed to destroy-requested
2. Reads state.json to find the deployment stack name (deploymentId) and stackId
3. Calls az stack sub show to inventory the stack's managed resources
4. Calls az stack sub delete --action-on-unmanage deleteAll — removes every resource the stack manages, across all scopes, in one synchronous call
5. Updates state.json and metadata.json with destroyed status and commits to repo

Idempotency:

• If the stack is already gone, the workflow records already-destroyed and succeeds cleanly.
• No RG-delete fallback path, no subscription-scope resource sweep — Stacks handle multi-scope destruction natively.

Destroy flow:

1. Agent or user creates a PR that sets metadata.json status to destroy-requested
2. PR is reviewed and approved (human gate for destructive action)
3. On merge to main, the workflow detects the status change and executes deletion

Requires: GitHub environment azure-destroy (for environment protection rules)

Copilot Coding Agent Flow

When the Copilot Coding Agent processes a deployment request:

Issue: "Deploy a Container App in Southeast Asia, project myapp"
                    │
                    ▼
    ┌───────────────────────────────┐
    │  Coding Agent (on branch)     │
    │  1. Parse requirements        │
    │  2. Generate ARM template     │
    │  3. Generate architecture.md  │
    │  4. Commit to branch          │
    │  5. Open PR                   │
    └───────────────┬───────────────┘
                    │ PR opened
                    ▼
    ┌───────────────────────────────┐
    │  git-ape-plan.yml           │
    │  1. Validate template         │
    │  2. Run what-if               │
    │  3. Post plan as PR comment   │
    └───────────────┬───────────────┘
                    │ User reviews plan
                    ▼
    ┌───────────────────────────────┐
    │  User approves & merges PR    │
    │  → deploy on merge to main    │
    └───────────────┬───────────────┘
                    │
                    ▼
    ┌───────────────────────────────┐
    │  git-ape-deploy.yml         │
    │  1. OIDC login                │
    │  2. Deploy ARM template       │
    │  3. Integration tests         │
    │  4. Commit state.json         │
    │  5. Post result as comment    │
    └───────────────┬───────────────┘
                    │
                    ▼
    ┌───────────────────────────────┐
    │  Teardown (when needed)       │
    │  PR: set metadata.json        │
    │  status → destroy-requested   │
    │  Merge → git-ape-destroy    │
    └───────────────────────────────┘

GitHub Environment Setup

Create two GitHub environments for protection rules:

azure-deploy:

• Required reviewers (optional — for prod deployments)
• Deployment branches: main only (for merge trigger)

azure-destroy:

• Required reviewers (recommended — destructive action)
• Deployment branches: main only (triggered on PR merge)

Security Baseline

• Enable HTTPS-only for all web-facing resources
• Always use managed identities — never use connection strings, storage keys, or shared access keys
• For Function Apps, use AzureWebJobsStorage__accountName (identity-based) instead of AzureWebJobsStorage (key-based)
• Set allowSharedKeyAccess: false on storage accounts when all consumers use managed identity
• Include RBAC role assignments in ARM templates when resources access each other

Deployment Error Recovery Rule

When a deployment fails, never weaken security controls to fix it. Specifically:

• Do NOT re-enable shared key access, disable firewalls, open NSGs, remove authentication, or downgrade TLS to work around errors
• Do NOT replace identity-based access with connection strings or shared keys
• Instead: verify RBAC roles are complete, check for Azure Policy conflicts, check resource dependencies and ordering, and ensure managed identities exist before dependent resources try to use them
• If the secure path genuinely cannot work, stop and ask the user — do not silently regress

Security Gate Re-Run Rule

Any modification to a template after the initial security analysis MUST trigger a full security gate re-run before deployment. A template that passed the gate at version N is not pre-approved at version N+1.

• Use AAD-only authentication for SQL databases (azureADOnlyAuthentication: true)
• Use Key Vault references for secrets in app settings (@Microsoft.KeyVault(...))
• Enable diagnostic logging and monitoring
• Apply least-privilege RBAC roles (use /azure-role-selector skill)
• Disable FTP on all App Services and Function Apps (ftpsState: Disabled)
• Set minimum TLS version to 1.2 on all resources

Security Analysis Integrity

All security reports and assessments produced by Git-Ape agents and skills MUST be factually accurate and verifiable against the actual ARM template or Azure resource configuration.

Compliance & Azure Policy

Compliance Frameworks

• Primary: General Azure best practices
• Optionally adopt: CIS Azure Foundations v3.0, NIST SP 800-53 Rev 5, or other regulatory initiatives

Policy Enforcement Mode

• Default: Audit (use Audit/AuditIfNotExists effects for initial rollout)
• Production hardening: Deny (use Deny effects for Critical-severity policies once audit baselines are clean)

Policy Categories

Always assess and recommend policies for: identity, networking, storage, compute, monitoring, tagging.

Policy Advisor Integration

• Use /azure-policy-advisor skill to assess ARM templates against compliance frameworks
• Query Microsoft Learn for current built-in policy definitions — do not hardcode policy IDs
• Output policy-assessment.md and policy-recommendations.json to deployment directory
• Policy gate is advisory (not blocking) — surfaces findings without halting deployment
• During onboarding, ask the user about compliance framework and enforcement mode preferences and update this section accordingly

Rules

1. Cite evidence: Every "✅ Applied" finding must reference the exact ARM property path and value from the template. No exceptions.
2. Platform defaults ≠ explicit config: Azure automatic controls (e.g., SSE at rest on managed disks) must be labeled "🔄 Platform Default", not "✅ Applied."
3. Honest framing: If a resource has a public IP, it IS internet-facing. If a port is open with IP restriction, the port IS open. Never soften or misrepresent exposure.
4. Verify before presenting: Always re-read the ARM template and cross-check every security finding before showing it to the user. Remove or correct anything that doesn't match.
5. When uncertain, say so: Use "❓ Unknown" if a status cannot be verified. Never fabricate findings.

Security Gate (Blocking)

Security analysis is a blocking deployment gate. Deployment CANNOT proceed until all Critical and High severity checks pass.

• 🟢 SECURITY GATE: PASSED — All Critical and High checks are ✅ Applied or 🔄 Platform Default. Deployment may proceed.
• 🔴 SECURITY GATE: BLOCKED — One or more Critical or High checks are ⚠️ Not applied or ❌ Misconfigured. Deployment is blocked until resolved.

When blocked, the user must either:

1. Accept proposed auto-fixes and re-run the full security analysis, or
2. Provide alternative security settings and re-run the full security analysis, or
3. Explicitly override by typing "I accept the security risk" (logged as OVERRIDDEN with justification)

The gate loops until PASSED or overridden — no shortcutting allowed.

Azure Authentication

Git-Ape supports multiple execution contexts. Always use the most secure auth method available.

Auth Method Priority

OIDC Setup for GitHub Actions

OIDC eliminates stored secrets by exchanging a short-lived GitHub token for an Azure access token at deploy time.

One-time Azure setup:

1. Create an Azure AD App Registration (or User-Assigned Managed Identity)
2. Add a federated credential for the GitHub repo:
   • Issuer: https://token.actions.githubusercontent.com
   • Subject: repo:{org}/{repo}:ref:refs/heads/main (or environment:production for env-scoped)
   • Audience: api://AzureADTokenExchange
3. Grant the app the required RBAC roles on the target subscription (e.g., Contributor + User Access Administrator)

Required GitHub secrets (NOT actual credentials — just identifiers):

• AZURE_CLIENT_ID — App Registration's Application (client) ID
• AZURE_TENANT_ID — Azure AD tenant ID

Required GitHub variable:

• AZURE_SUBSCRIPTION_ID — Target subscription ID (a repository/environment variable, read via vars.)

Workflow snippet:

permissions:
  id-token: write    # Required for OIDC token request
  contents: write    # Required for committing deployment state

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      - name: Deploy
        run: |
          az stack sub create \
            --name ${{ env.DEPLOYMENT_ID }} \
            --location ${{ env.LOCATION }} \
            --template-file .azure/deployments/${{ env.DEPLOYMENT_ID }}/template.json \
            --parameters @.azure/deployments/${{ env.DEPLOYMENT_ID }}/parameters.json \
            --action-on-unmanage deleteAll \
            --deny-settings-mode none \
            --description "Git-Ape deployment ${{ env.DEPLOYMENT_ID }}" \
            --tags "managedBy=git-ape" "deploymentId=${{ env.DEPLOYMENT_ID }}" \
            --yes \
            --verbose

Transitioning from Service Principal secrets to OIDC:

1. Create the federated credential on the existing App Registration
2. Update the workflow to use azure/login@v2 with client-id instead of creds
3. Add permissions.id-token: write to the workflow
4. Remove AZURE_CREDENTIALS secret from the repo
5. Verify with a test deployment on a dev branch

Copilot Coding Agent Considerations

When Git-Ape runs inside the Copilot Coding Agent:

• The agent operates on a branch and creates a PR — it cannot interactively confirm with the user
• Authentication must be pre-configured via OIDC in the Actions workflow
• All deployment plans should be committed as files in the PR for review
• Actual deployment should happen on merge to main (via a separate workflow)
• The agent should generate the template + what-if analysis but NOT execute deployment unless the workflow is explicitly configured to do so