Concepts
The vocabulary of bupha — each term defined once.
The pipeline shape
- Source — the ingest edge: a long-running producer of normalized
(repo, ref, sha, sender)pushes. Impls:github-webhook(HMAC-verified deliveries) andsturn-wal(WAL snapshot events). Trigger— the narrower per-request port a webhookSourcedrives: is this our event, which repo, does the signature verify, what does the payload ask for.- Push — the normalized job request every source emits; everything behind the queue is source-agnostic.
- Queue — per-job pending slots with a policy (
latest= latest-wins for gates,all= bounded FIFO for releases). Persisted via theQueueStoreport in dev; durable state is theci-jobentity plane in fleets. - Runner — how a job becomes a spawned process:
shell(bash),container(podman/docker),ssh,http(remotebupha agent),dagger,gha(workflow dialect). ghadialect vsgha-runner— two different products sharing a name:runner.kind = "gha"makes bupha read and execute.github/workflowsYAML;bupha gha-runnermakes bupha a self-hosted runner that GitHub's service drives via the actions/runner broker protocol.- Status sink — where run outcomes are reported: forge commit statuses (
ci/buphacontext by default, plus per-job detail under<context>/<workflow>/<job>).
Fleet and plane
- Bundle — a
type: buphatamias pack:tamias.yaml(provider units + ingress hooks) +fleet.toml(a complete watcher/worker config).libraries/ci-gate,docs-deploy,ci-ingressare the shipped examples. hostvsworker— the two service verbs:tamias-driver-bupha hostruns the standalone watcher (webhook → local queue → runner → status);workerpollsci-jobentities on the hypha/peregrin node and runs claimed jobs through the same pipeline. Enable ONE per ingress mode.- ci-job entity — a job as a hypha entity (
kind="ci-job", deterministic idci:{key}:{sha}:{attempt});ci.*ops carry enqueue/claim/renew/release/complete with fence + lease semantics. runs_onlabels — per-repo/job scheduling constraints (arch=arm64); a job runs only on workers whose[worker] labelssatisfy them.bupha agent— the remote executor behindkind = "http": tar worktree + poll over an HMAC-signed HTTP wire.
Dev harness
buphacommand — the dev/debug CLI behind thebins[]shim (bupha-cliis lib-only):run,doctor,watch,agent,gha-runner,import,deploy,service. Production fleets run through the driver verbs, not this binary.- Worktree — every run executes in a detached
git worktreeof the pushed sha at<base>-<repo>[-<job>]-<sha12>; never a shared dirty checkout.