Skip to main content

Provision a Builder app with ARM or Bicep

Bicep and ARM infrastructure templates (JSON) are equivalent ways to define the same Microsoft.Web/builderApps resource. These define Azure resources, unlike the starter-code templates in the Portal. Choose either format below; you do not need to deploy both. Provisioning the resource, authorizing source, building a version, and activating a deployment are separate operations. For a first running app without a template, use Portal or Builder CLI.

Preview example

Use development/test resources only; do not deploy production workloads. Confirm subscription access and location with your preview contact. After submitting a template, track the Azure deployment until it completes. See Private Preview guidance.

Prerequisites​

  • An authenticated Azure CLI with permission to deploy resources in your resource group. Reuse one or create it first.
  • Bicep tooling for the Bicep tab; the ARM JSON tab does not require Bicep compilation.
  • A preview subscription that can create Microsoft.Web/builderApps resources.
  • For the source/deployment step, the approved Builder CLI installer/version and connection settings, Node.js 22 or later, and GitHub CLI (gh).

The example deliberately contains no GitHub credential or sensitive variable values. Source authorization is completed separately through Builder CLI or ARM.

If you arrived from a quickstart or tutorial, keep that repository, branch, and root builder.yaml for the source step. Otherwise choose a published app from the sample catalog or prepare source using a language tutorial. The same minimal resource below applies to those app shapes; it contains no language build or startup settings. Those remain in the selected repository's builder.yaml.

Define and deploy the template​

The examples intentionally omit source, credentials, and sensitive variable values. Deploy to a new development/test app after confirming the selected Azure account/subscription and preview access. Do not rerun either minimal template over an existing configured app without reviewing PUT replacement semantics; neither carries that app's source and settings.

Save this as main.bicep:

targetScope = 'resourceGroup'

@description('Name of the development/test Builder App.')
param appName string

@description('Location qualified for your preview subscription.')
param location string

resource app 'Microsoft.Web/builderApps@2026-09-01-preview' = {
  name: appName
  location: location
  properties: {}
}

output appResourceId string = app.id

The API accepts creating an app without source, matching builder app create. The template does not start a build or create a running app. If the Bicep compiler reports that types are unavailable for this preview resource, it cannot validate its property schema. Compare the generated JSON with the ARM reference; successful compilation alone does not establish provider availability.

Compile locally first:

az bicep build --file main.bicep

Request resource creation:

az deployment group create \
  --subscription "<subscription-id>" \
  --resource-group "<resource-group>" \
  --template-file main.bicep \
  --parameters appName="<app-name>" location="<qualified-location>"

Inspect deployment errors explicitly. A successful ARM template deployment confirms resource provisioning, not a built version or serving endpoint.

Connect source and deploy the app​

Sign in to Azure and GitHub separately with the approved Builder CLI, then connect your prepared repository:

builder login
builder account show
builder source login github
builder app source connect github --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>" \
  --repository-id "<numeric-repository-id>" --repository "<owner>/<repository>" \
  --branch "<branch>" --root-directory "."

builder app deploy --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"

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

Wait for terminal deployment success, then verify the returned app URL and active version. Use <owner>/<repository> and <branch> from your prepared source; do not switch samples after resource creation. The example includes --repository-id for CLI 0.0.2 compatibility. See source control to look up that ID or use automatic lookup in a compatible CLI build. The ARM API deployment guide provides equivalent authorization/deploy/poll operations if you use an ARM client instead. Neither template format replaces the separate GitHub source authorization.

Clean up resources​

Delete only the test app when finished:

builder app delete --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"

Wait for deletion completion. Keep the resource group, template history, and separately owned services unless you intend to remove them independently. Terraform is not a documented Builder provisioning workflow in this preview.

See Bicep deployment guidance or ARM template deployment guidance for the Azure tooling.

Last updated on