How Builds Work

A build turns a build context (your source plus a Dockerfile) into a container image pushed to your organization’s registry. Builds run remotely with Kaniko and are fully asynchronous.

Context sources

Every build supplies its context exactly one of three ways:

Source	When to use it	How
Inline zip	Small projects (< 4 MB packed)	The context is sent inline with `CreateBuild` (`zippedCode`). The CLI tars your directory for you.
Uploaded context	Larger trees	Upload once via `UploadBuildContext` (gRPC client-stream, or `dodil ignite build upload`), then pass the returned `contextId` to `CreateBuild`.
Git	Source already in a repo	Pass a `gitSource` (`url`, `reference` — branch/tag/SHA, default `main`, and an optional `contextDir` subpath). Kaniko clones it directly — no upload.

The builder

Builds use Kaniko with a Dockerfile (path set by dockerfile, default Dockerfile). A standalone build always requires a Dockerfile.

Building from source without a Dockerfile — where the platform auto-detects a builder — is a Compute feature, reached through the draft/compile flow, not through BuildService directly. The dodil CLI can also scaffold a starter Dockerfile for common stacks when one is missing (see CLI Guide).

What you control on each build:

tags — image tags (defaults to latest).
buildArgs — Docker build args (map<string, string>).
platform — target platform, e.g. linux/amd64.
noCache — disable layer caching for a clean build.
timeoutSecs — build timeout (0 uses the platform default).

Lifecycle

CreateBuild validates the request, queues the build, and returns a build_id with status BUILD_STATUS_PENDING right away — it never blocks on the build finishing.


PENDING ──▶ RUNNING ──▶ SUCCEEDED
                   ├──▶ FAILED
                   └──▶ CANCELLED   (via CancelBuild)

Follow progress with StreamBuildLogs — keyed by build_id. fromStart: true replays the full persisted log; otherwise it tails from now.
Inspect a build with GetBuild (or list them with ListBuilds, filterable by status). A finished build carries metrics — durationMs, imageSizeBytes, layerCount, and whether the cache was used.
Cancel an in-flight build with CancelBuild.

Output and the Compute hand-off

A successful build pushes the image to your organization’s registry and records the full references in imageRefs (registry/your-org/name:tag). The target registry and repository are managed by the platform — you don’t set them.

That image is what an image-mode app version in Compute runs. When you compile a draft from an image source, Compute dispatches the build, waits for it, and wires the resulting image reference onto the version automatically. You can also reference a build’s imageRefs yourself as a Bring-Your-Own-Image deploy — see Bring Your Own Image.

Credentials

Private base images and private git repos need credentials. BuildService stores them per organization with SaveBuildSecrets — one call carries three groups:

registryCredentials — registry auth for pushing built images and pulling private base images.
gitCredentials — a username + token (PAT) for cloning private repos; applied automatically to gitSource builds.
buildSecrets — extra values exposed to the build as build args. (Secret values are redacted to *** when a build is read back.)

This per-org store is distinct from the named-slot model Compute’s Bring-Your-Own-Image deploys use (a registry_secret_ref pointing at a SecretService slot). Builds reference their org’s stored credentials implicitly; they don’t name a slot per build.