Skip to main content
Early Access. Commands and behavior can change between releases.
A trigger is one entry in triggers: with three keys: a name, an on that matches an event, and a run that says what to start. run is either a stage, which starts a Factory run, or a command, which runs one agent session once.

​
Event → trigger → what runs

The diagram below shows which events start what. The trigger column reads on.source · on.event → run.stage or run.command. Narrow a match with filters under on: label, assignee or status for board events, branch for CI, and repo for both. branch takes a glob such as factory/*. A schedule trigger takes cron and tz instead. The reference lists every key. A board trigger only starts work on an item that has every pickup label and no hold label, and never on an item in triage. So assigning an unlabelled item to factory does nothing. The number of open runs is capped by limits.maxActiveRuns; a run over the cap waits in a queue.

​
Defaults

If your file has no triggers key, these three apply: Once you write a triggers list, it replaces the defaults: copy the ones you want to keep. triggers: [] turns off every trigger from the file.

​
How stages chain

Triggers only start work. After that, a run moves from stage to stage on its own, and waits for you at two gates. You open each gate with a label, never by typing a command. A run starts at plan from a run.stage: plan trigger, from architech factory runs start, or when CI fails on a branch no run owns. A run.stage: build trigger sends the run that owns the branch back to build. The label names above are the defaults; see label roles. How many gates apply depends on policy.autonomy, and a change to a protected path always waits for merge approval. See approvals and guards. architech factory runs show <run> lists each stage with its command.

​
Routines

A routine is a source: schedule trigger. When the clock reaches its time, one agent session runs one command, once. It creates no Factory run and passes no gate. The session appears in your workspace’s sessions list.
A schedule trigger has no event, and it can’t start a stage: run.stage is refused for it. Push the file to create or change the routine. Removing the trigger from the file and pushing removes the routine. Disabling the trigger pauses it.

​
Run a routine now

Test a routine, or run it outside its schedule:
fire takes the trigger’s name from factory.yaml. It reads the Factory from the local file; pass --factory <id> to pick another one. It works only for a schedule trigger, and only while the trigger and its Factory are enabled. Each call is a new firing. To retry a firing without running it twice, pass the same --key <key> both times.

​
Test an event trigger

To check which trigger an event would match, without starting anything:
An event file holds JSON such as {"kind":"board.label","data":{"label":"factory:pickup"}}. A disabled trigger never matches.