diff --git a/public-docs/hub/configuration/hub-yml.md b/public-docs/hub/configuration/hub-yml.md index 91b71782d9..26578854a8 100644 --- a/public-docs/hub/configuration/hub-yml.md +++ b/public-docs/hub/configuration/hub-yml.md @@ -141,14 +141,15 @@ steps: Use one of these semantic event names for new GitHub workflows: -| `on` | Matches | -| ------------------------------------- | ------------------------------------------------------------------------- | -| `github.issue_created` | An `issues` delivery whose action is `opened`. | -| `github.pull_request_created` | A `pull_request` delivery whose action is `opened`. | -| `github.issue_comment_created` | An `issue_comment` delivery whose action is `created`, on an issue. | -| `github.pull_request_comment_created` | An `issue_comment` delivery whose action is `created`, on a pull request. | -| `github.issue_label_added` | An `issues` delivery whose action is `labeled`. | -| `github.pull_request_label_added` | A `pull_request` delivery whose action is `labeled`. | +| `on` | Matches | +| -------------------------------------- | ------------------------------------------------------------------------- | +| `github.issue_created` | An `issues` delivery whose action is `opened`. | +| `github.pull_request_created` | A `pull_request` delivery whose action is `opened`. | +| `github.pull_request_ready_for_review` | A draft pull request is marked ready for review. | +| `github.issue_comment_created` | An `issue_comment` delivery whose action is `created`, on an issue. | +| `github.pull_request_comment_created` | An `issue_comment` delivery whose action is `created`, on a pull request. | +| `github.issue_label_added` | An `issues` delivery whose action is `labeled`. | +| `github.pull_request_label_added` | A `pull_request` delivery whose action is `labeled`. | Existing configurations may continue to use `github.issues`, `github.issue_comment`, `github.pull_request_review`, `github.pull_request_review_comment`, and `github.push`. These legacy events retain their existing behavior. diff --git a/public-docs/hub/configuration/hub-yml.zh-CN.md b/public-docs/hub/configuration/hub-yml.zh-CN.md index 13f1ea5478..db8ddd38af 100644 --- a/public-docs/hub/configuration/hub-yml.zh-CN.md +++ b/public-docs/hub/configuration/hub-yml.zh-CN.md @@ -139,14 +139,15 @@ steps: 新的 GitHub workflow 请使用以下语义化事件名之一： -| `on` | 匹配 | -| ------------------------------------- | ----------------------------------------------------------------- | -| `github.issue_created` | action 为 `opened` 的 `issues` 投递。 | -| `github.pull_request_created` | action 为 `opened` 的 `pull_request` 投递。 | -| `github.issue_comment_created` | 在 issue 上、action 为 `created` 的 `issue_comment` 投递。 | -| `github.pull_request_comment_created` | 在 Pull Request 上、action 为 `created` 的 `issue_comment` 投递。 | -| `github.issue_label_added` | action 为 `labeled` 的 `issues` 投递。 | -| `github.pull_request_label_added` | action 为 `labeled` 的 `pull_request` 投递。 | +| `on` | 匹配 | +| -------------------------------------- | ----------------------------------------------------------------- | +| `github.issue_created` | action 为 `opened` 的 `issues` 投递。 | +| `github.pull_request_created` | action 为 `opened` 的 `pull_request` 投递。 | +| `github.pull_request_ready_for_review` | 草稿 PR 被标记为可审查。 | +| `github.issue_comment_created` | 在 issue 上、action 为 `created` 的 `issue_comment` 投递。 | +| `github.pull_request_comment_created` | 在 Pull Request 上、action 为 `created` 的 `issue_comment` 投递。 | +| `github.issue_label_added` | action 为 `labeled` 的 `issues` 投递。 | +| `github.pull_request_label_added` | action 为 `labeled` 的 `pull_request` 投递。 | 已有的配置可以继续使用 `github.issues`、`github.issue_comment`、`github.pull_request_review`、`github.pull_request_review_comment` 和 `github.push`。这些旧版事件保持原有的行为。 diff --git a/public-docs/hub/self-hosting/github-app.md b/public-docs/hub/self-hosting/github-app.md index 740ce9da5c..ad47a03f42 100644 --- a/public-docs/hub/self-hosting/github-app.md +++ b/public-docs/hub/self-hosting/github-app.md @@ -31,7 +31,7 @@ Keep GitHub's SSL verification enabled. ## Subscribe to GitHub events -Under **Subscribe to events**, select **Issue comment**, **Issues**, **Pull requests**, **Pull request review**, **Pull request review comment**, and **Push**. **Pull requests** is required for `github.pull_request_created` and `github.pull_request_label_added`. +Under **Subscribe to events**, select **Issue comment**, **Issues**, **Pull requests**, **Pull request review**, **Pull request review comment**, and **Push**. **Pull requests** is required for `github.pull_request_created`, `github.pull_request_ready_for_review`, and `github.pull_request_label_added`. ## Connect repositories diff --git a/public-docs/hub/self-hosting/github-app.zh-CN.md b/public-docs/hub/self-hosting/github-app.zh-CN.md index 75c0ac67a4..ef892fe815 100644 --- a/public-docs/hub/self-hosting/github-app.zh-CN.md +++ b/public-docs/hub/self-hosting/github-app.zh-CN.md @@ -29,7 +29,7 @@ GitHub 会使用以下 Hub URL： ## 订阅 GitHub 事件 {#subscribe-to-github-events} -在 **Subscribe to events** 下，选择 **Issue comment**、**Issues**、**Pull requests**、**Pull request review**、**Pull request review comment** 和 **Push**。`github.pull_request_created` 和 `github.pull_request_label_added` 需要 **Pull requests**。 +在 **Subscribe to events** 下，选择 **Issue comment**、**Issues**、**Pull requests**、**Pull request review**、**Pull request review comment** 和 **Push**。`github.pull_request_created`、`github.pull_request_ready_for_review` 和 `github.pull_request_label_added` 需要 **Pull requests**。 ## 连接仓库 {#connect-repositories} diff --git a/public-docs/hub/triggers/github.md b/public-docs/hub/triggers/github.md index 92be54bfe1..3585a2be3a 100644 --- a/public-docs/hub/triggers/github.md +++ b/public-docs/hub/triggers/github.md @@ -74,6 +74,10 @@ steps: `github.pull_request_created` fires only when someone opens a pull request. +To wait until a draft is finished, change `on` in the example above to `github.pull_request_ready_for_review`. It fires only when a draft is marked ready, with the user making that transition checked against `from_users`. Opening a pull request, later pushes, and converting it back to draft do not fire this event. + +Pull request webhook context includes `github.pull_request.draft` and `github.pull_request.head_sha` as delivered by GitHub. `github.pull_request` is `null` for other events, including conversation comments on a pull request. Fetch the live pull request with `gh pr view` before reviewing and again before posting. Finish without posting if it is now draft or its head differs from the reviewed SHA. Converting back to draft does not cancel a Hub run already in progress; the workflow owns these live checks. + ## Respond to new comments `.paseo/workflows/respond-to-issue-comment.yml`: @@ -177,14 +181,15 @@ steps: ## Choose the event -| `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. | +| `on` | Fires when | +| -------------------------------------- | ---------------------------------------------------- | +| `github.issue_created` | An issue is opened. | +| `github.pull_request_created` | A pull request is opened. | +| `github.pull_request_ready_for_review` | A draft pull request is marked ready for review. | +| `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. | Choose `github.issue_comment_created` for a comment on an issue and `github.pull_request_comment_created` for a conversation comment on a pull request. GitHub delivers both as issue comments; Hub separates them for you. A comment on a changed line is a diff comment, covered by the legacy `github.pull_request_review_comment` event. diff --git a/public-docs/hub/triggers/github.zh-CN.md b/public-docs/hub/triggers/github.zh-CN.md index 3f599873f6..71c033129f 100644 --- a/public-docs/hub/triggers/github.zh-CN.md +++ b/public-docs/hub/triggers/github.zh-CN.md @@ -72,6 +72,10 @@ steps: `github.pull_request_created` 只在有人创建 PR 时触发。 +若要等草稿完成后再开始审查，将上例的 `on` 改为 `github.pull_request_ready_for_review`。只有将草稿 PR 标记为可审查时才会触发；创建 PR、后续 push 和转回草稿都不会触发。`from_users` 匹配执行此操作的用户。 + +PR webhook 的上下文通过 `github.pull_request.draft` 和 `github.pull_request.head_sha` 提供投递时的草稿状态和 head commit。其他事件（包括 PR 会话评论）的此字段为 `null`。审查前及发布结果前，通过 `gh pr view` 重新获取 PR；如果它已成为草稿或 head 与已审查的 SHA 不同，就结束运行而不发布结果。转回草稿不会取消已启动的 Hub 运行，workflow 应自行检查状态。 + ## 回复新评论 {#respond-to-new-comments} `.paseo/workflows/respond-to-issue-comment.yml`： @@ -175,14 +179,15 @@ steps: ## 选择事件 {#choose-the-event} -| `on` | 触发时机 | -| ------------------------------------- | ---------------------- | -| `github.issue_created` | 创建 issue。 | -| `github.pull_request_created` | 创建 PR。 | -| `github.issue_comment_created` | 在 issue 上创建评论。 | -| `github.pull_request_comment_created` | 在 PR 上创建对话评论。 | -| `github.issue_label_added` | 为 issue 添加标签。 | -| `github.pull_request_label_added` | 为 PR 添加标签。 | +| `on` | 触发时机 | +| -------------------------------------- | ------------------------ | +| `github.issue_created` | 创建 issue。 | +| `github.pull_request_created` | 创建 PR。 | +| `github.pull_request_ready_for_review` | 草稿 PR 被标记为可审查。 | +| `github.issue_comment_created` | 在 issue 上创建评论。 | +| `github.pull_request_comment_created` | 在 PR 上创建对话评论。 | +| `github.issue_label_added` | 为 issue 添加标签。 | +| `github.pull_request_label_added` | 为 PR 添加标签。 | issue 上的评论选择 `github.issue_comment_created`，PR 上的对话评论选择 `github.pull_request_comment_created`。GitHub 把两者都作为 issue 评论投递；Hub 会替你区分它们。针对某一行改动的评论属于 diff 评论，由旧的 `github.pull_request_review_comment` 事件处理。 diff --git a/public-docs/hub/triggers/index.md b/public-docs/hub/triggers/index.md index 164d1739eb..002ad5c20e 100644 --- a/public-docs/hub/triggers/index.md +++ b/public-docs/hub/triggers/index.md @@ -87,17 +87,18 @@ Hub includes an `executionId` in each prompt. When using a continuing agent, pas ## 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. | +| `on` | Fires when | +| -------------------------------------- | ---------------------------------------------------- | +| `github.issue_created` | An issue is opened. | +| `github.pull_request_created` | A pull request is opened. | +| `github.pull_request_ready_for_review` | A draft pull request is marked ready for review. | +| `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. diff --git a/public-docs/hub/triggers/index.zh-CN.md b/public-docs/hub/triggers/index.zh-CN.md index 9835633efd..549614ca1a 100644 --- a/public-docs/hub/triggers/index.zh-CN.md +++ b/public-docs/hub/triggers/index.zh-CN.md @@ -85,17 +85,18 @@ Hub 在每段提示词中都包含一个 `executionId`。使用持续的 Agent ## 事件 {#events} -| `on` | 触发时机 | -| ------------------------------------- | ------------------------------- | -| `github.issue_created` | 有 issue 被创建。 | -| `github.pull_request_created` | 有 Pull Request 被创建。 | -| `github.issue_comment_created` | issue 上新增了评论。 | -| `github.pull_request_comment_created` | Pull Request 上新增了对话评论。 | -| `github.issue_label_added` | issue 被添加了标签。 | -| `github.pull_request_label_added` | Pull Request 被添加了标签。 | -| `slack.mention` | 机器人在频道中被提及。 | -| `discord.mention` | 机器人在服务器中被提及。 | -| `manual.run` | 通过 API 发起了一次运行。 | +| `on` | 触发时机 | +| -------------------------------------- | ------------------------------- | +| `github.issue_created` | 有 issue 被创建。 | +| `github.pull_request_created` | 有 Pull Request 被创建。 | +| `github.pull_request_ready_for_review` | 草稿 PR 被标记为可审查。 | +| `github.issue_comment_created` | issue 上新增了评论。 | +| `github.pull_request_comment_created` | Pull Request 上新增了对话评论。 | +| `github.issue_label_added` | issue 被添加了标签。 | +| `github.pull_request_label_added` | Pull Request 被添加了标签。 | +| `slack.mention` | 机器人在频道中被提及。 | +| `discord.mention` | 机器人在服务器中被提及。 | +| `manual.run` | 通过 API 发起了一次运行。 | 新的 GitHub workflow 应使用语义化事件。五个旧版事件仍然兼容：`github.issues`、`github.issue_comment`、`github.pull_request_review`、`github.pull_request_review_comment` 和 `github.push`。完整的 workflow 以及何时使用哪个事件，见 [GitHub 触发器](/docs/hub/triggers/github)。