Menu
Platform
AI
App store purchases
Database
Flags
Jobs and cron
Localization
Monitoring
Notifications
Payments
Queues
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Builds
What a build turns one commit into, and what it leaves behind.
Today this runs on the management API
Builds are started by a deploy and read with GET /v1/builds and GET /v1/deployments/builds/{id} on the management API; the Builds quickstart shows them. The builds collection in the API reference is not served at api.sylphx.com.
A Build turns one commit into an image, an SBOM, and signed provenance. It is immutable once created: it is never edited, only read. A build ends one of two ways — with the digests of what it produced, or with a typed failure that says why it produced nothing.
Every Hosting deploy builds through Sylphx Build today: the image a Service runs comes from a build of an exact commit, and that build is a record you can read back.
#What you name, and what the build decides
The only required part of a build is its source: a commit, read exactly.
| Field | Type | What it is |
|---|---|---|
source | BuildSourcerequired | The exact source. Required. |
dockerfile | string | A Dockerfile path relative to the root directory; unset lets the zero-config frontend detect the stack. |
target | string | The Dockerfile stage to build. |
build_class | string | The class, sylphx-<os>-<size>; the default is sylphx-linux-standard. |
build_args | map | Build arguments. Secret values bind through Kernel Secrets, never here. |
cache | string | The BuildCache to read and write; the project’s default cache by default. |
The source is three fields of its own, and the first two are required:
| Field | Type | What it is |
|---|---|---|
source_link | stringrequired | The Hosting SourceLink naming the repository and its Connection. Required. |
commit | stringrequired | The full commit SHA to build. Required. |
root_directory | string | The directory inside the repository to build; the root by default. |
A Dockerfile is optional. Unset, the zero-config frontend detects the stack, which is why a repository builds without one and can add one later without changing the call.
#Names are paths
A build lives in the project whose repository it builds:
- Build
- orgs/{org}/projects/{project}/builds/{build}
- Build id
- bld_<cell><ulid>
- Build cache
- orgs/{org}/projects/{project}/build_caches/{build_cache}
- Cache id
- bch_<cell><ulid>
An id is never reused. build:read covers reading a build and its caches;
everything that changes one needs build:write.