---
title: Builds
description: A Build turns one commit into an image, an SBOM and signed provenance; it is immutable once created and ends with digests or a typed failure.
type: tutorial
product: builds
summary: What a build turns one commit into, and what it leaves behind.
updated: 2026-10-01
order: 0
---
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](/docs/builds/quickstart) shows them. The `builds` collection in the [API reference](/docs/api/builds) 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.
-; the default is sylphx-linux-standard.',
},
{
name: 'build_args',
type: 'map',
description: 'Build arguments. Secret values bind through Kernel Secrets, never here.',
},
{
name: 'cache',
type: 'string',
description: '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:
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:
', mono: true },
{ key: 'Build cache', value: 'orgs/{org}/projects/{project}/build_caches/{build_cache}', mono: true },
{ key: 'Cache id', value: 'bch_| ', mono: true },
]}
/>
An id is never reused. `build:read` covers reading a build and its caches;
everything that changes one needs `build:write`.
|