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

# Configuring Triggers

> Add triggers to a Cosmos Expert — pick an event source, choose an event type, and filter payloads with JSONLogic expressions.

A **trigger** is how an outside event reaches an Expert. When it fires, Cosmos opens a session and drops the raw event payload in as the first message. Add and edit triggers from the **Automations** page in the sidebar.

<Note>Prefer not to wire triggers by hand? Describe the workflow to [Cosmos Advisor](/cosmos/automation-advisor) instead and it wires the right trigger for you.</Note>

## Trigger Types

Triggers come in three groups:

* **First-party integrations** — GitHub, Linear, Slack, GitLab, PagerDuty. Connect the integration once from the Integrations settings page; Cosmos owns the upstream registration. PagerDuty triggers pick from the PagerDuty integrations (Events API routing keys) you've registered instead.
* **Scheduled** — a 5-field cron expression and a timezone. No payload, no filter. See [Schedules](/cosmos/config-schedules).
* **Webhook** — any service that can POST JSON to an HTTPS URL you mint yourself. See [Webhooks](/cosmos/config-webhooks).

## Adding a Trigger to an Expert

1. Open **Automations** in the sidebar and click **Create automation**. The trigger editor opens.
2. Pick the Expert you want to wire up from the **Expert** dropdown. (The Expert must already exist — create it from the Experts page first.)
3. Choose a **Trigger source**, then complete the editor fields:
   * **Trigger name** — a human-readable label (e.g. `on-pr-opened`).
   * **Event** — for first-party triggers, the provider event name (see the reference below). Scheduled triggers show a **Frequency** builder instead — every N minutes, hourly, daily, weekly, monthly, or a custom cron expression — plus a **Timezone**.
   * **Filter** — an optional [JSONLogic](https://jsonlogic.com) expression evaluated against the raw event payload. The trigger fires only when this expression returns true.
   * **Auto-archive sessions created by this trigger** — toggle off when you want to keep trigger-launched sessions accessible after they go idle (useful for revisitable agent-driven sessions like a PR-author).
   * **Run sessions as** — under **Permissions**, keep the trigger creator or choose a service account as the identity for triggered sessions. Availability is rollout-dependent: without delegated access, only workspace admins can choose a service account. With delegated access, non-admins see only service accounts shared with them, and saving a selection requires permission to attach that account.
   * **Maximum runs per minute** — an optional rate limit on how often the trigger can fire.
4. Click **Save**. To add another trigger, expand the automation on the **Automations** page and click **Add trigger**.

To change **Run sessions as** later, expand the automation, select the trigger, and edit the field under **Permissions**.

<Note>The trigger **type** is fixed once a trigger is created. To change it, delete the trigger and add a new one.</Note>

## Event Type Reference

Each first-party trigger takes an **Event type** using the source's native event names:

| Source | Event types | Notes |
| - | - | - |
| [GitHub](/cosmos/config-github) | `pull_request`, `pull_request_review`, `pull_request_review_comment`, `issues`, `issue_comment`, `push`, `check_suite`, `status`, `workflow_run`, `workflow_job`, `workflow_dispatch` | GitHub webhook event names. No `reaction` event — GitHub doesn't send webhooks for emoji reactions. |
| [Linear](/cosmos/config-linear) | `Issue`, `Comment`, `Project` | Each delivers `action` ∈ `create` / `update` / `remove` in the payload — filter on it. |
| [Slack](/cosmos/config-slack) | `app_mention`, `message` | An @-mention is delivered as **both** — always filter on `event.type` to avoid double-firing. |
| [GitLab](/cosmos/gitlab-cloud) | `gitlab.push`, `gitlab.tag_push`, `gitlab.merge_request`, `gitlab.issue`, `gitlab.note`, `gitlab.pipeline` | A connected project registers these six by default; more are available on request. |
| PagerDuty | — | Routed by integration key, not event type. Filter on `event.event_type` (e.g. `incident.triggered`). |

The per-source pages have the payload shapes and filter recipes for each: [GitHub](/cosmos/config-github), [Linear](/cosmos/config-linear), [Slack](/cosmos/config-slack).

## Payload Filters

The **Filter** field on a trigger is a [JSONLogic](https://jsonlogic.com) expression evaluated against the parsed JSON payload. Common examples:

```json theme={null}
// Only PR opens
{"==": [{"var": "action"}, "opened"]}

// PRs targeting main
{"==": [{"var": "pull_request.base.ref"}, "main"]}

// Comments mentioning @auggie
{"in": ["@auggie", {"var": "comment.body"}]}

// Severity P0 or P1
{"in": [{"var": "severity"}, ["P0", "P1"]]}
```

To see the real shape of a payload before writing a filter, open the [events log](/cosmos/manage-automations), filter by source and event type, and inspect a captured event. The events log is the source of truth for what your triggers actually see — use it to confirm field paths and values before pasting a filter into a trigger.

### PagerDuty — P1 Incident Triggered

PagerDuty triggers route by integration key rather than event type. Create a PagerDuty Events API v2 integration on the relevant service, register its **routing key** as a PagerDuty integration in Cosmos, then pick it from the **PagerDuty integration** dropdown on the trigger. Use the **Event** dropdown (incident triggered / acknowledged / resolved) and the **Filter** field to match specific incidents:

```json theme={null}
{"and": [
  {"==": [{"var": "event.event_type"}, "incident.triggered"]},
  {"in": [{"var": "event.data.priority.name"}, ["P1"]]}
]}
```

## See Also

* [Understanding Automation](/cosmos/automations) — how triggers, events, and Experts fit together.
* [Webhooks](/cosmos/config-webhooks) — custom webhook URLs for everything else.
* [Schedules](/cosmos/config-schedules) — cron syntax, timezones, and concurrency rules.
* [Managing Automations](/cosmos/manage-automations) — the events log and run history.


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