Set up pipeline triggers
Este conteúdo ainda não está disponível no seu idioma.
A trigger is what starts a pipeline. Each one is a node on the canvas, dropped from the Triggers section of the node library. Selecting that node opens its inspector on the right — there is no always-on triggers list, no triggers tab, and no triggers screen.
Open a trigger inspector
Section titled “Open a trigger inspector”- Go to Settings → Workspace → Pipeline templates.
- Press the pencil on the template’s row to open the editor.
- Select a trigger node on the canvas. The right panel appears with that trigger’s settings. With nothing selected, the panel is hidden.
Add a trigger
Section titled “Add a trigger”The Triggers section of the node library lists every start kind as its own
node: manual, schedule, webhook, and one card per domain event. Search for
merged, ticket, or the type name (PrMerged) and drag the card onto the
canvas. A new template also shows an Add a trigger ghost tile at the entry
anchor — pick from the same searchable list.
The trigger is inserted immediately. New automatic triggers start disabled so a drop does not fire a run before you have configured it. Use the inspector’s Enabled switch to turn it on, or the bin icon to delete it.
Allow manual runs
Section titled “Allow manual runs”Drop Manual run (or pick it from the ghost tile) and turn on Enabled in
its inspector. That is what makes the template appear in the run launcher. It
is not a special case — the switch writes an ordinary trigger row whose event
type is manual. It persists immediately; there is nothing to save.
The same switch is behind Manual run in the editor header, where it sits alongside the template’s declared inputs.
On an event
Section titled “On an event”These events start a run:
| Picker label | Event |
|---|---|
| External PR opened | ExternalPrDetected |
| PR published | PullRequestPublished |
| PR status changed | PullRequestStatusChanged |
| PR merged | PrMerged |
| Message received | MessageReceived |
| Ticket created | TicketCreated |
| Ticket status changed | TicketStatusChanged |
| Ticket assigned | TicketAssigned |
| Ticket completed | TicketCompleted |
| Ticket failed | TicketFailed |
| Ticket cancelled | TicketCancelled |
| Budget threshold crossed | BudgetThresholdCrossed |
| Repository added | RepoAdded |
| Meeting recording stopped | MeetingRecordingStopped |
| Skill updated | SkillUpdated |
| Space deleted | SpaceDeleted |
SpaceDeleted is what the built-in worktree-cleanup pipeline listens on: it
carries the deleted space’s id, so the run reclaims exactly that space’s
worktrees instead of sweeping the whole workspace.
For the payload keys each event carries, see the domain events reference.
Filter an event trigger
Section titled “Filter an event trigger”Select the PR status changed node. The inspector’s status chips are the
only filter the UI can author. Tap any of merged, closed, approved,
opened, reopened; the trigger then fires only when the event’s status
matches one of them. Leaving every chip unselected means no filter.
There is no free-form JSON filter field. A filter key that the event’s payload does not carry never matches, so do not hand-author one against a key you have not confirmed in the domain events reference.
On a schedule
Section titled “On a schedule”Select the Schedule node to edit when it fires. The inspector fields persist as you leave them:
| Field | Description |
|---|---|
| Schedule (cron or every:seconds) | A five-field cron expression such as 0 9 * * 1, or an interval such as every:86400. A bare number is coerced to every:<n>. |
| Timezone (optional) | An IANA zone such as Europe/Paris. Defaults to UTC. |
| On missed runs | What to do about fires missed while the server was down: Run once collapses every missed slot into one fire on restart (the default), Skip resumes at the next future slot. |
The canvas tile’s summary line only spells out the interval for the
every:<seconds> form; a cron expression shows as just “Schedule”.
Via a webhook
Section titled “Via a webhook”Dropping Webhook mints a random token. Select the node to copy the path
POST /webhooks/<token> from the inspector.
The token is also the HMAC secret: the request must carry
X-Hub-Signature-256: sha256=<hex>, where the hex is HMAC-SHA256(body, token).
A delivery that fails verification is rejected and logged and is not
replayable. Duplicates are ignored by their dedupe key.
Each start is its own graph node. Pulling a wire from Schedule attaches only Schedule; Manual run can take a different path (for example a condition node) before it joins the same work. A run enters the start that matches its event type and skips subgraphs that belong to the other starts.
How a trigger reaches a run
Section titled “How a trigger reaches a run”An enabled trigger whose event type and filter both match starts a run with the
event’s payload as the run’s trigger payload — that is what {{key}} in a
step’s prompt or script resolves against. Events that carry a natural key are
de-duplicated, so the same event firing twice does not start two runs.
A disabled template is refused even when its trigger matches. Eight of the thirteen built-in templates ship disabled, so their seeded triggers fire into nothing until you turn the template on.
Useful patterns
Section titled “Useful patterns”- Gate only the manual path — wire Manual run through a condition node, and Schedule straight to the work. Each start owns its own wires.
- Review every new PR — event PR published on the
pr_reviewtemplate. - Clean up after a merge — event PR status changed, filtered to
merged/closed/approved. The built-inpr_merged_cleanuptemplate already listens this way, plus ticket completed/cancelled,SpaceDeleted, and a daily schedule that is force-enabled on every re-seed because it is garbage collection. - Nightly sweep — schedule
0 2 * * *with a timezone, on a template whose first node is a bash script. - React to an external system — a webhook trigger, with the calling system signing its request body as above.