builds

Cancel a build.

Handles both active builds (delegated to Build Coordinator) and pre-dispatch builds (cancelled FS-only via an atomic row lock).

The operation is idempotent with respect to terminal state. When the build has already reached a terminal state (cancelled, completed, failed, or timed_out) — whether Build Coordinator reports it or the local task row records it — the response is still 200 and the status field carries that terminal state. Coordinator statuses are normalized into the effective vocabulary before they are surfaced: BC's timed_out surfaces as timed_out, the same word a subsequent GET reconstructs from the footprint the callback path persists (status='failed' + error_class='timeout'), so the two surfaces always agree.

Cancelling a pre-dispatch build permanently retires its identity tuple: uq_factory_build_identity dedup treats the cancelled row like any other terminal build, so a later event expanding to the same identity inserts nothing. Recovery is manual by design — a cancel that ambient event traffic could overturn would not be a cancel.

Outcomes: 200 — Build cancelled, or already terminal. BuildResponse.status reflects the effective state. 404 — No build with the given ID. 409 — The coordinator does not know the build yet because its dispatch is in flight (the worker commits its claim before the HTTP submit). Retry with backoff. 502 — Build Coordinator unreachable or returned an unexpected error; or the coordinator has no record of a build whose dispatch window has long passed (lost to a restart or purge, or stranded by a worker that died between claim and submit).

An audit log line is emitted on every path, including unhandled exceptions (outcome=internal_error).

delete/api/v1/factory/builds/{build_id}

Request

  • The document declares no server URL.
  • Auth
    • HTTP bearer
    • or HTTP basic

Path parameters

build_idinteger required

Response

Build cancelled or already terminal; status field carries the outcome

build_idinteger required
status'pending' | 'running' | 'completed' | 'failed' | 'timed_out' | 'cancelled' required

Effective status of a build, derived server-side and never stored.

A dispatched build's task lifecycle is authoritative, with timed_out reconstructed from a failed task whose error class is 'timeout'; a build cancelled before dispatch is cancelled; an undispatched, uncancelled build is pending. These six values are exactly what the derivation can emit; emittable, filterable, and the whole vocabulary are the same set. The member order here is the documentation order.

source_repo_urlstring required
source_commit_shastring required
nixpkgs_revisionstring required
systemstring required
attr_pathstring required
build_typestring required
catalog_namestring required
exit_codeinteger nullable
created_atstring date-time required

Changes

    • info

      added the optional property to the response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status