0010. Build trigger: a new commit on a Mirror builds a Workload¶
Status: Proposed (2026-11-11)
From #914 (a push starts a build), with the owner's decisions of 2026-11-11 recorded on the issue.
The answer¶
A Trigger of the build reef names a Workload (here triton, the Workload of catalog/workloads/triton.yaml, whose source is this repository). Its Nereid follows the scm reef's Mirror of that Workload's repository and, whenever the Mirror's status.commit changes, creates a Build of that commit. Each Nereid writes only its own reef's objects: the forgejo Nereid keeps the Mirror's commit, the buildkit Nereid creates the Builds.
$ nereus scm mirror create nereus --from https://github.com/getnereus/nereus
✓ scm/mirrors/nereus created (mandate forgejo)
$ nereus build trigger create triton --workload triton
build/triggers/triton created (mandate: buildkit, nereid: buildkit)
Next steps:
nereus build trigger get triton
$ git push origin main # the Mirror pulls it on its interval
$ nereus build trigger list
TRIGGER WORKLOAD MIRROR COMMIT LAST BUILD STATUS
triton triton nereus a1b2c3d triton-a1b2c3d Ready
$ nereus build list
BUILD WORKLOAD COMMIT STATUS DIGEST
triton-a1b2c3d triton a1b2c3d Succeeded sha256:4f2a…
Decided (owner, 2026-11-11)¶
- The build reef turns a commit into a Build, not the scm reef's webhook receiver: no Nereid writes another reef's objects.
- Webhook or watching is the Mirror's choice. The forgejo Nereid already reads each Mirror's head on every pass (15 s), which is the watching mode; Forgejo's webhook, which shortens that by at most one pass, is a later slice (
nereus scm mirror create --webhook). The build side is the same for both. - The opt-in is a kind of the build reef,
Trigger, not a field of the Workload: the catalog reef stays as it is, and deleting the Trigger stops it. - A new Trigger builds the commit the Mirror holds now, without waiting for the next one: its list shows a result at once.
- A burst of pushes builds the last commit only: while a Build of the Trigger is not over (no phase yet,
PendingorRunning), nothing new starts, which bounds the builds, as spec 0009 asks. - Deleting a Trigger keeps its Builds: a Build is an image in the registry; the Trigger only automates them.
The Trigger kind¶
Cluster-scoped, as a Build, a Workload and a Mirror are (reefs/build/triggers.yaml).
spec.workload(required, never changes): the Workload of the catalog reef it builds.spec.owner(an Organization or a Project): the owner of every Build it creates; absent, the Builds have none, as a Build created by hand.spec.mandate: a build Mandate, so the Nereid that serves it and builds; absent, the reef's default.status:nereid,mirror(the Mirror it follows),branch,commit(the last commit it saw on the Mirror),lastBuild(the Build it created last) and theReadycondition.
What the Nereid does on each pass¶
- Reads the Workload. None:
NoWorkload. A Workload with nospec.source.repository:NoSource. - Finds the Mirror whose
spec.fromis that repository (same host, owner and name, any case, with or without.git). None:NoMirror. More than one: the oldest, as the forgejo Nereid does. - The Mirror is not
Ready:MirrorNotReady. The Workload names a branch other than the Mirror'sstatus.branch:OtherBranch(a Mirror follows its default branch only). - The Build it made last is
PendingorRunning: nothing new (Building); intermediate commits are skipped, so a burst of pushes builds the last one. - Otherwise, when no Build of the Mirror's commit exists for this Trigger, it creates
<trigger>-<first 7 digits of the commit>(the Trigger's name cut to 55 characters), with the Workload, the full commit, the Trigger's owner and Mandate, and the labelbuild.getnereus.dev/trigger: <trigger>. A Build of that name that is not this Trigger's:NameTaken. ThenReady, withcommitandlastBuild.
The details of those steps:
- A Build with no phase yet counts as not over, as
Pendingdoes (step 4). status.commitis the Mirror's commit the Trigger saw on its last pass, built or not yet.- The cut name loses a trailing hyphen before
-<commit>, so it never holds--. - The Build carries the Trigger's
spec.mandateonly when it names one; with none, the Build names none either and gets the reef's default, as a Build created by hand.
A new Trigger builds the commit the Mirror holds when it is created. A Build it created is never deleted by it: deleting the Trigger leaves its Builds.
Security (OWASP)¶
- A08, software and data integrity: only the commits a Mirror pulled are built, from the repository the Workload names; nothing outside the cluster can name a commit. The Forgejo webhook slice adds its signature check before it changes anything.
- A01, broken access control: a Trigger's Builds carry its owner, so the gates of spec 0009 hold: in portable mode only an operator's Builds run, a team's ends
SandboxRequired. A Trigger cannot give its Builds an owner the person could not give a Build by hand (the CLI checks it as fornereus build create). - CI/CD-SEC-04, poisoned pipeline execution: a Mirror pulls a branch, never a fork's pull request.
- Bounded builds: at most one Build of a Trigger runs at a time (step 4).
Stand-ins¶
None: the trigger watches the Mirror's status; the webhook is a later slice, not a stand-in.
Done when¶
make test: the buildkit Nereid's unit tests cover each step above; the CLI's covernereus build trigger create|list|get|delete.make scene-build(owner, 2026-11-12): a Build fetches its Workload's repository from upstream, and its fetch never reaches a private address (#1141), so a fake Git host in the cluster cannot end inSucceeded. The scene has two acts instead. First, a public repository: a Mirrorbuild-fixturesofgetnereus/build-fixtureson GitHub, a Workloadfixturesof itsmainand the Triggerfixtures, which builds the Mirror's commit at once,Succeededwith the registry's digest; this repository and its Workloadtritontake their place once it is public (#1337), since a Mirror of a private repository needs a credential (#1396). Second, a push: a Mirrorappof the fake Git host and a Triggerapp; a commit on the fake reaches the Mirror within a pass and makes a Build of that commit, whose fetch fails since the host is private. The rule of a burst of pushes (one Build at a time, the last commit) stays in the unit tests, since the fake's fetch fails in seconds.
What is left to other issues¶
- Forgejo's webhook (
--webhookon a Mirror), which updates the Mirror's commit at once. - A branch other than the Mirror's default branch.
- A quota per repository across Triggers.
Learn more¶
- OWASP, Top 10 CI/CD Security Risks, CICD-SEC-04.
- Flux, image automation: a controller that follows a source and acts on a new revision, the shape a Trigger takes here.