KEkernel

Create a new build

Changed on

Creates a new build job. Source code should be uploaded as a tar.gz archive in the multipart form data.

post/builds

Request

  • Base URL
    http://localhost:4973
  • URL
    http://localhost:4973/builds
  • Auth
    HTTP bearer

Request body multipart/form-data

sourcestring binary required

Source tarball (tar.gz) containing application code and optionally a Dockerfile

dockerfilestring

Dockerfile content. Required if not included in the source tarball.

base_image_digeststring

Optional pinned base image digest

builder_idstring

Optional Builder ID whose persistent cache disk backs this build. This is the only builder selector. One build at a time runs on a builder; builds for the same builder are serialized.

cache_scopestring

Tenant-specific cache key prefix

timeout_secondsinteger

Build timeout (default 600)

memory_mbinteger

Memory limit for builder VM in MB (default 2048)

cpusinteger

Number of vCPUs for builder VM (default 2)

image_namestring

Custom image name for the build output. When set, the image is pushed to {registry}/{image_name} instead of {registry}/builds/{id}.

secretsstring

JSON array of secret references to inject during build. Each object has "id" (required) for use with --mount=type=secret,id=... Example: [{"id": "npm_token"}, {"id": "github_token"}]

is_admin_buildstring

Set to "true" to grant push access to global cache (operator-only). Admin builds can populate the shared global cache that all tenant builds read from.

global_cache_keystring

Global cache identifier (e.g., "node", "python", "ubuntu", "browser"). When specified, the build will import from cache/global/{key}. Admin builds will also export to this location.

tagsstring

JSON object of tags. Example: {"team":"backend","env":"staging"}

Response

Build created and queued

idstring required

Build job identifier

status'queued' | 'building' | 'pushing' | 'ready' | 'failed' | 'cancelled' required

Build job status

tagsTags

User-defined key-value tags.

queue_positioninteger nullable

Position in build queue (only when status is queued)

image_digeststring nullable

Digest of built image (only when status is ready)

image_refstring nullable

Full image reference (only when status is ready)

errorstring nullable

Error message (only when status is failed)

created_atstring date-time required

Build creation timestamp

started_atstring date-time nullable

Build start timestamp

completed_atstring date-time nullable

Build completion timestamp

duration_msinteger nullable

Build duration in milliseconds

builder_instance_idstring nullable

Disposable VM instance that executed this build; distinct from builder_id

builder_idstring nullable

Persistent Builder resource whose cache backed this build

Example response

{
  "id": "build-abc123",
  "tags": {
    "team": "backend",
    "env": "staging"
  }
}

Changes

  • 9787f2320a2eRevision changes
    • info

      added the non-success response with the status

  • b00eacfe26b2Revision changes
    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status