# Triggers (/web/triggers)



Triggers are the lightest routing surface for GitHub events.

Use them when the rule is simply:

`one event -> one agent`

If you need branching, delays, multiple agents, or a draft/publish workflow,
move up to [Automations](/web/automations).

## Why Triggers exists [#why-triggers-exists]

Triggers is the “do the obvious thing” surface.

It is for cases where you do not need a canvas, a repo-owned standing contract,
or a multi-step workflow. You just need one GitHub event on one installation to
wake one agent reliably.

## What a trigger binds [#what-a-trigger-binds]

Each trigger binds:

* one GitHub App installation
* one supported event type
* one agent
* an enabled or disabled state
* for mention triggers only, whether bare `@mogplex` mentions should route here

Triggers are installation-scoped, not repo-scoped. They listen to webhook
events from the selected GitHub App installation and then dispatch to the
chosen agent.

That scope is the main reason to choose Triggers over
[Assignments](/web/assignments): the installation is the source of truth, not a
single repo.

## Supported events [#supported-events]

Current trigger events are:

* `@mention`
* pull request opened
* issue opened
* pull request comment
* issue comment
* push
* CI failure

## Choose Triggers vs Assignments vs Automations [#choose-triggers-vs-assignments-vs-automations]

* Use **Triggers** when the rule should apply at the installation event layer.
* Use **Assignments** when a single repo should own standing work like PR
  review, CI failure response, or cron.
* Use **Automations** when one event should branch, delay, fan out, or publish
  as a workflow graph.

## Requirements [#requirements]

Triggers only work for repos covered by an installed GitHub App.

GitHub OAuth on its own is not enough. If the page is empty, or the creation
form says no installations are available, check
[Installations](/web/installations) and confirm the correct user or org has the
Mogplex GitHub App installed.

The creation form searches installations by both account scope and synced repos,
so this page is often the fastest way to notice that repos are synced but still
not webhook-covered.

## How to create a good trigger [#how-to-create-a-good-trigger]

When you create a trigger, the practical sequence is:

1. choose the GitHub App installation that owns the repos you care about
2. choose the event type that should wake work
3. choose the agent that should respond
4. for mention routes, decide whether this is the default route for bare
   `@mogplex`

Keep the rule as narrow as possible. If you feel tempted to explain branches,
follow-up steps, or parallel work in prose, the route probably belongs in
[Automations](/web/automations) instead.

## How creation works [#how-creation-works]

When you create a trigger, the form asks for:

1. the GitHub App installation to listen on
2. the event type
3. the agent to wake up

If the event is `@mention`, the form also shows whether the route should be the
default for bare `@mogplex` mentions. That toggle only exists for mention
triggers because it is not meaningful for the other event types.

If the selected agent already has a slug, the form shows the exact targeted
mention handle, such as `@mogplex/triage`. When you save the trigger, Mogplex
ensures the agent has a slug so targeted mention routing can resolve
consistently.

## Mention routing rules [#mention-routing-rules]

The most important detail is that GitHub mention syntax is exact.

* `@mogplex` is a bare mention
* `@mogplex/<agent-slug>` is a targeted mention

Example:

```text
@mogplex/triage summarize this PR thread and suggest next steps.
```

Rules:

* Bare `@mogplex` only routes to mention triggers marked as the default for
  that installation.
* `@mogplex/<agent-slug>` targets the trigger whose agent slug matches the text
  after `/`.
* The slash matters. `@mogplex triage` is not the same as
  `@mogplex/triage`.
* Mention routing comes from GitHub comment events, not from issue titles or PR
  titles.

For the full mention model, see
[GitHub Mention Routing](/web/guides/github-mention-routing).

## What healthy trigger operations look like [#what-healthy-trigger-operations-look-like]

Existing triggers are grouped by installation and show live operating signals,
including:

* enabled or disabled state
* the event badge and selected agent
* the agent slug when targeted mention routing is possible
* last run status and timestamp
* failed, running, pending, suppressed, and deferred counts
* the latest pressure reason when dispatch was intentionally held
* whether a mention trigger is the default target for bare `@mogplex`

The page is optimized for fast routing edits, so enable/disable and delete are
inline instead of hidden in a deeper detail view.

That means the trigger row is not just configuration. It is also the first
operational summary for whether the route is alive, under pressure, or failing.

## Good fits for Triggers [#good-fits-for-triggers]

Use Triggers when you want a direct event-to-agent mapping, for example:

* wake a review agent when a pull request opens
* wake a triage agent when a CI run fails
* route `@mention` events to a default repo assistant
* target a specific agent with `@mogplex/<agent-slug>`

If the durable unit is a specific repo instead of an installation, use
[Assignments](/web/assignments). If the workflow needs conditions, branches, or
multiple steps, use [Automations](/web/automations).

## Common mistakes [#common-mistakes]

* writing `@mogplex triage` instead of `@mogplex/triage`
* expecting OAuth-synced repos to appear before GitHub App coverage exists
* using Triggers when the logic really belongs to one repo and should be an
  [Assignment](/web/assignments)
* assuming bare `@mogplex` will route anywhere without a default mention route

## If routing does not fire [#if-routing-does-not-fire]

Check these in order:

1. the repo is covered by the correct GitHub App installation
2. the trigger is enabled
3. the event type matches what actually happened
4. if this is a mention:
   * bare `@mogplex` has a default mention route on that installation
   * targeted `@mogplex/<agent-slug>` matches the agent slug exactly
5. if the route still looks idle, inspect [Observability](/web/observability)
   for call activity and then return to the trigger row for pressure signals