Create a new build

client.Builds.New(ctx, body) (*Build, error)

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 BuildNewParams

Source param.Field[Reader]

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

formatbinary

BaseImageDigest param.Field[string]optional

Optional pinned base image digest

CacheScope param.Field[string]optional

Tenant-specific cache key prefix

Dockerfile param.Field[string]optional

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

GlobalCacheKey param.Field[string]optional

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.

IsAdminBuild param.Field[string]optional

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 param.Field[string]optional

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

TimeoutSeconds param.Field[int64]optional

Build timeout (default 600)

ReturnsExpand Collapse

type Build struct{…}

ID string

Build job identifier

CreatedAt Time

Build creation timestamp

formatdate-time

Status BuildStatus

Build job status

Accepts one of the following:

const BuildStatusQueued BuildStatus = "queued"

const BuildStatusBuilding BuildStatus = "building"

const BuildStatusPushing BuildStatus = "pushing"

const BuildStatusReady BuildStatus = "ready"

const BuildStatusFailed BuildStatus = "failed"

const BuildStatusCancelled BuildStatus = "cancelled"

BuilderInstanceID stringoptional

Instance ID of the builder VM (for debugging)

CompletedAt Timeoptional

Build completion timestamp

formatdate-time

DurationMs int64optional

Build duration in milliseconds

formatint64

Error stringoptional

Error message (only when status is failed)

ImageDigest stringoptional

Digest of built image (only when status is ready)

ImageRef stringoptional

Full image reference (only when status is ready)

Provenance BuildProvenanceoptional

BaseImageDigest stringoptional

Pinned base image digest used

BuildkitVersion stringoptional

BuildKit version used

LockfileHashes map[string, string]optional

Map of lockfile names to SHA256 hashes

SourceHash stringoptional

SHA256 hash of source tarball

Timestamp Timeoptional

Build completion timestamp

formatdate-time

QueuePosition int64optional

Position in build queue (only when status is queued)

StartedAt Timeoptional

Build start timestamp

formatdate-time

Create a new build

package main

import (
  "bytes"
  "context"
  "fmt"
  "io"

  "github.com/kernel/hypeman-go"
  "github.com/kernel/hypeman-go/option"
)

func main() {
  client := hypeman.NewClient(
    option.WithAPIKey("My API Key"),
  )
  build, err := client.Builds.New(context.TODO(), hypeman.BuildNewParams{
    Source: io.Reader(bytes.NewBuffer([]byte("some file contents"))),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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"
}