docs(hub): clarify trigger authoring and event limits

This commit is contained in:
Mohamed Boudra
2026-11-20 17:31:13 +01:00
parent d6fa19f2d5
commit 36dbeb1943
12 changed files with 50 additions and 18 deletions
+8 -2
View File
@@ -39,9 +39,11 @@ One trigger document can list more than one event under `on`. The dashboard visu
| Field | Required | Notes |
| ---------- | -------- | ------------------------------------------------------------------------------ |
| `daemon` | yes | Connected daemon slug with `hub.execute` permission. |
| `cwd` | yes | Existing absolute path on that daemon. |
| `cwd` | yes | Existing directory on that daemon, with an absolute path that starts with `/`. |
| `worktree` | no | Optional git worktree mode: `branch-off`, `checkout-branch`, or `checkout-pr`. |
For example, `/home/me/project` uses the required path format. Hub rejects Windows drive paths such as `C:\work\project`.
Worktree modes:
- `branch-off`: requires `newBranch` and optional `base`. Embed `${{ paseo.execution.id }}` in `newBranch` (for example `trigger-${{ paseo.execution.id }}`) so each execution gets a unique branch that survives retries. `${{ paseo.execution.id }}` is the only expression accepted in `newBranch`.
@@ -129,7 +131,11 @@ Wrap untrusted external text in a clear delimiter such as `<user-prompt>...</use
Hub attaches its execution MCP server to every run and always exposes `finish_execution`.
Conversational triggers (`github.*`, `linear.*`, `slack.*`, `discord.*`) also grant an unlimited, optional event-native `reply` tool automatically. Add `run.outputs` when you want to cap `max` replies or require at least one reply before `finish_execution` succeeds:
Hub grants the `reply` tool when the event has an issue, pull request, or thread to reply to. Replies are optional and unlimited by default.
A `github.push` event has no reply destination. If you set `run.outputs.github.reply.required: true` for a push, Hub fails the run before it starts the agent.
Set `run.outputs` to cap replies with `max` or require a reply before `finish_execution`.
```yaml
run:
@@ -37,9 +37,11 @@ nav: 触发器 YAML 参考
| 字段 | 必填 | 说明 |
| ---------- | ---- | ---------------------------------------------------------------------------- |
| `daemon` | 是 | 拥有 `hub.execute` 权限的已连接 daemon slug。 |
| `cwd` | 是 | 该 daemon 上已存在的绝对路径。 |
| `cwd` | 是 | 该 daemon 上已有的目录,使用以 `/` 开头的绝对路径。 |
| `worktree` | 否 | 可选的 git worktree 模式:`branch-off`、`checkout-branch` 或 `checkout-pr`。 |
例如,`/home/me/project` 符合路径格式。Hub 会拒绝 `C:\work\project` 这类 Windows 盘符路径。
worktree 模式:
- `branch-off`:需要 `newBranch` 和可选的 `base`。在 `newBranch` 中嵌入 `${{ paseo.execution.id }}`(例如 `trigger-${{ paseo.execution.id }}`),让每次执行获得唯一分支并在重试时保持一致。`newBranch` 只接受 `${{ paseo.execution.id }}` 表达式。
@@ -127,7 +129,11 @@ run:
Hub 会为每次运行挂载执行 MCP 服务器,并始终提供 `finish_execution`。
对话类触发器(`github.*`、`linear.*`、`slack.*`、`discord.*`)还会自动授予不限次、非必需的事件原生 `reply` 工具。如需限制 `max` 回复次数,或要求在 `finish_execution` 成功前至少回复一次,请添加 `run.outputs`:
当事件有关联的 issue、Pull Request 或讨论串可供回复时,Hub 会授予 `reply` 工具。默认情况下,回复可选且不限次数。
`github.push` 事件没有回复目标。如果为推送事件设置 `run.outputs.github.reply.required: true`,Hub 会在启动 Agent 前将运行标记为失败。
通过 `run.outputs` 设置 `max` 可限制回复次数,也可以要求 Agent 在调用 `finish_execution` 前至少回复一次。
```yaml
run:
+4 -2
View File
@@ -26,13 +26,15 @@ Yes. Integrations belong to the organization under **Integrations**, and each co
## Who can trigger an agent?
For GitHub, Slack, Discord, and Linear comment or assignment triggers, Hub checks the sender against `from_users`. Setting `from_users: ["*"]` (the dashboard's **Audience: Everyone** default) allows any sender, while listing named logins or user IDs restricts access.
GitHub, Slack, and Discord triggers accept `from_users: ["*"]`, the value the dashboard saves for **Audience → Everyone**. To limit who can trigger a run, list the allowed logins or user IDs in `from_users`.
For Linear comments and assignments, **Everyone** matches no users. Choose **Specific people** and enter the allowed Linear user UUIDs in **User IDs**. See [trigger filters](/docs/hub/triggers#filters).
`linear.issue_entered_scope` requires `filters.project` and can omit `from_users`. Inbound webhooks authenticate callers with a Bearer secret (`whsec_...`), and schedules fire on Hub's own clock.
## Can an agent reply back to GitHub, Linear, Slack, or Discord?
Yes. Conversational triggers (`github.*`, `linear.*`, `slack.*`, `discord.*`) automatically grant the Hub MCP `reply` tool, which posts back to the triggering issue, pull request, or thread.
Hub grants the `reply` tool when the event has an issue, pull request, or thread to reply to. A `github.push` event has no reply destination.
Add `run.outputs` to set `max` or `required: true`, and tell the agent to call `reply` and `finish_execution` in `run.prompt`. When Hub runs over HTTPS, replies include an **Open in Paseo** link for signed-in organization members.
+4 -2
View File
@@ -24,13 +24,15 @@ Hub 可以运行你已连接的 Paseo daemon 上配置的任意 Provider,包
## 谁可以触发 Agent? {#who-can-trigger-an-agent}
对于 GitHub、Slack、Discord 以及 Linear 评论和分配触发器,Hub 会对照 `from_users` 检查发送者。设置为 `from_users: ["*"]`(控制台 **Audience: Everyone** 的默认值)时允许任意发送者,列出具名登录名或用户 ID 时则只允许这些账号。
GitHub、Slack 和 Discord 触发器支持 `from_users: ["*"]`,这是控制台为 **Audience → Everyone** 保存的值。如需限制谁能触发运行,请在 `from_users` 中列出允许的登录名或用户 ID。
对于 Linear 评论和分配事件,**Everyone** 无法匹配用户。请选择 **Specific people**,并在 **User IDs** 中输入允许的 Linear 用户 UUID。请参阅[触发器过滤条件](/docs/hub/triggers#filters)。
`linear.issue_entered_scope` 要求设置 `filters.project` 且可以省略 `from_users`。入站 webhook 通过 Bearer 密钥(`whsec_...`)验证调用方,定时任务则按 Hub 自己的时钟触发。
## Agent 可以回复到 GitHub、Linear、Slack 或 Discord 吗? {#can-an-agent-reply-back-to-github-linear-slack-or-discord}
可以。对话类触发器(`github.*`、`linear.*`、`slack.*`、`discord.*`)会自动授予 Hub MCP `reply` 工具,将回复发布回触发运行的 issue、Pull Request 或讨论串。
当事件有关联的 issue、Pull Request 或讨论串可供回复时,Hub 会授予 `reply` 工具。`github.push` 事件没有回复目标。
添加 `run.outputs` 可设置 `max` 或 `required: true`,并在 `run.prompt` 中指示 Agent 调用 `reply` 和 `finish_execution`。当 Hub 运行在 HTTPS 下时,回复会为已登录的组织成员附带 **Open in Paseo** 链接。
+3 -1
View File
@@ -56,7 +56,9 @@ paseo hub permissions grant hub.execute
## 4. Create the starter trigger
From the same repository directory, generate and deploy a starter trigger:
Use a repository directory whose absolute path starts with `/`. Hub rejects Windows drive paths such as `C:\work\project` when `paseo hub init` validates the trigger. See [target and worktree](/docs/hub/configuration/reference#target-and-worktree).
From that repository directory, generate and deploy a starter trigger.
```sh
paseo hub init
+3 -1
View File
@@ -54,7 +54,9 @@ paseo hub permissions grant hub.execute
## 4. 创建入门触发器 {#4-create-the-starter-trigger}
在同一仓库目录中生成并部署入门触发器:
请使用绝对路径以 `/` 开头的仓库目录。`paseo hub init` 校验触发器时,Hub 会拒绝 `C:\work\project` 这类 Windows 盘符路径。请参阅[目标与 worktree](/docs/hub/configuration/reference#target-and-worktree)。
在该仓库目录中生成并部署入门触发器。
```sh
paseo hub init
+3 -1
View File
@@ -52,7 +52,9 @@ Discord filters use numeric snowflake IDs, not server names, display names, or c
`from_users` is required and matches the sender, while `guild` and `channels` restrict where the mention arrived. `pattern` requires a prefix after the mention (`contains` is its legacy alias with the same prefix behavior). All filters compose with AND.
`${{ paseo.prompt }}` contains the complete received message text. If you declare `inputs`, Hub parses leading `key=value` tokens after the mention into `${{ paseo.inputs }}`. Include `${{ paseo.context }}` in `run.prompt` to pass the referenced message, thread history, and attachment descriptors as JSON.
`${{ paseo.prompt }}` contains the full message. Hub parses leading `key=value` tokens after the mention for inputs you declare. If you declare `inputs.repo`, use `${{ paseo.inputs.repo }}` in `run.prompt` to insert its value.
Include `${{ paseo.context }}` in `run.prompt` to pass the referenced message, thread history, and attachment descriptors as JSON.
## Replies and continuation
+3 -1
View File
@@ -50,7 +50,9 @@ Discord 过滤条件使用数字 snowflake ID,而不是服务器名称、显
`from_users` 为必填项,匹配发送者,`guild` 和 `channels` 限制提及出现的位置。`pattern` 要求提及之后紧跟指定前缀(`contains` 是其旧别名,前缀行为相同)。所有过滤条件按逻辑与组合。
`${{ paseo.prompt }}` 包含收到的完整消息文本。如果你声明了 `inputs`,Hub 会将提及之后紧跟的 `key=value` 头部解析到 `${{ paseo.inputs }}`。在 `run.prompt` 中包含 `${{ paseo.context }}`,即可以 JSON 形式传入被引用的消息、讨论串历史和附件描述符。
`${{ paseo.prompt }}` 包含完整消息。Hub 会在提及后解析开头的 `key=value`,提取已声明的输入值。如果声明了 `inputs.repo`,请在 `run.prompt` 中使用 `${{ paseo.inputs.repo }}` 插入该值。
在 `run.prompt` 中使用 `${{ paseo.context }}`,以 JSON 形式传入被引用的消息、讨论串历史和附件描述符。
## 回复与会话延续 {#replies-and-continuation}
+6 -2
View File
@@ -129,7 +129,9 @@ External provider triggers require a non-empty `from_users` allowlist. There are
- `schedule.tick` uses `recurrence` and accepts no `connection` or `filters`.
- `webhook.received` authenticates callers with a Bearer secret and accepts no `connection` or `filters`.
The dashboard trigger form defaults **Audience** to **Everyone**, which saves `from_users: ["*"]` and lets any user on a public repository or workspace start a run. To restrict access, choose **Specific people** in the form or list explicit logins or user IDs in `from_users`.
The dashboard defaults **Audience** to **Everyone** and saves `from_users: ["*"]`. GitHub, Slack, and Discord accept this wildcard. To limit who can trigger a run, choose **Specific people** or list the allowed logins or user IDs in `from_users`.
For Linear comments and assignments, **Everyone** matches no users. Choose **Specific people** and enter the allowed Linear user UUIDs in **User IDs**, or list them in `from_users` in YAML.
Allowlists do not sandbox the agent or sanitize untrusted text, so read [Hub security](/docs/hub/security) before granting write access or widening the audience.
@@ -170,7 +172,9 @@ Both run. Triggers are independent, unordered, and do not shadow each other.
## Replying and Open in Paseo links
Conversational triggers (`github.*`, `linear.*`, `slack.*`, `discord.*`) automatically grant an event-native `reply` tool on the Hub MCP server so the agent can post progress updates and final answers back to the originating issue, pull request, or thread.
Hub grants the `reply` tool when the event has an issue, pull request, or thread to reply to.
A `github.push` event has no reply destination. If you require `github.reply` for a push, Hub fails the run before it starts the agent.
To cap how many replies an agent can send or require at least one reply before `finish_execution` succeeds, declare `run.outputs`:
+6 -2
View File
@@ -127,7 +127,9 @@ Hub 会在每段提示词中附带 `executionId`。在持续运行的 Agent 上
- `schedule.tick` 使用 `recurrence`,不接受 `connection` 或 `filters`。
- `webhook.received` 通过 Bearer 密钥验证调用方,不接受 `connection` 或 `filters`。
控制台触发器表单默认将 **Audience** 设为 **Everyone**,保存为 `from_users: ["*"]`,允许公开仓库或工作区中的任意用户启动运行。如需限制访问,请在表单中选择 **Specific people**,或在 YAML 的 `from_users` 中显式列出登录名或用户 ID。
控制台默认将 **Audience** 设为 **Everyone**,并保存为 `from_users: ["*"]`。GitHub、Slack 和 Discord 支持此通配符。如需限制谁能触发运行,请选择 **Specific people**,或在 `from_users` 中列出允许的登录名或用户 ID。
对于 Linear 评论和分配事件,**Everyone** 无法匹配用户。请选择 **Specific people**,在 **User IDs** 中输入允许的 Linear 用户 UUID,或在 YAML 的 `from_users` 中列出这些 UUID。
白名单不能为 Agent 提供沙箱隔离,也不会清洗不可信文本,授予写权限或放宽受众范围前请先阅读 [Hub 安全](/docs/hub/security)。
@@ -168,7 +170,9 @@ on:
## 回复与 Open in Paseo 链接 {#replying-and-open-in-paseo-links}
对话类触发器(`github.*`、`linear.*`、`slack.*`、`discord.*`)会自动通过 Hub MCP 服务器授予事件原生的 `reply` 工具,让 Agent 可以向来源 issue、Pull Request 或讨论串发送进度更新和最终答复。
当事件有关联的 issue、Pull Request 或讨论串可供回复时,Hub 会授予 `reply` 工具。
`github.push` 事件没有回复目标。如果为推送事件要求 `github.reply`,Hub 会在启动 Agent 前将运行标记为失败。
如需限制最大回复次数,或要求在 `finish_execution` 成功前至少回复一次,请声明 `run.outputs`:
+1 -1
View File
@@ -54,7 +54,7 @@ Slack filters use IDs, not display names or connection slugs. All filters compos
- `workspace` matches the Slack team ID and `channels` limits which channels can trigger the run.
- `pattern` requires a prefix after the mention (`contains` is its legacy alias with the same prefix behavior).
`${{ paseo.prompt }}` contains the complete received message text. If you declare `inputs` on the trigger, Hub parses leading `key=value` tokens after the mention into `${{ paseo.inputs }}`:
`${{ paseo.prompt }}` contains the full message. Hub parses leading `key=value` tokens after the mention for inputs you declare. If you declare `inputs.repo`, use `${{ paseo.inputs.repo }}` in `run.prompt` to insert its value.
```text
@Paseo repo=project investigate the failed sync
+1 -1
View File
@@ -52,7 +52,7 @@ Slack 过滤条件使用 ID,而不是显示名称或连接 slug。所有过滤
- `workspace` 匹配 Slack Team ID,`channels` 限制可触发运行的频道。
- `pattern` 要求提及之后紧跟指定前缀(`contains` 是其旧别名,前缀行为相同)。
`${{ paseo.prompt }}` 包含收到的完整消息文本。如果你在触发器上声明了 `inputs`,Hub 会将提及之后紧跟的 `key=value` 头部解析到 `${{ paseo.inputs }}`:
`${{ paseo.prompt }}` 包含完整消息。Hub 会在提及后解析开头的 `key=value`,提取已声明的输入值。如果声明了 `inputs.repo`,请在 `run.prompt` 中使用 `${{ paseo.inputs.repo }}` 插入该值。
```text
@Paseo repo=project investigate the failed sync