# Triggers

URL: https://docs.usestitch.ai/docs/triggers



An enabled trigger binds one harness, one sandbox, an `agentId`, and an `initialPrompt`.
GitHub or webhook events can start runs only after filters and admission guards pass.

## Schema [#schema]

[Triggers JSON Schema](/schema/triggers.json) · [Guard JSON Schema](/schema/guards.json)

| Field                | Contract                                                           |
| -------------------- | ------------------------------------------------------------------ |
| `key`, `name`        | Unique local key and display name                                  |
| `provider`           | `github` or `webhook`                                              |
| `harness`, `sandbox` | Existing local declaration keys                                    |
| `agentId`            | Non-empty kebab-case runtime agent ID                              |
| `initialPrompt`      | Non-empty instruction; at most 64 KiB                              |
| `enabled`            | Defaults to `true`; explicitly disable during setup                |
| `guards`             | At most 10; each guard type appears at most once; defaults to `[]` |

## Filters [#filters]

Filters inspect the incoming event, not prior runs. All configured filter conditions must pass.
For GitHub, select `eventType` and `actions`, then use only the fields supported by that event.
For webhooks, select `events` and a nested `payloadFilter`.
Unsupported combinations fail validation. Empty filters generally add no restriction,
but comment events need a comment selector or `matchAllComments`.

## Guards [#guards]

Guards inspect prior admissions or active runs. They are evaluated with run reservation.
They are not content filters, and they do not change the agent prompt.

| `type`            | Effect                              | Parameters                                          |
| ----------------- | ----------------------------------- | --------------------------------------------------- |
| `max_occurrences` | Limit admissions                    | `limit` 1–100 (default 3); optional `windowSeconds` |
| `cooldown`        | Require a gap between admissions    | Required positive `seconds`                         |
| `max_concurrent`  | Limit active runs                   | Required `limit` 1–100                              |
| `deduplicate`     | Skip previously admitted identities | Optional `windowSeconds`                            |

All guards accept `enabled` (default `true`) and a `scope`.
Time windows are positive integer seconds, at most 31536000.
Without a window, occurrence/deduplication guards consider all matching admission history.

| Scope        | Identity                                            |
| ------------ | --------------------------------------------------- |
| `repository` | Repository, within this trigger's admission history |
| `subject`    | Issue or pull request                               |
| `commit`     | Commit SHA                                          |
| `event`      | Event type, action, and event ID                    |
| `delivery`   | Delivery ID; `deduplicate` only                     |

`deduplicate` supports delivery/subject/commit/event, not repository.
Other guard types support repository/subject/commit/event, not delivery.
The event must also supply the selected identity. A missing identity skips admission;
it does not silently broaden the guard scope.

```yaml
guards:
  - type: max_concurrent
    scope: repository
    limit: 1
  - type: deduplicate
    scope: delivery
```

* [GitHub triggers](/docs/triggers/github)
* [Webhook triggers](/docs/triggers/webhook)