ZIP Deploy and Run From Package¶

Use ZIP Deploy when you already have a prepared deployment artifact and want to push it directly to App Service without introducing a full CI/CD system. For production workloads, pair ZIP Deploy with immutable packages and explicit validation.

Main Content¶

ZIP Deploy Flow¶

flowchart TD
    A[Build app artifact locally or in CI] --> B[Create ZIP package without parent folder]
    B --> C[az webapp deploy --type zip]
    C --> D{WEBSITE_RUN_FROM_PACKAGE enabled?}
    D -- Yes --> E[Package mounted read-only]
    D -- No --> F[Files extracted into wwwroot]
    E --> G[Restart app]
    F --> G
    G --> H[Run smoke test]

When ZIP Deploy Fits Best¶

• You already have a tested ZIP artifact from another pipeline.
• You want a direct CLI-driven deployment method.
• You need deterministic package promotion without rebuilding in App Service.
• You want to combine artifact deployment with deployment slots.

ZIP Deploy vs az webapp up¶

Use az webapp up for first-time experimentation or tutorials. Use ZIP Deploy when the app already exists and you want explicit control over the artifact, restart timing, and release flow.

Enable WEBSITE_RUN_FROM_PACKAGE¶

WEBSITE_RUN_FROM_PACKAGE=1 tells App Service to run from a mounted package instead of relying on mutable file copies in wwwroot. This improves consistency and reduces partial-copy or file-lock issues during deployment.

az webapp config appsettings set \
  --resource-group $RG \
  --name $APP_NAME \
  --settings WEBSITE_RUN_FROM_PACKAGE=1 SCM_DO_BUILD_DURING_DEPLOYMENT=false \
  --output json

Portal view: Environment variables blade¶

The az webapp config appsettings set command above writes directly into this blade, which is the same surface the Portal exposes for manual edits. Notice there is no WEBSITE_RUN_FROM_PACKAGE row yet - this is the pre-state before enabling run-from-package, and after the CLI runs it appears here with Source App Service just like the existing entries. Treat this blade as a read-only audit view in CI-driven deployments rather than the primary editing surface, because manual Portal edits drift from the configuration that ZIP Deploy expects. The Deployment slot setting column matters when you promote to production - if a slot-specific value is required for staging-only configuration, mark it sticky from the CLI or this column instead of relying on the default empty state.

Complete ZIP Deploy Example¶

zip -r ./artifacts/webapp.zip .

az webapp deploy \
  --resource-group $RG \
  --name $APP_NAME \
  --src-path ./artifacts/webapp.zip \
  --type zip \
  --clean true \
  --restart true \
  --output json

curl --silent --show-error --fail \
  "https://$APP_NAME.azurewebsites.net/health"

Deploy to a Slot Instead of Production¶

az webapp deploy \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --src-path ./artifacts/webapp.zip \
  --type zip \
  --restart true \
  --output json

Advanced Topics¶

ZIP Deploy Design Guidance¶

• Prefer prebuilt artifacts from CI over ad hoc local builds.
• Use WEBSITE_RUN_FROM_PACKAGE for more predictable production behavior where the runtime supports it.
• Keep the package small and remove build-only files where possible.
• If the app requires build automation, document why SCM_DO_BUILD_DURING_DEPLOYMENT=true is acceptable.

Verification Commands¶

az webapp show \
  --resource-group $RG \
  --name $APP_NAME \
  --query "{state:state,host:defaultHostName}" \
  --output json

az webapp config appsettings list \
  --resource-group $RG \
  --name $APP_NAME \
  --query "[?name=='WEBSITE_RUN_FROM_PACKAGE' || name=='SCM_DO_BUILD_DURING_DEPLOYMENT']" \
  --output table

See Also¶

• Deployment Methods
• GitHub Actions
• Slots and Swap

Sources¶

• Deploy Files to Azure App Service (Microsoft Learn)
• Run Your App in Azure App Service Directly from a ZIP Package (Microsoft Learn)