builder.yaml reference
builder.yaml defines named source build units, runtime commands, and public routes for an App Service Builder version.
At a glance
- The top-level
componentslist must be nonempty. - Names and public mounts are unique.
- The selected build behavior combines explicit settings and repository evidence.
- Deployment supports at most one static output and one public compute output.
Top-level fields
| Field | Type | Contract |
|---|---|---|
name | String | Optional informational name; the ARM resource name is authoritative |
components | List | At least one component; order is preserved in the version |
Unknown keys and duplicate YAML keys are rejected.
There are no supported YAML fields for component variables, linked services, authentication, identity, scaling, or a customer-facing framework selector.
Those app-owned settings use their own contracts where available.
Component fields
| Field | Type | Default and constraints |
|---|---|---|
name | String | Required, unique using case-sensitive comparison; letters, digits, ., _, -; not . |
role | static or web | Optional intent/validation constraint; omission does not mean static |
platform | String | nodejs, python, dotnet, php; required with a custom build |
platformVersion | String | Requires platform; omission sends no explicit customer override |
rootDirectory | Relative path | Default app source root; selects build input, not the hosted document root |
build | String | Custom command; requires platform and generated output under $DESTINATION_DIR |
output | Relative path | Static web root; required for explicit no-build static and custom static builds |
run | Object | Required for explicit web intent; forbidden with role: static |
path | Absolute path | Single component defaults to /; every component must declare it in multi-component manifests |
rootDirectory and output must be safe relative paths.
They cannot be absolute, escape with .., or contain shell syntax.
Use . deliberately to select a root.
Public paths start with / and cannot contain whitespace, repeated/trailing separators, or ./.. segments.
Only one component can own the catch-all /.
More-specific public prefixes win over the catch-all.
Runtime fields
| Field | Type | Default and constraints |
|---|---|---|
run.port | Integer | Default 8080; range 1–65535 |
run.start | String | Optional startup override; omit for default PHP 8.5 nginx/PHP-FPM startup |
run.healthCheckPath | Absolute path | Optional; when explicit, must be canonical and within the component's public mount |
run.healthCheckStatusCodes | Integer list | Only with an explicit health path; nonempty, unique, each in 100–599 |
Omitting run.start does not omit runtime startup.
The selected runtime resolves startup when no override is supplied.
For PHP 8.5, keep the run block, omit run.start, and put index.php and health.php at the packaged build root.
Use run.healthCheckPath: /health.php; the port and single-component mount can retain their defaults of 8080 and /.
Neither rootDirectory nor the static output field configures a PHP public/ document root.
See PHP build and startup for source, Composer, and packaging guidance.
Output resolution
| Build shape | Where static output is resolved |
|---|---|
| No platform/build/run, explicit static output | Beneath the component source root; no build step |
| Recognized Vite | Generated output root; conventional output is dist |
| Generic or custom static build | Generated output root |
| Generic compute | No output field; entire runnable build output is packaged |
For Vite, a vite dependency or vite.config.* identifies framework evidence.
Node.js and conventional build/output values can be inferred.
Next.js with a next dependency and standalone configuration can resolve a hybrid static-plus-compute result.
Omitted fields do not permit arbitrary source publication when no safe build shape matches.
The manifest does not enumerate runtime versions installed in a particular target.
Health semantics
| Configuration | Deployment health result |
|---|---|
| No explicit health path | Reachability: completed response from 100 through 499; 5xx or transport failure is unhealthy |
| Explicit path, no status list | Exact HTTP 200 |
| Explicit path and status list | Exact membership in the configured list |
Without an explicit path, direct compute is probed at / and the public route at the component mount.
For an explicit /api/health under mount /api, both direct compute and the public route are probed at /api/health.
Implement that path in the application rather than assuming the mount is removed.
These checks qualify a deployment, not continuing app health.
Use the manifest guide for examples and local validation. The Builder CLI reference describes read-only manifest validation and optional trusted-repository Docker build checks. The runtime reference describes build versus deployment support.