Builds — API Reference

Package: dodil.ignite.v1 · Service: BuildService

These RPCs drive a remote container image build with Kaniko and push the result to the platform’s org-scoped registry. A build takes a source (an uploaded context, an inline zip, or a git repo), runs your Dockerfile, and produces one or more image refs you can run in image-mode Compute. Builds are asynchronous — CreateBuild returns immediately with a buildId; follow progress with StreamBuildLogs and read the final result with GetBuild.

gRPC reaches every method at dodil.ignite.v1.BuildService/<Method> on $IGNITE_GRPC; the HTTP gateway mirrors each one. See Conventions → Using gRPC for grpcurl setup. gRPC requests use the proto field names (snake_case); HTTP uses pbjson (camelCase). Responses render camelCase. int64/uint64 fields (timeoutSecs, createdAtMs, …) serialize as JSON strings.

RPC	HTTP	streaming
`CreateBuild`	`POST /v1/ignite/builds`	unary
`GetBuild`	`GET /v1/ignite/builds/{build_id}`	unary
`ListBuilds`	`GET /v1/ignite/builds`	unary
`StreamBuildLogs`	`GET /v1/ignite/builds/{build_id}/logs/stream`	server-stream
`CancelBuild`	`POST /v1/ignite/builds/{build_id}/cancel`	unary

BuildStatus (used throughout) is one of: BUILD_STATUS_PENDING, BUILD_STATUS_RUNNING, BUILD_STATUS_SUCCEEDED, BUILD_STATUS_FAILED, BUILD_STATUS_CANCELLED.

`CreateBuild`

Starts a build. Exactly one source must be set:

context_id — id from a prior UploadBuildContext; use this for contexts too large for the inline path.
zipped_code — an inline tar.gz/zip of the build context (bytes). Must be under 4 MB; for anything larger, upload a context first.
git_source — clone and build from a git repo.

Request

Field (proto)	HTTP (pbjson)	Type	Notes
`name`	`name`	string	Required. Build / image name.
`dockerfile`	`dockerfile`	string	Path to the Dockerfile, relative to the context root. Default `Dockerfile`.
`tags`	`tags`	repeated string	Image tags. Defaults to `["latest"]`.
`build_args`	`buildArgs`	map`<string, string>`	Docker build args (`ARG`).
`no_cache`	`noCache`	bool	Disable layer caching for this build.
`timeout_secs`	`timeoutSecs`	uint64	Build timeout in seconds. `0` = server default. JSON string.
`platform`	`platform`	string	Target platform, e.g. `linux/amd64`.
`context_id`	`contextId`	string	source. Id from `UploadBuildContext`.
`zipped_code`	`zippedCode`	bytes	source. Inline `tar.gz`/`zip`, base64 over JSON. Under 4 MB.
`git_source`	`gitSource`	`GitSource`	source. Build from a git repo.

GitSource:

Field (proto)	HTTP (pbjson)	Type	Notes
`url`	`url`	string	Repo URL.
`reference`	`reference`	string	Branch, tag, or commit SHA. Default `main`.
`context_dir`	`contextDir`	string	Subdirectory within the repo to build from. Optional.

For private repos, store a PAT once with SaveBuildSecrets — it is auto-applied to git_source builds.

HTTP


curl -sS -X POST "https://api.dev.dodil.io/v1/ignite/builds" \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-data-processor",
    "dockerfile": "Dockerfile",
    "tags": ["v1", "latest"],
    "buildArgs": { "NODE_ENV": "production" },
    "noCache": false,
    "timeoutSecs": "600",
    "platform": "linux/amd64",
    "gitSource": {
      "url": "https://github.com/acme-corp/data-processor.git",
      "reference": "main",
      "contextDir": "services/processor"
    }
  }'

Response

HTTP


{
  "buildId": "bld_01HZX9ABCD",
  "status": "BUILD_STATUS_PENDING"
}

Next: tail progress with StreamBuildLogs, then read the result with GetBuild.

`GetBuild`

Fetches the full Build record by id — including final status, the pushed imageRefs, and metrics.

Request

HTTP


curl -sS "https://api.dev.dodil.io/v1/ignite/builds/bld_01HZX9ABCD" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

GetBuildResponse { Build build = 1; } — the full Build.

HTTP


{
  "build": {
    "id": "bld_01HZX9ABCD",
    "name": "my-data-processor",
    "organizationId": "acme-corp",
    "status": "BUILD_STATUS_SUCCEEDED",
    "dockerfile": "Dockerfile",
    "imageRefs": [
      "registry.example/acme-corp/my-data-processor:v1",
      "registry.example/acme-corp/my-data-processor:latest"
    ],
    "buildArgs": { "NODE_ENV": "production", "NPM_TOKEN": "***" },
    "createdAtMs": "1748390400000",
    "startedAtMs": "1748390402000",
    "completedAtMs": "1748390461000",
    "error": "",
    "metrics": {
      "durationMs": "59000",
      "contextSizeBytes": "2480000",
      "imageSizeBytes": "184320000",
      "layerCount": 11,
      "cacheUsed": true
    }
  }
}

The `Build` record

Field (proto)	HTTP (pbjson)	Type	Notes
`id`	`id`	string	Build id.
`name`	`name`	string	Build / image name.
`organization_id`	`organizationId`	string	Owning organization.
`status`	`status`	`BuildStatus`	Current state.
`dockerfile`	`dockerfile`	string	Dockerfile path used.
`image_refs`	`imageRefs`	repeated string	Full `registry/org/name:tag` refs the build pushed.
`build_args`	`buildArgs`	map`<string, string>`	Build args; secret values are redacted to ``*.
`created_at_ms`	`createdAtMs`	int64	Submission time, ms epoch. JSON string.
`started_at_ms`	`startedAtMs`	int64	Build start, ms epoch. JSON string.
`completed_at_ms`	`completedAtMs`	int64	Build end, ms epoch. JSON string.
`error`	`error`	string	Failure reason; empty on success.
`metrics`	`metrics`	`BuildMetrics`	Build statistics.

BuildMetrics:

Field (proto)	HTTP (pbjson)	Type	Notes
`duration_ms`	`durationMs`	int64	Wall-clock build duration. JSON string.
`context_size_bytes`	`contextSizeBytes`	int64	Size of the build context. JSON string.
`image_size_bytes`	`imageSizeBytes`	int64	Size of the produced image. JSON string.
`layer_count`	`layerCount`	uint32	Number of image layers.
`cache_used`	`cacheUsed`	bool	Whether cached layers were reused.

`ListBuilds`

Lists recent builds for the calling organization, newest first.

Request

Field (proto)	HTTP (pbjson)	Type	Notes
`limit`	`limit`	int32	Max results. Default 20, max 100.
`status_filter`	`statusFilter`	`BuildStatus`	Only return builds in this state.

HTTP


curl -sS "https://api.dev.dodil.io/v1/ignite/builds?limit=50&statusFilter=BUILD_STATUS_SUCCEEDED" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

HTTP


{
  "builds": [
    {
      "id": "bld_01HZX9ABCD",
      "name": "my-data-processor",
      "status": "BUILD_STATUS_SUCCEEDED",
      "imageRefs": ["registry.example/acme-corp/my-data-processor:v1"],
      "createdAtMs": "1748390400000"
    }
  ]
}

Each entry is a full Build.

`StreamBuildLogs`

Server-streaming build log — each message is a chunk of raw build output. The build log is persisted, so you can attach at any time: set from_start to true to replay the full log from the beginning, or false to tail from the current position. The stream ends when the build reaches a terminal BuildStatus.

Request

Field (proto)	HTTP (pbjson)	Type	Notes
`build_id`	`buildId`	string	Path parameter `{build_id}`.
`from_start`	`fromStart`	bool	`true` replays the full persisted log; `false` tails from now.

HTTP


curl -sS -N "https://api.dev.dodil.io/v1/ignite/builds/bld_01HZX9ABCD/logs/stream?fromStart=true" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

Server-stream of BuildLogChunk messages, one per chunk of build output, until the build finishes:


message BuildLogChunk {
  bytes data        = 1;                // raw log output (base64 over JSON)
  int64 timestamp_ms = 2;               // chunk timestamp, ms epoch
}

Over HTTP each chunk arrives as a newline-delimited JSON object; data is base64 in JSON and raw bytes over gRPC. After the stream ends, call GetBuild for the final status, imageRefs, and metrics.

`CancelBuild`

Requests cancellation of a pending or running build. Terminal builds are unaffected.

Request

HTTP


curl -sS -X POST "https://api.dev.dodil.io/v1/ignite/builds/bld_01HZX9ABCD/cancel" \
  -H "Authorization: Bearer $DODIL_TOKEN"

Response

HTTP


{
  "status": "BUILD_STATUS_CANCELLED"
}

Builds — API Reference

CreateBuild

Request

HTTP

gRPC

Response

HTTP

gRPC

GetBuild

Request

HTTP

gRPC

Response

HTTP

gRPC

The Build record

ListBuilds

Request

HTTP

gRPC

Response

HTTP

gRPC

StreamBuildLogs

Request

HTTP

gRPC

Response

CancelBuild

Request

HTTP

gRPC

Response

HTTP

gRPC

See also

`CreateBuild`

`GetBuild`

The `Build` record

`ListBuilds`

`StreamBuildLogs`

`CancelBuild`