> ## Documentation Index
> Fetch the complete documentation index at: https://docs.songbird.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Start a loop on demand, on a schedule, or when an event happens in another system.

***

A **trigger** is what starts a loop. Every loop has exactly one, and it's one of three kinds.

> **On demand**
>
> Runs when someone explicitly chooses: click "Run now" in the Songbird app, or ask Songbird in Slack.

> **Schedule**
>
> Runs on a regular cadence, such as "every weekday at 9am" or "every 12 hours."

> **Event**
>
> Runs when something happens in Slack, GitHub, or Linear, such as a message in a channel, a merged PR, or an issue moving to Done.

## Setting a trigger

The easiest way is to say what you want. Tell the Songbird agent "run this every Monday at 8am" or "run this whenever a PR merges in the web repo," and it fills in the trigger for you. You can also choose a trigger type in the loop editor and fill in the details yourself.

## Event triggers

Event triggers let a loop respond the moment the business changes, instead of checking on a timer.

### Where events come from

Events come from three **Organization apps**: Slack, GitHub, and Linear. An Organization app is installed once for the whole Organization and can trigger any loop, in My loops or in a space. They are the only connections that can trigger loops. See [Connections](/connections.md).

If an app isn't set up yet, its trigger option appears greyed out with a **Set up** link. Anyone in the Organization can set one up, though the provider may also ask for its own approval, for example from a GitHub org owner.

### How events are narrowed

Two boundaries decide which events reach a loop.

**1. The installer sets the outer boundary**

When someone installs an Organization app, they choose what Songbird can see in that provider's own settings. For GitHub, that's the repositories the Songbird app is installed on. For Slack, it's the public channels the Songbird bot has been added to. Events from anywhere else never reach Songbird.

**2. Each loop narrows further**

A loop's trigger picks one event type and can filter on its fields.

| Provider | Filter by |
| - | - |
| **Slack** | Channel, author |
| **GitHub** | Repository, PR action |
| **Linear** | Team, label, state |

### The event is the run's input

When a trigger fires, the event that matched (the Slack message, the GitHub PR, the Linear issue change) is passed into the run. Any step can read it, for example "Summarize the PR that started this run and check it against our release checklist."

### Built-in guardrails

* **No self-triggering.** Anything Songbird does itself, such as posting in Slack or commenting through an Organization app, never fires a trigger. A loop can't set itself or another loop off.
* **Rate limit.** Each loop can run up to 15 times per hour from events. If it hits the limit, it pauses instead of running away.

## When an event-triggered loop pauses

An event-triggered loop pauses, and shows why in its header and in loop lists, in two cases.

| Status | Cause | To resume |
| - | - | - |
| **Paused: too many events** | The loop hit its hourly rate limit. | Resume it manually. |
| **Paused: connection removed** | The Organization app it depends on was disconnected. | Reconnect the app, or change the trigger. |

## Common questions

> **Can a loop have more than one trigger?**
>
> Not yet. Each loop has one trigger today. If you want the same work to run on a schedule and on an event, duplicate the loop and give each copy its own trigger. Smarter triggers are on the near-term roadmap.

> **Can I trigger a loop from a private Slack channel?**
>
> No. Slack event triggers work in public channels the Songbird bot has been added to, and all channel members can view (but not edit) the loop instructions.

> **Can I trigger a loop from a webhook or another system?**
>
> Not yet. Event triggers currently come from Slack, GitHub, and Linear. Webhook triggers, and triggering one loop from another, are next on the roadmap. In the meantime, another way to accomplish this need is to create a scheduled loop whose first step is to check any connected system for a change (with a stop condition, if the trigger you want did not occur).

> **Can I use a GitHub or Linear connection I made myself to trigger a loop?**
>
> No. Personal and shared connections to GitHub and Linear can be used by steps to read and write, but only the Organization app can trigger loops.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.