Azure Integrations

Tech Stack Target / Version: Azure Static Web Apps, App Service, Bicep or ARM templates, GitHub Actions, Node.js 20+, and Azure CLI 2.60+.

Deployment and integration patterns for Azure cloud services, focusing on web application hosting, CI/CD automation, and infrastructure as code.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

When to Use This Skill

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

• Deploying Next.js or Vite/React apps to Azure
• Setting up CI/CD workflows with GitHub Actions
• Configuring Azure Static Web Apps or App Service
• Managing Azure Blob Storage for file uploads
• Using Azure Key Vault for secure secrets management
• Setting up Application Insights for monitoring
• Writing Bicep or ARM templates for infrastructure as code
• Integrating Azure Cosmos DB (MongoDB API) with applications

<!-- MCP:START --> <!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

• GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the workflow in project instructions when folder discovery is unavailable.
• Claude Code: keep the folder in a local skills directory or a compatible plugin source.
• Codex: install or sync the folder into $CODEX_HOME/skills/azure-integrations and restart Codex after major changes.

<!-- PORTABILITY:END -->

MCP Availability And Fallback

Preferred MCP Server: Azure MCP

• Fallback prompt: "Use the Azure Integrations skill without MCP. Follow the documented local or manual fallback, show the selected tool surface, and report the verification evidence."
• Use Azure CLI (az), Bicep or ARM templates, and the bundled PowerShell deployment scripts in this skill when the MCP server is unavailable.
• Validate resources with az queries, deployment logs, and portal checks before closing the task.
• Do not claim an MCP operation was used when the active host does not expose it.

<!-- MCP:END -->

Anti-Patterns

• Changing infrastructure before inspecting the current state: Cloud drift and hidden dependencies make blind edits risky.
• Hardcoding credentials or environment assumptions: Rollouts stop being reproducible and secrets become harder to rotate.
• Skipping rollback, observability, or validation planning: You only notice the missing safeguards after the deployment is already live.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Azure Integrations implementation names the target runtime, framework version, and affected files.
2. Pass/fail: Build, lint, test, or equivalent local validation is run for the changed surface.
3. Pass/fail: Edge cases for errors, dependency drift, and environment differences are addressed or explicitly out of scope.
4. Pressure-test scenario: Apply the workflow to a change that passes happy-path tests but fails one boundary condition.
5. Success metric: Zero untested success claims; every implementation claim maps to a command or artifact.

Available Deployment Scripts

• examples/vite-swa-deployment.md - Vite/React to Static Web Apps
• examples/nextjs-app-service-deployment.md - Next.js to App Service with Key Vault, App Insights, Storage
• scripts/deploy-swa.ps1 - PowerShell deployment script for SWA
• scripts/deploy-appservice.ps1 - PowerShell deployment script for App Service

Reference Documentation

• references/bicep-quickref.md - Bicep template patterns and syntax
• references/github-actions-azure.md - GitHub Actions patterns for Azure deployments

---

Azure Static Web Apps

Deployment Setup

name: Deploy to Azure Static Web Apps

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches: [main]

jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build and Deploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: "upload"
          app_location: "/"
          api_location: "api"
          output_location: "dist"

Configuration (staticwebapp.config.json)

{
  "routes": [
    { "route": "/api/*", "allowedRoles": ["authenticated"] },
    { "route": "/*", "serve": "/index.html", "statusCode": 200 }
  ],
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/api/*", "*.{css,js,png,jpg,svg,ico}"]
  },
  "globalHeaders": {
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY",
    "Content-Security-Policy": "default-src 'self'"
  },
  "responseOverrides": {
    "401": { "redirect": "/login", "statusCode": 302 }
  }
}

Best Practices

• Use staging environments for PR previews
• Configure custom domains with SSL
• Set up authentication providers (Azure AD, GitHub, etc.)
• Use API routes for serverless backend functions

---

Azure App Service

Full end-to-end deployment guide with Key Vault integration, Application Insights, and Azure Storage available in examples/nextjs-app-service-deployment.md.

Quick Reference

| Resource | Purpose | |-----------|---------| | App Service Plan | Linux hosting for Node.js apps | | Web App | Next.js application instance | | Key Vault | Secure secrets management (MongoDB URI, auth secrets) | | Storage Account | File uploads (recipe images) | | Application Insights | Monitoring and telemetry | | Managed Identity | Service-to-service authentication (no passwords) |

PowerShell Deployment Script

Automated deployment script: scripts/deploy-appservice.ps1

.\deploy-appservice.ps1 -AppName "my-app" -ResourceGroup "rg-my-app" -Sku S1 -EnableAppInsights -EnableStorage

Deployment Workflow

name: Deploy Next.js to App Service

on:
  push:
    branches: [main]

permissions:
  id-token: write   # Required for OIDC authentication

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install and Build
        run: |
          npm ci
          npm run build

      - name: Azure Login (OIDC)
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Deploy to App Service
        uses: azure/webapps-deploy@v3
        with:
          app-name: kitchen-odyssey
          package: .

Key Features Covered in Full Guide

• ✅ Zero-downtime deployments with deployment slots
• ✅ Key Vault integration for secure secrets
• ✅ Managed Identity authentication (no secrets in app settings)
• ✅ Application Insights for monitoring and telemetry
• ✅ Azure Storage for file uploads with CORS
• ✅ Bicep infrastructure as code templates
• ✅ Production-ready security headers
• ✅ Automated CI/CD with GitHub Actions

App Settings (Key Vault Pattern)

az webapp config appsettings set --name <app-name> --resource-group <rg> --settings \
  AZURE_KEYVAULT_RESOURCEENDPOINT="https://<vault-name>.vault.azure.net" \
  AZURE_CLIENTID="<Managed-Identity-Client-ID>" \
  NEXTAUTH_URL="https://<app-name>.azurewebsites.net" \
  NODE_ENV="production"

Legacy Pattern (not recommended - secrets exposed in app settings):

az webapp config appsettings set --name <app-name> --resource-group <rg> --settings \
  MONGODB_URI="mongodb+srv://..." \
  NEXTAUTH_SECRET="..."

---

Azure Blob Storage

Upload Integration

import { BlobServiceClient } from '@azure/storage-blob';

const blobServiceClient = BlobServiceClient.fromConnectionString(
  process.env.AZURE_STORAGE_CONNECTION_STRING
);

export async function uploadFile(containerName, fileName, buffer, contentType) {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  await containerClient.createIfNotExists({ access: 'blob' });

  const blockBlobClient = containerClient.getBlockBlobClient(fileName);
  await blockBlobClient.uploadData(buffer, {
    blobHTTPHeaders: { blobContentType: contentType },
  });

  return blockBlobClient.url;
}

export async function deleteFile(containerName, fileName) {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blockBlobClient = containerClient.getBlockBlobClient(fileName);
  await blockBlobClient.deleteIfExists();
}

export async function generateSasUrl(containerName, fileName, expiresInMinutes = 60) {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(fileName);

  const sasUrl = await blobClient.generateSasUrl({
    permissions: BlobSASPermissions.parse('r'),
    expiresOn: new Date(Date.now() + expiresInMinutes * 60 * 1000),
  });

  return sasUrl;
}

---

Bicep Templates

Web App + Cosmos DB

@description('The name of the web app')
param appName string

@description('The location for resources')
param location string = resourceGroup().location

@description('The SKU of the App Service Plan')
param sku string = 'B1'

resource appServicePlan 'Microsoft.Web/serverfarms@2023-01-01' = {
  name: '${appName}-plan'
  location: location
  sku: {
    name: sku
  }
  properties: {
    reserved: true
  }
  kind: 'linux'
}

resource webApp 'Microsoft.Web/sites@2023-01-01' = {
  name: appName
  location: location
  properties: {
    serverFarmId: appServicePlan.id
    siteConfig: {
      linuxFxVersion: 'NODE|20-lts'
      appSettings: [
        { name: 'MONGODB_URI', value: cosmosDb.listConnectionStrings().connectionStrings[0].connectionString }
        { name: 'NODE_ENV', value: 'production' }
      ]
    }
  }
}

resource cosmosDb 'Microsoft.DocumentDB/databaseAccounts@2023-04-15' = {
  name: '${appName}-db'
  location: location
  kind: 'MongoDB'
  properties: {
    databaseAccountOfferType: 'Standard'
    capabilities: [{ name: 'EnableMongo' }]
    locations: [{ locationName: location, failoverPriority: 0 }]
  }
}

output webAppUrl string = 'https://${webApp.properties.defaultHostName}'

Deployment

az deployment group create \
  --resource-group myResourceGroup \
  --template-file main.bicep \
  --parameters appName=my-recipe-app

---

GitHub Actions CI/CD Patterns

Multi-Environment Pipeline

name: CI/CD Pipeline

on:
  push:
    branches: [main, staging]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm run lint
      - run: npm run test

  deploy-staging:
    needs: test
    if: github.ref == 'refs/heads/staging'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: azure/webapps-deploy@v3
        with:
          app-name: ${{ secrets.STAGING_APP_NAME }}
          publish-profile: ${{ secrets.STAGING_PUBLISH_PROFILE }}

  deploy-production:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: azure/webapps-deploy@v3
        with:
          app-name: ${{ secrets.PROD_APP_NAME }}
          publish-profile: ${{ secrets.PROD_PUBLISH_PROFILE }}

---

Troubleshooting

| Issue | Solution | |-------|----------| | SWA deployment fails | Check output_location matches build output directory | | App Service 500 errors | Check application logs: az webapp log tail | | Blob upload CORS | Configure CORS rules on storage account | | Bicep deployment error | Validate: az bicep build --file main.bicep | | Environment variables missing | Check App Settings in Azure Portal | | Cold start latency | Use Always On for App Service, or premium SWA tier |

---

References & Resources

Documentation

• Bicep Quick Reference — Bicep template patterns, resource declarations, modules, and common Azure resource examples
• GitHub Actions for Azure — GitHub Actions workflows for Azure deployments, OIDC setup, multi-stage pipelines

Scripts

• Deploy to Azure SWA — PowerShell script to deploy Vite/React or Next.js apps to Azure Static Web Apps

Examples

• Vite SWA Deployment Guide — End-to-end walkthrough deploying a Vite+React app to Azure Static Web Apps

---

Related Skills

• powerbi-modeling: Use it when the workflow also needs Power BI semantic model design and DAX work.
• microsoft-development: Use it when the workflow also needs microsoft development guidance.
• sql-development: Use it when the workflow also needs SQL query, schema, and performance tuning work.
• documentation-authoring: Use it when the workflow also needs drafting structured technical or product documents.