Run a build
Runs one command over an uploaded tree and settles with its exit code, like the local command.
Runs one command over an uploaded tree and settles with its exit code, like the local command. A caller that gets a failure before the command started (BUILD_FAILURE_SETUP_FAILED, NO_CAPACITY) may build locally.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/builds:run - Scope
build:run - Effect
write— a successful call changes state. - Collection builds
- Validate-only
validate_only=trueruns every check and writes nothing - Operation answers with an
Operation; the result isBuild
Request
| Field | Type | What it is |
|---|---|---|
parent | string | The project to run in. Required. |
tree | BuildTree | The uploaded tree to run over. Required. |
command | string[] | The program and its arguments. Required. |
artifacts | string[] | Globs of files kept after the command ends, whatever its exit code. |
size | BuildSize | The machine size; default [build] size, else STANDARD. One of standard, large, xlarge. |
timeout | duration | The time limit; default 1 hour. |
allow_hosts | string[] | Internet hosts the command may reach; empty means in-cell only. |
cache | string | The BuildCache to use; default the project's default cache. |
build_id | string | The id segment of the Build's name; the server assigns one when unset. |
validate_only | bool | Validate and return the result without writing anything. |
BuildTree
| Field | Type | What it is |
|---|---|---|
root_digest | string | The root Directory digest, <sha256 hex>/<size in bytes>. Required. |
Response
| Field | Type | What it is |
|---|---|---|
name | string | {parent-of-target}/operations/{operation}. |
target | string | The name of the Resource being changed. |
target_generation | int64 | The generation this Operation waits for. |
verb | OperationVerb | What the Operation does. One of create, update, delete, custom. |
custom_verb | string | The custom method verb when verb is CUSTOM, for example revoke. |
done | bool | Whether the Operation has finished. |
create_time | timestamp | When the Operation started. |
end_time | timestamp | When the Operation finished. |
response | any | The settled Resource (or Empty for a delete). One of the result group. |
error | ProblemDetails | The failure, as the one error body. One of the result group. |
progress | OperationProgress | Progress while not done. |
ProblemDetails
| Field | Type | What it is |
|---|---|---|
type | string | https://sylphx.com/docs/errors/<code in kebab-case>. |
title | string | A short customer-safe summary of the problem class. |
status | int32 | The HTTP status, fixed by grpc_status. |
detail | string | A customer-safe explanation of this occurrence. Never contains SQL, stack traces, internal hostnames, or another tenant's data. |
instance | string | The request id (Sylphx-Request-Id). |
code | string | The stable UPPER_SNAKE code, one of ErrorCode without its prefix. |
grpc_status | string | One of the 16 canonical gRPC status names, for example ABORTED. |
retryable | bool | Whether the same request may be retried. |
effect | ErrorEffect | What the failed call committed. One of none, applied, unknown. |
retry_after_ms | int64 | How long to wait before retrying, when the server knows. |
details | any[] | Typed details such as PreconditionFailure or EntitlementDenial. |
OperationProgress
| Field | Type | What it is |
|---|---|---|
percent | int32 | Percent complete, when the controller can tell. |
message | string | A customer-safe progress message. |
conditions | Condition[] | The target's conditions when this progress was read. |
Condition
| Field | Type | What it is |
|---|---|---|
type | string | The condition type, for example Ready. |
status | ConditionStatus | Whether the condition holds. One of true, false, unknown. |
observed_generation | int64 | The generation this observation was made against. |
reason | string | A machine-readable UpperCamelCase reason. |
message | string | A customer-safe human-readable message. |
severity | Severity | How severe a FALSE condition is. One of info, warning, error. |
transition_time | timestamp | When status last changed. |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.UNKNOWN_FIELD— The request has a field the schema does not know.INVALID_FIELD— A field failed validation.RESOURCE_ALREADY_EXISTS— A Resource with this name exists.IDEMPOTENCY_KEY_REUSED— An Idempotency-Key was reused with another body.IDEMPOTENCY_IN_PROGRESS— The first call with this Idempotency-Key is still running.PLAN_LIMIT_REACHED— The plan's limit is reached.SPEND_LIMIT_REACHED— The org's spend limit is reached.
Every error arrives in the body Errors describes.
Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/builds:run" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":["…"],"tree":{"root_digest":"…"}}'