Trigger node

Every workflow needs at least one trigger node. When a run starts, the engine begins at the trigger that fired. The step writes the run’s starting facts to trigger/run.json and succeeds at once.

Kinds

kind	Starts a run when	Keys
webhook	A GitHub delivery matches the event and conditions	event, conditions, debounceSeconds, maxRunsPerHour, ref (default or tags), priority
cron	A schedule fires	cron (five fields), tz, runsOn (aws or cloudflare), overlap
label	A label is added to an issue or pull request, or a /sf command asks for it	label, allowBots
finding	A scanner reports a finding of the listed severities	severity list: critical, high, medium, low
kanban	A card moves from one board list to another	fromList, toList
firewall	The Package Firewall, AI Firewall or sandbox egress sees something new	source, events, newTo, filters, ticketRepo
manual	A person starts the run, in the console or on a Pix call	none

finding and kanban triggers validate and publish, but the engine has no code path that fires them yet: GitHub deliveries match only webhook and label triggers.

Each kind has its own page:

• Triggers and webhook conditions covers webhook events, every condition, and the safeguards against storms and forks.
• Schedules covers cron.
• Labels and commands covers label and the sf: labels.
• Source events covers firewall.

Several triggers on one node

A trigger node can list more triggers under also. Each becomes its own trigger, and any of them starts the same graph:

{ "id": "n1", "type": "trigger", "title": "Weekday dependency sweep",
  "config": { "kind": "cron", "cron": "0 3 * * 1-5", "tz": "Australia/Melbourne", "runsOn": "aws",
              "overlap": "skip_if_running",
              "also": [ { "kind": "finding", "severity": ["critical", "high"] },
                        { "kind": "webhook", "event": "push", "ref": "default" },
                        { "kind": "label", "label": "belai:security" } ] } }

also entries cannot nest.

Priority

When one GitHub delivery matches several triggers, they fire in priority order, 1 first to 5, default 3. At most 6 runs start per delivery by default (factory.fanoutCap, 1 to 50). See Labels and commands.

What a run keeps of its trigger

A run started by an event keeps the event’s facts: the event and action, repository, pull request or issue number, head commit, branch, author, labels and whether it came from a fork. It does not keep titles, bodies or comment text, so a crew is never handed text an outsider wrote. The facts are on the run page and in the crew’s card.