Skip to main content

Deployments and versions

Deploy your latest code or return to an earlier version with App Service Builder. A version records the code and configuration you built; a deployment makes that version serve traffic.

Prerequisites​

  • An existing Builder app. Authorize GitHub source for a GitHub-backed build, or follow ZIP deployment to deploy local source without a GitHub connection. Deploying a retained version does not require fresh source authorization.
  • Permission to deploy the app and preview access for the selected location.
  • The approved CLI and connection settings, or an authenticated ARM client, if using those tabs.

Versions and activation​

  • A version freezes source revision, manifest, build outputs, and variables.
  • A deployment records an activation attempt and its outcome.
  • A ready build is not necessarily the version serving traffic.
  • Deploying an earlier version reuses its build output and saved variables.

Copy version and deployment IDs from app history or command output rather than constructing them yourself. Keep these IDs when tracking progress or reporting a problem.

Deploy current source​

Each request creates a new deployment record, even when it reuses a version. Builder reuses a ready version only when its source and configuration match and its build output is still available.

In Versions, open the Build and deploy menu before the search box, choose Build and deploy, then confirm. Source control must be configured first. Creation requests the first deployment automatically; Settings → Source Control also offers Save and deploy. Follow progress on Deployments rather than treating the saved source as a running app.

Track completion​

Portal Versions shows source and build results, including component build logs. Build timing is available in the version detail drawer rather than the versions table. Select Deploying in a version's Deployment state column to reopen that in-progress deployment's steps and logs without leaving Versions. This works after you dismiss the initial progress banner and does not start another deployment. Source commit links show the first seven characters beside a commit icon and open the full commit on GitHub. Search still matches the full commit ID. Deployments is a read-only history of activation progress, failures, and deployment logs. Both log views include line numbers, search, and Copy raw; see reading logs. Search or filter by status, page through ten records at a time, and use Refresh after the filters. Select a version link to inspect it in Versions, where deployment actions are available. Check Overview and the runtime's active version/deployment IDs to determine what is serving. A newer failure or pending attempt must not be confused with the active deployment.

ARM deploy and redeploy return 202 Accepted and Azure-AsyncOperation. Poll that URL until terminal; CLI waits unless --no-wait is set. If you chose not to wait:

builder app status "<returned-operation-url>" --wait

The CLI reads the subscription from the operation URL. If the URL has no subscription segment, supply --subscription "<subscription-id>".

An accepted request is not a completed deployment. Wait for success and check the app URL; deployment health checks are not continuous monitoring.

CLI status polling is throttled​

While waiting, the CLI retries temporary HTTP 429 (Too Many Requests) responses from ARM operation-status reads. Retries honor Retry-After and remain within the operation timeout; they do not resubmit the original write. If a CLI build stops waiting after a throttled read or the local timeout expires, an already accepted deployment can continue on the service. The local wait ending does not by itself mean deployment failed.

Do not immediately rerun builder app deploy. Wait before reading status again and honor Retry-After if it is available. If you have the operation URL, use builder app status as shown above to follow the same operation, not create a new one. Otherwise, inspect the existing app's Deployments and Overview in Portal, or read history:

builder app deployment list --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"
builder app show --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"

Confirm the existing attempt's outcome and active version before deciding whether another deployment is needed. After success, check the actual app URL.

Deploy an earlier version​

Only versions whose build outputs are still retained can be deployed again. The active version and a limited history are protected; retention is not unlimited.

Deploying a retained version preserves its variables, even if current desired variables have changed. App authentication and identity settings are not restored from the version. Use a new build when you intend to capture current variables.

In Versions, open the Build and deploy menu and choose Roll back to last known good to select the most recently successfully deployed version different from the active version. Review the version named in the confirmation before choosing Roll back. This reuses retained build outputs and saved variables without building from source. Rollback remains available when source authorization needs attention, but requires an active version and a successful different version in loaded deployment history. It is unavailable while history is loading or refreshing, or if that read fails; use Refresh to retry.

In Versions, select an eligible retained version and request deployment. Follow the new activation attempt on Deployments and verify the active version on Overview.

Retry safely​

For CLI retries, supply the same --request-id <id> for the same intent. For an intentional new deployment attempt, use a new request ID. ARM accepts idempotencyKey or x-ms-client-request-id. Changing source selection while reusing an ID can cause an idempotency conflict. If the response is lost, check deployment history before sending another request. If another deployment is pending, follow it to completion before retrying.

Related content​

Variables explains frozen configuration. Troubleshooting covers build failures and health policies; the ARM reference lists deployment routes.

Last updated on