Skip to content
Console
On this page

Create a build

Creates a build: one command or one image over a commit or a tree.

Creates a build: one command or one image over a commit or a tree. The Operation is done when the build reaches a final state. run and image are the short forms.

  • Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/builds
  • Scope build:run
  • Effect write — a successful call changes state.
  • Collection builds
  • Query build_id, validate_only
  • Operation answers with an Operation; the result is Build

Request

FieldTypeWhat it is
parentstringThe parent to create in. Required.
buildBuildThe build to create; only spec and caller-writable metadata are read. Required.
build_idstringThe id segment of the name; the server assigns one when unset.
validate_onlyboolValidate and return the result without writing anything.

Build

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/builds/{build}.
metaResourceMetaResource metadata.
specBuildSpecDesired state. Required.

ResourceMeta

FieldTypeWhat it is
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.

BuildSpec

FieldTypeWhat it is
sourceBuildSourceA commit, read through the Broker at that exact commit. One of the input group.
cachestringThe BuildCache to read and write; default the project's default cache.
treeBuildTreeA tree uploaded to the org's store, by its root digest. One of the input group.
imageImageTargetAn OCI image with an SBOM and signed provenance. One of the output group.
commandCommandTargetOne command's exit code and the artifacts it names. One of the output group.
sizeBuildSizeThe machine size; default [build] size, else STANDARD. One of standard, large, xlarge.
timeoutdurationThe time limit; default 1 hour, at most 6 hours. A command that reaches it is killed and the Build ends with BUILD_FAILURE_TIMEOUT.
allow_hostsstring[]Internet hosts the build may reach. Empty means in-cell only: the mirrors and the store. Default [build] allow_hosts.

BuildSource

FieldTypeWhat it is
source_linkstringThe Hosting SourceLink naming the repository and its Connection. Required.
commitstringThe full commit SHA to build. Required.
root_directorystringThe directory inside the repository to build; default the root.

BuildTree

FieldTypeWhat it is
root_digeststringThe root Directory digest, <sha256 hex>/<size in bytes>. Required.

ImageTarget

FieldTypeWhat it is
servicestringThe sylphx.toml service whose dockerfile and context apply; unset reads the fields below or lets the zero-config frontend detect the stack.
dockerfilestringA Dockerfile path relative to the input root; unset lets the zero-config frontend detect the stack.
targetstringThe Dockerfile stage to build.
build_argsmap<string, string>Build arguments. Secret values bind through [build.secrets], never here.

CommandTarget

FieldTypeWhat it is
argvstring[]The program and its arguments. Use ["bash", "-lc", "…"] for a shell. Required.
artifactsstring[]Globs, relative to the input root, of files kept after the command ends, whatever its exit code (test reports, coverage).

Response

FieldTypeWhat it is
namestring{parent-of-target}/operations/{operation}.
targetstringThe name of the Resource being changed.
target_generationint64The generation this Operation waits for.
verbOperationVerbWhat the Operation does. One of create, update, delete, custom.
custom_verbstringThe custom method verb when verb is CUSTOM, for example revoke.
doneboolWhether the Operation has finished.
create_timetimestampWhen the Operation started.
end_timetimestampWhen the Operation finished.
responseanyThe settled Resource (or Empty for a delete). One of the result group.
errorProblemDetailsThe failure, as the one error body. One of the result group.
progressOperationProgressProgress while not done.

ProblemDetails

FieldTypeWhat it is
typestringhttps://sylphx.com/docs/errors/<code in kebab-case>.
titlestringA short customer-safe summary of the problem class.
statusint32The HTTP status, fixed by grpc_status.
detailstringA customer-safe explanation of this occurrence. Never contains SQL, stack traces, internal hostnames, or another tenant's data.
instancestringThe request id (Sylphx-Request-Id).
codestringThe stable UPPER_SNAKE code, one of ErrorCode without its prefix.
grpc_statusstringOne of the 16 canonical gRPC status names, for example ABORTED.
retryableboolWhether the same request may be retried.
effectErrorEffectWhat the failed call committed. One of none, applied, unknown.
retry_after_msint64How long to wait before retrying, when the server knows.
detailsany[]Typed details such as PreconditionFailure or EntitlementDenial.

OperationProgress

FieldTypeWhat it is
percentint32Percent complete, when the controller can tell.
messagestringA customer-safe progress message.
conditionsCondition[]The target's conditions when this progress was read.

Condition

FieldTypeWhat it is
typestringThe condition type, for example Ready.
statusConditionStatusWhether the condition holds. One of true, false, unknown.
observed_generationint64The generation this observation was made against.
reasonstringA machine-readable UpperCamelCase reason.
messagestringA customer-safe human-readable message.
severitySeverityHow severe a FALSE condition is. One of info, warning, error.
transition_timetimestampWhen status last changed.

Errors

Every error arrives in the body Errors describes.

Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/builds" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{}}'