Sign in
builds

Create a build

Creates a build for the pipeline and starts execution in-process. When pipeline_ir is supplied the IR is materialised directly; when it is absent the engine renders the pipeline's IR in a sandbox VM first (rendering never happens on the API host). A manual build against a pipeline that disallows manual builds yields 403; an IR that fails to render/parse/plan yields 422 (the build row is created with its error fields set).

post/api/v0/organizations/{org}/pipelines/{pipeline}/builds

Request

  • Base URL: https://api.harmont.dev
  • URL: https://api.harmont.dev/api/v0/organizations/{org}/pipelines/{pipeline}/builds
  • Auth: HTTP bearer

Path parameters

orgstring required

The organization slug.

pipelinestring required

The pipeline slug.

Request body

branchstring required

Source branch.

commitstring required

Source commit SHA.

envobject nullable

Build-level environment variables.

messagestring nullable

Optional build/commit message.

pipeline_irstring nullable

The pre-rendered v0 IR JSON the engine materialises into jobs. When absent/blank the engine renders the pipeline's IR in a sandbox VM instead.

sourcestring nullable

How the build was triggered (e.g. api, ui). Defaults to api.

source_b64string nullable

Base64-encoded source tarball (expected to be gzipped; the API validates only that it is valid base64, not the archive format) — the hm run local-code upload path. When present, the API stores it at the build's key and derives the internal, runner-token-authenticated source_url; it takes precedence over any caller-supplied source_url.

source_sha256string nullable

SHA-256 of the source archive, verified by the sandbox before rendering (in-sandbox-render path). Defaults to empty when omitted.

source_urlstring nullable

URL to the build's source archive, fetched by the sandbox. Ignored when source_b64 is supplied (the API derives this internally).

Response

The created build

branchstring nullable

Source branch.

commitstring nullable

Source commit SHA.

created_atstring date-time required

When the build row was created.

error_codestring nullable

Stable build-level error code, if the build failed at the build level.

error_messagestring nullable

Human-readable build-level error message, if any.

finished_atstring date-time nullable

When the build reached a terminal state.

messagestring nullable

Commit/build message.

numberinteger required

The build's number, sequential and unique within its pipeline.

pipeline_slugstring required

The global slug of the pipeline this build belongs to.

scheduled_atstring date-time nullable

When the build was queued.

sourcestring nullable

How the build was triggered (e.g. api, webhook, ui).

started_atstring date-time nullable

When the build started running.

state'scheduled' | 'running' | 'failing' | 'passed' | 'failed' | 'canceling' | 'canceled' required

The rolled-up build state.

Changes

No recorded changes to this operation across all 1 revision of this API.