# Triggers

A trigger says which provider event can start a workflow. The [Hub workflows](/docs/hub/workflows) page covers the steps, inputs, routing, prompts, and deadlines that run after a match.

`.paseo/workflows/github-issue.yml`:

```yaml
name: triage-issue
on: github.issue_created
filters:
  repo: acme/api
  from_users: [alice]
max_runtime: 2h
steps:
  - id: work
    environment: dev
    max_runtime: 90m
    idle_timeout: 10m
    agent: codex
    prompt:
      - text: Call hub.finish_execution when the step is complete.
      - text: ${{ paseo.prompt }}
```

Field-by-field detail is in the [configuration reference](/docs/hub/configuration/hub-yml).

## Choose the agent in Hub

When you create or edit a trigger in the Hub dashboard, choose the daemon and enter its working directory first. Hub then asks that daemon for its available providers, models, execution modes, and thinking options. The suggested model and mode are the daemon's defaults.

Changing the daemon or working directory reloads the choices. If an existing trigger names a model, mode, or thinking option that the daemon no longer reports, Hub marks that value unavailable without replacing it. You can keep the authored value, choose a current value, or switch to YAML editing.

If the daemon is offline or needs a newer Isee version, the agent selectors show an error and a retry action. The rest of the trigger and its YAML remain editable.

## Continue the same agent

Dashboard triggers default to **Same conversation**. Messages in the same Slack or Discord thread, events on the same GitHub issue or pull request, and events on the same Linear issue continue the existing agent in that project. An event without a conversation starts a new agent.

If the agent is busy, the new prompt steers its current work. Each arrival keeps its own output limits and completion status. If a reusable workspace is archived, Hub asks Isee to restore it before sending the prompt.

Choose **Custom key** to group arrivals by an input, or **New agent** to keep them separate. A self-contained trigger document can express the same choice:

```yaml
name: support
on:
  slack.mention:
    filters:
      from_users: [U01234567]
run:
  target:
    daemon: laptop
    cwd: /Users/you/code/support
  agent:
    provider: codex
  continuation:
    mode: conversation
  max_runtime: 30m
  idle_timeout: 5m
  prompt: Handle this request and call finish_execution when complete.
```

The [continuation reference](/docs/hub/configuration/hub-yml#agent-continuation) covers keys and agent reuse. The run detail shows whether each arrival created, continued, or restored an agent.

Hub includes an `executionId` in each prompt. When using a continuing agent, pass that ID to `reply` and `finish_execution`. These tools act on that arrival's destination and contract; an old or unrelated execution ID is rejected.

## Events

| `on`                                  | Fires when                                           |
| ------------------------------------- | ---------------------------------------------------- |
| `github.issue_created`                | An issue is opened.                                  |
| `github.pull_request_created`         | A pull request is opened.                            |
| `github.issue_comment_created`        | A comment is created on an issue.                    |
| `github.pull_request_comment_created` | A conversation comment is created on a pull request. |
| `github.issue_label_added`            | A label is added to an issue.                        |
| `github.pull_request_label_added`     | A label is added to a pull request.                  |
| `slack.mention`                       | The bot is mentioned in a channel.                   |
| `discord.mention`                     | The bot is mentioned in a guild.                     |
| `manual.run`                          | A run started from the API.                          |

New GitHub workflows should use a semantic event. The five legacy events remain compatible: `github.issues`, `github.issue_comment`, `github.pull_request_review`, `github.pull_request_review_comment`, and `github.push`. See [GitHub triggers](/docs/hub/triggers/github) for complete workflows and when to use each event.

Each provider page documents its events and the data they expose:

- [GitHub triggers](/docs/hub/triggers/github)
- [Slack triggers](/docs/hub/triggers/slack)
- [Discord triggers](/docs/hub/triggers/discord)

## Filters

`filters` is required, and `from_users` must be present and non-empty. A trigger without it is rejected at validation.

The allowlist is what keeps a stranger's comment on a public issue from starting an agent on your machine. There is no default, because a safe default differs per repository.

An allowlist is one layer of defense. It does not make a permitted account trustworthy after compromise or make prompt injection harmless. See [Hub security](/docs/hub/security) before choosing the daemon, working directory, provider policy, and outputs for an external trigger.

| Filter       | Applies to                | Matches                                                              |
| ------------ | ------------------------- | -------------------------------------------------------------------- |
| `from_users` | all                       | GitHub: login. Slack and Discord: **user id**, not display name      |
| `repo`       | GitHub                    | `owner/name`                                                         |
| `workspace`  | Slack                     | Team id, `T01234567`                                                 |
| `guild`      | Discord                   | Guild id                                                             |
| `channels`   | Slack, Discord            | Channel ids                                                          |
| `contains`   | all                       | GitHub substring; Slack and Discord invocation prefix                |
| `pattern`    | all                       | Invocation prefix                                                    |
| `connection` | all                       | A connection slug, when the organization has several                 |
| `label`      | GitHub label-added events | The label added by this delivery, case-insensitively                 |
| `labels`     | GitHub                    | Every listed current issue or pull-request label, case-insensitively |

All conditions must pass. There is no `any` mode.

## Which connection an event comes from

`repo`, `workspace`, and `guild` are resolved to immutable ids when the configuration activates, along with the connection that owns them. Naming a resource the organization has no connection for fails activation, so you find out on push rather than when someone comments.

Omit the resource filter and the trigger listens to every connection of that provider in the organization. To pin it to one:

```yaml
filters:
  connection: acme-github
  from_users: [alice]
```

See [How Hub works](/docs/hub/concepts) for what activation compiles.

## When two triggers match

Both run. Triggers are not ordered and do not shadow each other, in one configuration or across projects.

## Replying

Put `allow_outputs` on the step that should reply. The reply capabilities are `slack.reply` and `discord.reply`.

- Set `max` when a step needs more than one update.
- Set `required: true` when the step must emit at least one reply before it can finish. A required type must be registered and available for the execution context.

GitHub has no reply capability; a step with a [`github` block](/docs/hub/github) comments through `gh` instead. The [output capability reference](/docs/hub/configuration/hub-yml#output-capabilities) has the contract.

The declaration grants the `hub.reply` tool; the prompt has to tell the agent to call it. See [Tell the agent which tool to call](/docs/hub/workflows#tell-the-agent-which-tool-to-call).