# Triggers



A **trigger** runs an agent in response to a GitHub event. There are two lanes:
the zero-config **mention** lane and the opt-in **auto** lane.

## Mention lane (zero-config) [#mention-lane-zero-config]

Comment on a pull request with a mention and a built-in reviewer runs
immediately — no setup, no trigger to create:

* `@cluster-build review` — a standard code review.
* `@cluster-build megareview` — a deeper, multi-pass review.

Each mention creates a session that reviews the PR and posts back. Mention fires
are deduplicated per webhook delivery, so a re-delivered event won't run twice.

## Auto lane (your agents) [#auto-lane-your-agents]

The auto lane runs **your** agent whenever a matching GitHub event arrives on a
repo. Create a trigger to opt in.

<Tabs items="['Console', 'API']">
  <Tab value="Console">
    Open an agent's **Triggers** and add one: choose the repo, the events to fire on,
    and (optionally, under *Advanced*) a kickoff template. Triggers can be enabled and
    disabled in place.
  </Tab>

  <Tab value="API">
    `POST /v1/triggers`. `agent`, `repo`, and `events` are required.

    ```bash
    curl https://agents.clusterbase.dev/v1/triggers \
      -H "Authorization: Bearer $CLUSTER_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "agent": "agt_3f9c2a",
        "repo": "acme/web",
        "events": ["pull_request.opened"],
        "kickoff_template": "Review PR {{pr}} on {{branch}} in {{repo}}."
      }'
    ```

    ```json
    {
      "id": "trg_d4e5f6",
      "agent_id": "agt_3f9c2a",
      "source": "github",
      "repo": "acme/web",
      "events": ["pull_request.opened"],
      "kickoff_template": "Review PR {{pr}} on {{branch}} in {{repo}}.",
      "enabled": true
    }
    ```
  </Tab>
</Tabs>

| Field              | Notes                                                                                                                       |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `agent`            | The agent id to run. Must be one you own.                                                                                   |
| `repo`             | A GitHub `owner/name` slug.                                                                                                 |
| `events`           | A non-empty subset of the supported events (below).                                                                         |
| `kickoff_template` | Optional. Omit to use the agent's built-in kickoff.                                                                         |
| `deployment`       | Optional. A [deployment](/docs/agents/api-reference#deployments) that supplies the VM and vaults for each fire — see below. |

### Run in a VM [#run-in-a-vm]

By default a fire runs the agent directly. Set `deployment` and each fire runs
in the VM environment the deployment describes, carrying the deployment's
credential vaults — this is how a triggered run gets a VM and vault credentials.

Unlike a schedule, the trigger still names its own `agent`, and the deployment
must name the same one — a deployment for a different agent is rejected at
create with `400`. So is a deployment on a saved (`existing`) environment:
there's no caller around at fire time to provision against, so fires use fresh,
ephemeral VMs. The deployment's `kickoff` is unused — the GitHub event supplies
the message.

Every repo the deployment's environment configures must clone successfully —
the source PR repo and all of the agent's configured repos. If any of them is
missing, or its clone fails or completes with a warning (bad ref, missing repo,
no access), the fire fails outright: the VM is torn down and no session is
created, rather than starting the agent with a partial checkout.

### Supported events [#supported-events]

| Event                           | Fires when                             |
| ------------------------------- | -------------------------------------- |
| `pull_request.opened`           | A pull request is opened.              |
| `pull_request.ready_for_review` | A draft PR is marked ready for review. |

### Kickoff template placeholders [#kickoff-template-placeholders]

When a trigger fires, the kickoff template is rendered with values from the event:

| Placeholder       | Expands to                                                                            |
| ----------------- | ------------------------------------------------------------------------------------- |
| `{{repo}}`        | The source PR repo (`owner/name`).                                                    |
| `{{pr}}`          | The pull request number.                                                              |
| `{{branch}}`      | The PR's head branch.                                                                 |
| `{{path}}`        | The cloned path of the source repo in the VM.                                         |
| `{{instruction}}` | The instruction parsed from the triggering event.                                     |
| `{{repos}}`       | Every repo cloned for the run — the source PR repo plus the agent's configured repos. |

## Manage a trigger [#manage-a-trigger]

Update with `PATCH /v1/triggers/{id}` (set `events`, `enabled`, or
`kickoff_template` — the repo binding is fixed at create), and delete with
`DELETE /v1/triggers/{id}`.

To see what a trigger has done, list its **fires** — one record per
webhook-delivery-to-run:

```bash
curl https://agents.clusterbase.dev/v1/triggers/trg_d4e5f6/fires \
  -H "Authorization: Bearer $CLUSTER_TOKEN"
```

Each fire reports its `status`, the `session_id` it created, and the `repo` /
`pr_number` it ran against — open that session to read the [event
stream](/docs/agents/sessions-and-events).