Skip to content
Build Perch
Browse documentation

Triggers

Short answer: A trigger is what fires a Workflow without you clicking Run: on a schedule, when an allowlisted email or Discord message arrives, when a file lands in a watched folder, or when another workflow finishes. Every trigger is attached from inside the workflow editor, and untrusted sources fail closed: an empty allowlist never fires.

What is a trigger?

Besides running a workflow manually, Build Perch supports five automated trigger types:

  • Schedule: once, hourly, daily, weekly, or every N minutes. All times use your local timezone.
  • Email: fires when a message arrives from an address on a sender allowlist you set, optionally scoped to a +tag address so several workflows can share one connected mailbox.
  • Discord: fires on a message in a specific channel from an allowlisted sender (matched by their Discord user ID, not their display name).
  • File: fires when a file is added or changed in a workspace folder you pick. Watches direct children only, not subfolders, and can’t watch the app’s own internal BuildPerch/ folder.
  • Workflow-chained: fires when another workflow finishes, on success, on failure, or either. This is how you build multi-workflow pipelines.

Triggers bind to a workflow, not directly to an agent; to put a single agent on a schedule or an inbound message, wrap it in a one-step workflow and attach the trigger there.

Email, Discord, and file triggers are untrusted inlets: a run they fire treats the incoming content strictly as data, withholds tools that fetch arbitrary URLs, and can only reply to the original sender; a triggered run can’t be redirected to send somewhere else by content in the inbound message.

How do I attach a trigger to a workflow?

  1. Open a workflow in the Workflows tab and open its trigger settings.
  2. Pick a trigger kind: Manual — run on demand, On a schedule, When an email arrives, When a Discord message arrives, When a file is added or changed, or After another workflow runs.
  3. For email or Discord, add the senders allowed to fire it; this list can’t be empty, or the trigger simply never fires.
  4. For a file trigger, pick the folder to watch. For a workflow-chained trigger, pick the upstream workflow and whether success, failure, or either should fire it.
  5. Save. The workflow now runs on its own. Check its card in the Workflows tab, or the History tab, for what fired and when.

Good to know

  • A sender allowlist is fail-closed by design: an empty allowlist means the trigger never fires.
  • A workflow runs on one trigger at a time; scheduling it again replaces the existing trigger rather than adding a second one.
  • Chained (workflow-after-workflow) triggers are depth-capped so one misconfigured chain can’t loop forever, and a global rate limit pauses all autonomous (non-manual, non-chat) runs if too many start within an hour. It’s a circuit breaker against a runaway automation; in normal use it never trips.
  • A file trigger won’t re-fire on a run’s own output: the trigger tracks what the workflow just wrote and skips it on the next check.
  • Pause all agents (tray icon) stops every autonomous run (schedules, inbound triggers, and chains) without touching anything you run manually.