Manage Blueprints

A Git-connected Blueprint tracks a repository, branch, and YAML file and records synchronizations of its declared resources. Use it to manage an application's services, datastores, and configuration together.

The App resources and render.yaml guide covers manifest grammar and direct validation/apply. This guide covers the persistent Blueprint resource and its lifecycle. Neither workflow copies existing application data.

Preview and create​

Prepare and commit render.yaml, connect the repository through GitHub integration, and select the intended workspace. Blueprint creation requires an authorized developer/admin and configured control-plane storage and Git fetching. Private repositories need a valid grant.

Using the credentials from API authentication, preview the exact repository, branch, and path before creating the Blueprint:

curl --fail-with-body --silent --show-error \
  -X POST "$BEX_API_URL/v1/blueprints/preview" \
  -H "Authorization: Bearer $BEX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ownerId":"YOUR_WORKSPACE_ID","repo":"https://github.com/acme/shop","branch":"main","path":"render.yaml"}'

Replace the example values. Review validation errors, required secret inputs, resource changes, and pricing/capacity implications. A preview is not a deploy. Paths must be clean repository-relative .yaml or .yml paths. If both legacy bex.yml and render.yaml exist, specify the intended file explicitly.

Create with POST /v1/blueprints using the same fields and an optional name. Creation applies the manifest; it is not just registration. Inputs for declared secret placeholders can be supplied through envVarValues as supported by the preview/create flow—keep them out of committed YAML and logs.

Store the returned Blueprint id. Inspect the Blueprint and its sync history, then check the actual deployments and datastore readiness. Successful configuration application does not establish that every workload is healthy.

Synchronize changes​

New Git-connected Blueprints enable automatic sync. Delivery still depends on working Git integration. Blueprint auto-sync and each service's auto-deploy setting govern different operations; inspect both when a push changes behavior.

A manual Git sync resolves the tracked branch to a commit and reads the file at that commit. A fetch failure or an unavailable Git fetcher fails the sync; it does not apply the stored manifest as a fallback. Check the sync's recorded commit and resolve repository access problems before retrying. An explicitly supplied manifest is a separate sync path and does not claim a Git commit.

Only one apply can run for a given Blueprint at a time. A competing sync or disconnect can return 409 with BLUEPRINT_SYNC_BUSY; wait for the active sync to settle, then inspect its result before retrying.

Reapplying unchanged declarations is a no-op for unchanged resources. Changed services deploy, and validation errors must be resolved before applying. Runtime failures during a multi-resource apply can leave partial progress; inspect the resulting resources before retrying. Protected-environment changes can require an explicit confirmation phrase.

Change ownership or remove resources​

Manage a resource from one authoritative manifest. Dashboard/API changes can be replaced by the next sync if the manifest declares conflicting values. Review existing settings before adopting a resource into a Blueprint; defaults can differ from its current configuration.

Removing an entry from YAML does not delete the resource. To retire it, remove its declaration and delete the resource explicitly after reviewing data and backup requirements. Leaving the declaration can recreate it on a later sync.

DELETE /v1/blueprints/{id}?ownerId=… disconnects the Blueprint and clears its ownership. Workloads remain; empty Blueprint-created project/environment groupings may be reclaimed. Disconnection does not necessarily disable each service's own Git auto-deployment. Check those settings separately.

For failed builds or releases, use deployment stages and logs. For path-related failures, see monorepos.