Skip to content

Discovery worker ​

Development preview

This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.

The private ngit-ci-discovery-worker endpoint separates Git discovery from coordinator signing keys and repository secrets. It is coordinator plumbing, not an execution provider or an alternative to whole-job VMs. Workflow matching and allocation policy remain in the coordinator.

Native coordinator startup and discovery/diff use this endpoint, with NixOS and native Compose wiring. The deployment qualification summary links the recorded acceptance evidence and its limits. Legacy act-only coordinators retain their existing path.

Run it as a dedicated, non-root service account with no credentials. The coordinator rejects a root or same-account worker; the worker rejects a same-account caller (a root administrator may connect). Protect the socket's parent from writes by other users; grant only the coordinator service group access to the mode-0660 socket. The worker requires a private mode-0700 work directory. Never mount coordinator state, credential directories or provider sockets into its filesystem. A different UID is not a kernel security boundary and does not by itself hide world-readable host files; deployments must also restrict its filesystem view. No .env or coordinator config is loaded by the executable. Before binding the socket, the worker exercises its private temporary-home creation and git --version. Missing Git or unusable temporary storage is a startup error, not a misleading five-minute wait for repository propagation. Before loading signing keys, the coordinator waits up to 30 seconds for the worker handshake. Missing or not-yet-listening sockets are retried; permission, peer-identity and protocol errors fail immediately. The deadline also bounds a connected worker that does not reply. There is no in-process fallback. The private /tmp mount must be writable by the worker (mode 1777 in NixOS).

CLIEnvironmentRequired
--socketNGIT_CI_DISCOVERY_WORKER_SOCKETAbsolute private Unix socket path
--work-dirNGIT_CI_DISCOVERY_WORKER_WORK_DIRAbsolute worker-only checkout directory

The local protocol uses a four-byte big-endian length followed by JSON, one operation per connection. Requests are bounded to 1 MiB, responses to 32 MiB. Operations are protocol-1 readiness, discovery, push diff, PR diff and checkout release. Requests cannot choose a filesystem path, executable or environment. Socket permissions and Unix peer credentials provide local authorization; there is no TCP mode.

The worker admits at most four operations without queuing. Request reads have a ten-second deadline, operations a six-minute deadline and response writes a 30-second deadline. Caller disconnect, extra input and shutdown cancel work; the discovery Git process-group guards terminate its helpers. Errors have bounded diagnostics. Discovery retains its existing file/output limits and Git configuration restrictions.

Checkouts are worker-owned metadata state, not job workspaces. The endpoint retains them for the subsequent diff operation; the coordinator then explicitly releases them before queuing jobs. A cleanup failure leaves the trigger retryable. Interrupted planning can leave metadata until rediscovery or worker restart; it remains inside the bounded worker filesystem. The NixOS unit stores them under its private runtime directory on tmpfs; the Compose worker uses a private tmpfs. Both apply a 1-GiB memory cap with no swap allowance, one CPU and 128 tasks. Disabling swap matters because tmpfs pages are charged by the memory controller, and a resident-memory limit alone does not bound swapped-out metadata. The NixOS filesystem view uses systemd’s temporary filesystems and explicit bind mounts. Restart discards metadata; missing diff state remains unknown, matching existing path-filter semantics. Actual source checkout, Nix evaluation, builds and workflow commands continue to belong inside the disposable job VM.