Create a new build

client.builds.create(, ?): Build { id, created_at, status, 9 more }

post/builds

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

ParametersExpand Collapse

body: BuildCreateParams { source, base_image_digest, cache_scope, 5 more }

source: Uploadable

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

formatbinary

base_image_digest?: string

Optional pinned base image digest

cache_scope?: string

Tenant-specific cache key prefix

dockerfile?: string

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

global_cache_key?: string

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.

is_admin_build?: string

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.

secrets?: string

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"}]

timeout_seconds?: number

Build timeout (default 600)

ReturnsExpand Collapse

Build { id, created_at, status, 9 more }

id: string

Build job identifier

created_at: string

Build creation timestamp

formatdate-time

status: BuildStatus

Build job status

Accepts one of the following:

"queued"

"building"

"pushing"

"ready"

"failed"

"cancelled"

builder_instance_id?: string | null

Instance ID of the builder VM (for debugging)

completed_at?: string | null

Build completion timestamp

formatdate-time

duration_ms?: number | null

Build duration in milliseconds

formatint64

error?: string | null

Error message (only when status is failed)

image_digest?: string | null

Digest of built image (only when status is ready)

image_ref?: string | null

Full image reference (only when status is ready)

provenance?: BuildProvenance { base_image_digest, buildkit_version, lockfile_hashes, 2 more }

base_image_digest?: string

Pinned base image digest used

buildkit_version?: string

BuildKit version used

lockfile_hashes?: Record<string, string>

Map of lockfile names to SHA256 hashes

source_hash?: string

SHA256 hash of source tarball

timestamp?: string

Build completion timestamp

formatdate-time

queue_position?: number | null

Position in build queue (only when status is queued)

started_at?: string | null

Build start timestamp

formatdate-time

Create a new build

import Hypeman from '@onkernel/hypeman';

const client = new Hypeman({
  apiKey: 'My API Key',
});

const build = await client.builds.create({ source: fs.createReadStream('path/to/file') });

console.log(build.id);

{
  "id": "build-abc123",
  "created_at": "2019-12-27T18:11:19.117Z",
  "status": "queued",
  "builder_instance_id": "builder_instance_id",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "duration_ms": 0,
  "error": "error",
  "image_digest": "image_digest",
  "image_ref": "image_ref",
  "provenance": {
    "base_image_digest": "base_image_digest",
    "buildkit_version": "buildkit_version",
    "lockfile_hashes": {
      "foo": "string"
    },
    "source_hash": "source_hash",
    "timestamp": "2019-12-27T18:11:19.117Z"
  },
  "queue_position": 0,
  "started_at": "2019-12-27T18:11:19.117Z"
}

Returns Examples

{
  "id": "build-abc123",
  "created_at": "2019-12-27T18:11:19.117Z",
  "status": "queued",
  "builder_instance_id": "builder_instance_id",
  "completed_at": "2019-12-27T18:11:19.117Z",
  "duration_ms": 0,
  "error": "error",
  "image_digest": "image_digest",
  "image_ref": "image_ref",
  "provenance": {
    "base_image_digest": "base_image_digest",
    "buildkit_version": "buildkit_version",
    "lockfile_hashes": {
      "foo": "string"
    },
    "source_hash": "source_hash",
    "timestamp": "2019-12-27T18:11:19.117Z"
  },
  "queue_position": 0,
  "started_at": "2019-12-27T18:11:19.117Z"
}