Configure application variables

Set application variables to pass configuration to your app's build and running HTTP process. Each new version captures the values saved when it is created. Saving alone does not change a running version.

Prerequisites

• An existing Builder app and preview access.
• Permission to update the app; retrieving variable values requires permission for the separate listVariables action.
• An authenticated ARM client if you use the ARM tab. See the ARM API deployment guide for management authentication.
• An installed and signed-in Builder CLI if you use the CLI tab.

All components receive these values during build. Static builds can embed them in public assets; review the secret-handling boundaries before adding credentials.

Set variables

Portal

1. Open the app's Variables page.
2. Choose Add variables and enter names and values. Editing one existing variable can intentionally replace its value with an empty string.
3. Choose Save only to persist the desired list, or Save and deploy to save and request a new build.
4. If you requested deployment, follow it in Deployments. If saving succeeds but deployment cannot start, your values remain saved. Retry deployment instead of re-entering the values.

Builder CLI

Update a non-sensitive setting:

builder app version-config variables update --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>" \
  --variable-name FEATURE_FLAG --variable-value enabled

For several values or sensitive input, use a local JSON object instead of putting values in shell history:

{"FEATURE_FLAG":"enabled","LOG_LEVEL":"info"}

Save it as variables.json, keep it out of source control, and restrict access to the file. Merge its entries into the saved configuration:

builder app version-config variables update --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>" \
  --settings @variables.json

builder app version-config variables list --name "<app-name>" \
  --subscription "<subscription-id>" --resource-group "<resource-group>"

Update merges supplied names and preserves other existing variables. List shows names, not values. To remove one variable, use builder app version-config variables delete --name "<app-name>" with the same subscription and resource group and --variable-name "<variable-name>". Remove the local file when it is no longer needed.

Saving does not create a version or deployment. Deploy current source with --rebuild to capture the desired values in a new version, then verify the running app.

ARM API

PATCH the app URL using the ARM reference. An explicit list is the complete desired set of names:

{
  "properties": {
    "versionConfiguration": {
      "variables": [
        { "name": "FEATURE_FLAG", "value": "enabled" },
        { "name": "EXISTING_SETTING" },
        { "name": "EMPTY_SETTING", "value": "" }
      ]
    }
  }
}

In this example, EXISTING_SETTING must already exist. Names absent from the list are deleted.

Write	Result
Omit variables	Preserve current desired variables
Send variables: []	Clear all desired variables
Existing name with omitted value	Preserve that stored value
New name with a value	Add the variable
Existing name with value: ""	Replace with an intentionally empty value
Explicit null list	Invalid PATCH input

After saving, request a new deployment to capture the values. POST <app-resource-url>/listVariables?api-version=2026-09-01-preview returns sensitive desired values to callers with permission for that action. Do not record its response in logs.

Verify the change

Wait for deployment success and confirm that the active version is the version you just built. Check the intended behavior in the running app without displaying credentials or environment dumps. Ordinary app reads show variable names, not values, so a refreshed name list alone does not prove that the running version changed.

Understand build and runtime values

All components receive the same values during build, and HTTP processes receive them at runtime. There is no per-component list or runtime-only secret setting. Static files have no runtime environment; frontend builds may embed values into browser-readable output. Treat any value used by a client-side build as potentially public.

Saving values does not mutate running compute or existing versions. Retained-version activation uses that version's historical values, not the newly saved desired list. Use Save and deploy or a new build when current values must be captured.

Secrets and sensitive values

Treat every variable value as sensitive, including ordinary configuration such as LOG_LEVEL. An authorized POST .../listVariables request returns all current desired values, not one selected value or a historical version snapshot. Restrict access to that action and avoid recording its response, credentials, or environment dumps in logs. Write-only on ordinary reads does not prevent authorized retrieval or protect a value embedded into static assets.

Built-in secretValue and keyVaultReference fields are not supported. Access to a separate secret store must be implemented in your application. Your app can read Key Vault with its managed identity; Builder does not automatically resolve Key Vault references. See connecting to services and security guidance.

Variable limits

Names follow [A-Za-z_][A-Za-z0-9_]*, are at most 256 characters, and must be unique ignoring case. PORT and names beginning with EMBR_ are reserved ignoring case. The list allows 100 entries, a value allows 32,768 UTF-8 bytes, and all names plus values allow 65,536 UTF-8 bytes.

Related content

Deployments explains version capture and activation. Managed identity explains credential-free Azure access, including the AZURE_CLIENT_ID variable.