Build a HarnessRelease from a GitHub repository

Submits an async Organization-owned build from a GitHub repository URL plus an optional ref and a protocol-exact ACP or one-shot process contract. The request separately names either a platform build pool or an exact Workspace and RunnerPool execution target; ownership never implies execution authority. The ref is resolved to an exact commit at submission and frozen. Accepted with 202 and a pending HarnessBuild; a Workspace-targeted build settles only when a build-capable Runner from the exact named pool claims it. Terminal success references an immutable, digest-pinned HarnessRelease, while terminal failure carries a bounded reason and optional builder log. Re-registering is a new build resolved afresh. Send Idempotency-Key so a retry does not open a second build.

Checkfu support posture: alpha; hosted. Required evidence journey: harness-registry. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/organizations/{organization_id}/harness-builds

Build a HarnessRelease from a GitHub repository

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/organizations/{organization_id}/harness-builds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "repository": "<string>",
  "build_execution_target": {
    "type": "platform",
    "build_pool_id": "<string>"
  },
  "entrypoint": "<string>",
  "ref": "<string>",
  "working_directory": "<string>",
  "configuration_schema": true,
  "model_wire_dialects": [],
  "argv": "<unknown>",
  "prompt_transport": "<unknown>",
  "output_mode": "<unknown>",
  "resume_flag": "<unknown>",
  "output_schema_flag": "<unknown>",
  "output_schema_transport": "<unknown>",
  "protocol": "acp-v1",
  "arguments": [
    "<string>"
  ]
}
'

202

{
  "id": "<string>",
  "organization_id": "<string>",
  "build_execution_target": {
    "type": "platform",
    "build_pool_id": "<string>"
  },
  "status": "pending",
  "source": {
    "kind": "github",
    "repository": "<string>",
    "commit_sha": "<string>"
  },
  "entrypoint": "<string>",
  "working_directory": "<string>",
  "platform": {
    "os": "linux",
    "architecture": "amd64"
  },
  "configuration_schema": true,
  "attempts": 1,
  "created_at": "<string>",
  "completed_at": "<string>",
  "protocol": "acp-v1",
  "arguments": [
    "<string>"
  ],
  "model_wire_dialects": [
    "anthropic_messages"
  ],
  "release_id": "<string>",
  "failure": {
    "reason": "ref_resolution_failed",
    "detail": "<string>",
    "log": "<string>"
  },
  "argv": "<unknown>",
  "prompt_transport": "<unknown>",
  "output_mode": "<unknown>",
  "resume_flag": "<unknown>",
  "output_schema_flag": "<unknown>",
  "output_schema_transport": "<unknown>",
  "mcp_delivery": "session_http"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-24

idempotency-key · string

Maximum string length: 255

Path Parameters

organization_id · string · required

Pattern: ^org_[0-9a-f]{32}$

Body

application/json

Option 1

Option 2

A GitHub source/ref plus the exact ACP or one-shot process contract the resulting immutable release will carry

repository · string · required

Pattern: ^https:\/\/github\.com\/[A-Za-z\d](?:[A-Za-z\d-]{0,38})\/[A-Za-z\d._-]{1,100}$

build_execution_target · object · required

Option 1

Option 2

Show child attributes

entrypoint · string · required

Maximum string length: 4096

Pattern: ^\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+)*$

ref · string

Required string length: 1 - 1024

Pattern: ^\S+$

working_directory · string

Maximum string length: 4096

Pattern: ^\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+)*$

platform · object

Show child attributes

configuration_schema · boolean object

model_wire_dialects · enum<string>[]

Required array length: 1 - 4 elements

Available options: anthropic_messages, openai_chat, openai_responses, fal_queue

argv · any

prompt_transport · any

output_mode · any

resume_flag · any

output_schema_flag · any

output_schema_transport · any

protocol · enum<string>

Available options: acp-v1

arguments · string[]

At most 256 exact process arguments and 131072 aggregate UTF-8 bytes including one terminator per argument

Maximum array length: 256

Exact process argument text, preserving whitespace; U+0000 is forbidden and UTF-8 encoding is limited to 65536 bytes

Maximum string length: 65536

Pattern: ^[^\u0000]*$

mcp_delivery · enum<string>

Available options: session_http, none

Response

202

application/json

An async custom-harness build whose exact ACP or one-shot process contract is frozen with its source commit

Option 1

Option 2

An async custom-harness build whose exact ACP or one-shot process contract is frozen with its source commit

id · string · required

Pattern: ^hbld_[0-9a-f]{32}$

organization_id · string · required

Pattern: ^org_[0-9a-f]{32}$

build_execution_target · object · required

Option 1

Option 2

Show child attributes

status · enum<string> · required

Available options: pending, succeeded, failed

source · object · required

Show child attributes

entrypoint · string · required

Maximum string length: 4096

Pattern: ^\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+)*$

working_directory · string · required

Maximum string length: 4096

Pattern: ^\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+)*$

platform · object · required

Show child attributes

configuration_schema · boolean object · required

attempts · integer · required

Required range: x >= 0

created_at · string · required

completed_at · string | null · required

protocol · enum<string> · required

Available options: acp-v1

arguments · string[] · required

At most 256 exact process arguments and 131072 aggregate UTF-8 bytes including one terminator per argument

Maximum array length: 256

Exact process argument text, preserving whitespace; U+0000 is forbidden and UTF-8 encoding is limited to 65536 bytes

Maximum string length: 65536

Pattern: ^[^\u0000]*$

model_wire_dialects · enum<string>[]

Required array length: 1 - 4 elements

Available options: anthropic_messages, openai_chat, openai_responses, fal_queue

release_id · string

Pattern: ^hrel_[0-9a-f]{32}$

failure · object

Show child attributes

argv · any

prompt_transport · any

output_mode · any

resume_flag · any

output_schema_flag · any

output_schema_transport · any

mcp_delivery · enum<string>

Available options: session_http, none