Slots and Swap¶

Deployment slots reduce release risk by letting you deploy to a live nonproduction endpoint, validate it, and promote it into production with a swap. This page focuses on slot creation and promotion mechanics and links to the broader operational slot guide where appropriate.

Main Content¶

Slot Promotion Flow¶

flowchart TD
    A[Deploy new version to staging slot] --> B[Apply slot-specific settings]
    B --> C[Warm up staging slot]
    C --> D[Run smoke tests]
    D --> E{Ready to promote?}
    E -- Yes --> F[Swap staging with production]
    E -- No --> G[Keep production unchanged]
    F --> H[Previous production now lives in staging]
    H --> I[Swap back if rollback is required]

Create a Deployment Slot¶

az webapp deployment slot create \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --configuration-source $APP_NAME \
  --output json

az webapp deployment slot list \
  --resource-group $RG \
  --name $APP_NAME \
  --query "[].{name:name,state:state,host:defaultHostName}" \
  --output table

Configure Slot-Specific Settings¶

Some values must stay with the slot instead of moving during a swap. Typical examples include environment names, test endpoints, and nonproduction secrets.

az webapp config appsettings set \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --slot-settings APP_ENVIRONMENT=staging API_BASE_URL=https://api-staging.contoso.example \
  --output none

--slot-settings both sets the value and marks it sticky, so the same names do not need a separate --settings argument. Use --settings only for application-defined values that should keep swapping with the code; updating an already-sticky setting through --settings does not remove its sticky designation.

Confirm the sticky flag by reading back only the names and the slotSetting flag. The --query projection leaves value out of the formatted output (shell tracing, command history and debug logging can still expose values):

az webapp config appsettings list \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --query "[?contains(['APP_ENVIRONMENT','API_BASE_URL'], name)].{name:name,slotSetting:slotSetting}" \
  --output table

Each listed setting should show slotSetting as True. For an application-defined setting like these, a False row means it will still swap with the code; some platform settings are never swapped even without this flag (see Microsoft Learn). The same procedure, with additional guidance on which settings are sticky by default, is maintained in Configure Slot-Specific Settings.

Manual Swap¶

az webapp deployment slot swap \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --target-slot production \
  --output json

Portal view: Swap blade with config preview¶

Purpose: Show the configuration changes a swap will apply before you start it.

Look for: The Source and Target slots, Perform swap with preview, and the Config Changes table.

Expected result: The table lists every setting that changes on swap; review each row before selecting Start Swap.

This is the Portal equivalent of the az webapp deployment slot swap command on the production app. The Source slot changes and Target slot changes tabs render the exact effective configuration each slot will have after the swap completes - this is the last opportunity to catch sticky-setting omissions before cutover. Notice the disabled Perform swap with preview checkbox: the banner explains the slot must have at least one slot-specific setting before preview mode unlocks, which is why marking APP_ENVIRONMENT and API_BASE_URL as --slot-settings in the Configure Slot-Specific Settings example is important even when the values look ordinary. Run this manual review against staging slot deployments before promoting; treat any Old Value to New Value transition in the production-bound row as a release decision, not a Portal click.

Swap with Preview¶

az webapp deployment slot swap \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --target-slot production \
  --action preview \
  --output json

az webapp deployment slot swap \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --target-slot production \
  --action swap \
  --output json

If validation fails, cancel the pending swap:

az webapp deployment slot swap \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging \
  --target-slot production \
  --action reset \
  --output json

Auto-Swap¶

Auto-swap can shorten release flow for lower-risk workloads, but it is better suited to deterministic startup behavior and automated validation.

az webapp deployment slot auto-swap \
  --resource-group $RG \
  --name $APP_NAME \
  --slot staging

Blue-Green Pattern with App Service Slots¶

In App Service, the blue environment is usually the current production slot and the green environment is the staging slot holding the candidate release.

1. Deploy the new build to staging.
2. Warm the slot and validate health checks.
3. Swap staging into production.
4. If regression appears, swap again to restore the previous version.

This pattern gives a fast rollback path without rebuilding or repackaging during the incident.

Advanced Topics¶

Verification Commands¶

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

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

See Also¶

• Deployment Methods
• GitHub Actions
• Deployment Slots Operations

Sources¶

• Set Up Staging Environments in Azure App Service (Microsoft Learn)
• Deployment Best Practices for Azure App Service (Microsoft Learn)