Skip to main content

Deploy ZIP source with Builder CLI

Deploy application source from your computer without connecting a GitHub repository or installing the GitHub App. Builder uploads your ZIP, builds the application, and activates the deployment. This uploads source, not a ready-to-run application package.

Prerequisites​

  • Builder CLI 0.0.2 or a compatible later release, Node.js 22 or later, and PowerShell for these examples.
  • A subscription enabled for Private Preview, an existing resource group, and permission to create and deploy Builder apps there. Use development/test workloads only.
  • Application source and a valid root builder.yaml describing how to build and run it. Use the manifest guide to prepare it.

Sign in​

Confirm your installed version and Azure account:

builder --version
builder login
builder account show

The linked release reports version 0.0.2. Use your subscription's Microsoft Entra account, not a GitHub login. Add --tenant to builder login only if you need to select a particular directory.

This walkthrough uses the default public ARM endpoint, https://management.azure.com. If you previously configured a custom endpoint, reset that override first:

builder config reset --endpoint-resource-manager

Create a Builder app​

Replace the subscription and resource-group placeholders and choose an app name:

$sub = "<subscription-id>"
$rg = "<existing-resource-group>"
$app = "my-zip-app"

builder app create --name $app `
  --subscription $sub --resource-group $rg `
  --location eastus2 --json

The example uses East US 2; see available regions for other choices. sourceIntegrationState: "NotConfigured" is expected here. ZIP deployment does not require a GitHub source connection.

Package the source​

The ZIP must contain builder.yaml at its root, not inside an extra parent folder. For example:

my-app.zip
  builder.yaml
  server/
    package.json
    package-lock.json
    server.js

If your manifest's component root is server, run this from your project directory:

Compress-Archive -LiteralPath .\builder.yaml, .\server `
  -DestinationPath .\my-app.zip -Force

Select only the source files and folders your app needs. Exclude credentials, .env files, Git metadata, and dependency caches. The compressed ZIP limit is 100 MiB; the manifest limit is 1 MiB. See ZIP input details if you need to preserve executable permissions or use another archive tool.

Deploy the ZIP​

Pass the same manifest file whose exact bytes are inside the ZIP:

$deployJson = builder app deploy --name $app `
  --subscription $sub --resource-group $rg `
  --source-archive .\my-app.zip `
  --manifest .\builder.yaml --json

if ($LASTEXITCODE -ne 0) { throw "ZIP deployment command failed: $($deployJson | Out-String)" }
$deploy = $deployJson | ConvertFrom-Json
if ($deploy.status -ne "Succeeded" -or $deploy.terminal -ne $true) {
  throw "Deployment has not confirmed success."
}

$url = $deploy.app.properties.runtime.url

The command waits by default. A completed deployment reports status: "Succeeded" and terminal: true. If you change the manifest after creating the ZIP, recreate the ZIP before deploying.

Verify the app and inspect logs​

Check an expected application route. For an app mounted at /:

if ([string]::IsNullOrWhiteSpace($url)) {
  throw "No app URL was returned. Read the existing app state before continuing."
}
(Invoke-WebRequest -Uri $url).StatusCode

Verify the expected response content as well as the status code. If the app requires authentication, use its configured authentication rather than bypassing it. If the result lacks an app URL, read the app with builder app show using the same name, subscription, and resource group; do not redeploy just to recover the URL.

Inspect the build log, replacing web with your manifest's component name: If the result does not include appVersionId, use version history to find it first.

builder app version build-log --name $app $deploy.appVersionId `
  --subscription $sub --resource-group $rg `
  --component web

For an update, change your source, recreate the ZIP, and run the deploy command again.

Recover an interrupted deployment​

If observation stops after admission, follow the returned operation instead of submitting another deployment:

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

SourceUploadDisabled means ZIP upload is not enabled for your target; contact your preview contact. For a manifest mismatch or invalid ZIP, correct the source/archive and recreate it before retrying. See deployment recovery for status-polling errors.

Clean up resources​

Delete the test app when you no longer need it:

builder app delete --name $app `
  --subscription $sub --resource-group $rg

The command asks for confirmation and waits for deletion. Confirm the app identity before approving. Your local source, ZIP, and resource group are separate from the Builder app.

Related content​

CLI ZIP input covers directory packaging, archive limits, and manifest matching. ZIP deployment with the ARM API covers the upload and deployment requests for API automation.

Last updated on