Skip to Content
We are live but in Staging 🎉
BuildsAPI ReferenceUpload Context

Upload Context — API Reference

Package: dodil.ignite.v1 · Service: BuildService

UploadBuildContext uploads a build context (a tar.gz/zip of your source tree) ahead of a build and returns a context_id you then pass to CreateBuild as its context_id source.

gRPC only. UploadBuildContext is client-streaming — the client sends a sequence of messages and the server replies once at the end. The HTTP gateway cannot transcode client-streaming RPCs, so there is no HTTP endpoint for this method. Use gRPC, or the CLI (below).

When to use it

CreateBuild accepts a context three ways. Use UploadBuildContext when your context is too large for the inline zipped_code path, which must be under 4 MB. Upload the context once, then reference the returned context_id:

  1. Stream the archive with UploadBuildContext → get back a context_id.
  2. Call CreateBuild with context_id set as the source.

For git-based builds you don’t need this at all — use git_source on CreateBuild instead.

UploadBuildContext

Client-streaming. The first message must be metadata; every message after it carries a chunk of the archive bytes (roughly 512 KB per chunk is a good size). After the final chunk, the server returns a single UploadBuildContextResponse.

rpc UploadBuildContext(stream UploadBuildContextRequest) returns (UploadBuildContextResponse);
 
message UploadBuildContextRequest {
  oneof payload {
    UploadBuildContextMetadata metadata = 1;  // first message only
    bytes chunk                         = 2;  // subsequent messages, ~512 KB each
  }
}
 
message UploadBuildContextMetadata {
  string content_type        = 1;             // e.g. "application/gzip"
  string name                = 2;             // required
  uint64 expected_size_bytes = 3;             // optional; total archive size if known
}
 
message UploadBuildContextResponse {
  string context_id  = 1;                     // pass to CreateBuild as the context_id source
  uint64 size_bytes  = 2;                      // total bytes received (JSON string in pbjson)
}

Request

The protocol on the wire:

OrderMessageFields
1stmetadatacontent_type (e.g. application/gzip), name (required), expected_size_bytes (optional)
2nd…chunkchunk — a slice of the archive bytes, ~512 KB each

Because grpcurl reads a stream of JSON messages from stdin, a hand-rolled call would send the metadata message first and then one chunk message per slice of the archive. In practice this is awkward to do by hand — prefer the CLI.

Response

UploadBuildContextResponse { string context_id = 1; uint64 size_bytes = 2; }. Feed context_id straight into CreateBuild:

# after upload returns context_id "ctx_01HZX9..."
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",
    "tags": ["latest"],
    "contextId": "ctx_01HZX9ABCD"
  }'

Chunking an archive into a client stream by hand is fiddly. The CLI does the packaging, chunking, and context_id hand-off for you — it tars the directory, streams it, and can immediately start a build. See the CLI Guide.

See also

BuildsBuild Secrets