Heroku to Azure App Service Migration

Detailed guidance for migrating Heroku applications to Azure App Service.

Service Mapping

Dyno → App Service Plan Mapping

Procfile → Startup Configuration

Web Process

Worker Process

Heroku worker dynos have no direct App Service equivalent. Migration paths:

Add-ons → Azure Managed Services

Config Vars → App Configuration / Key Vault

⚠️ Warning: Heroku's DATABASE_URL includes credentials. On Azure, use managed identity authentication instead. Never migrate connection strings with embedded passwords.

Buildpacks → Docker

For apps using standard runtimes, use App Service runtime stacks directly. For custom buildpacks, migrate to Docker:

Heroku Pipelines → GitHub Actions

Example: GitHub Actions Deployment

name: Deploy to App Service
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # Required for azure/login@v2 OIDC token request
      contents: read    # Required to checkout the repo
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - uses: azure/webapps-deploy@v3
        with:
          app-name: '<app-name>'
          slot-name: 'staging'

⚠️ Without the permissions: block, azure/login@v2's OIDC token request fails with HTTP 403.

Review Apps → Deployment Slots

Reference Links

• Heroku to Azure migration guide
• App Service deployment slots
• GitHub Actions for App Service
• App Service managed identity