合并规则

定义在变更请求合并之前必须满足的要求

此功能可在以下方案中使用 专业版与企业版计划.

合并规则允许您定义在变更请求合并之前必须满足的要求，例如需要特定用户的审阅，或要求变更请求有主题或描述。

这些规则有助于维护内容质量并确保整个文档工作流中有适当的审核流程。

当您配置了合并规则时，它们会在变更请求合并之前自动评估。如果某条规则不满足，则在满足要求之前合并将被阻止。

这提供了一种自动化方式来强制执行团队的协作和审核标准。

使用合并规则

您可以在不同层级配置合并规则以匹配团队的工作流：

组织级配置

组织可以设置所有空间继承的默认合并规则。这在多个空间之间提供一致性，同时仍允许各空间根据需要自定义其规则。

要为您的组织配置合并规则，请打开侧边栏顶部的组织菜单并选择 设置 。在“设置”屏幕中，选择 合并规则 在 组织 侧边栏部分。在这里您可以为整个组织指定合并规则。

在不受限制的合并之间进行选择，或从预设列表中选择应用于整个组织的变更请求。

空间级配置

无论您是否启用了组织范围的合并规则，每个空间都可以根据其内容和团队结构有自己的合并要求。

这使您能够对重要文档使用更严格的规则，对草稿内容使用更宽松的规则，具有灵活性。

为空间设置合并规则时，您可以选择：

• 继承 来自组织的合并规则

• 定义自定义规则 特定于该空间

• 完全禁用 合并规则

如果您继承组织规则，则对组织合并规则的任何更改将自动应用于该空间。

要为您的组织配置合并规则，请打开编辑器左上角的 操作菜单 ，然后选择 合并规则。在这里您可以指定是继承组织的合并规则还是为该空间配置新的规则。

规则评估

规则如何工作

当有人想要合并变更请求时，GitBook 会按顺序评估所有配置的规则：

• 配置中的所有规则必须通过，合并才被允许

• 规则按其在配置中出现的顺序进行评估

• 如果任何规则失败，合并将被以适当的错误信息阻止

• 具有绕过能力的规则可以覆盖之前的失败

绕过规则

某些规则具有绕过能力（例如 允许指定参与者绕过要求）。这些特殊规则可以覆盖其他规则的失败。如果绕过规则的评估结果为真，则即使其他规则失败也会允许合并。

最佳实践

设置合并规则时，请考虑以下建议：

• 从简单开始：从基本规则开始，例如要求至少有一次审阅。

• 逐步扩展：随着团队增长和工作流成熟，添加更具体的要求。

• 谨慎使用绕过：仅向受信任的管理员授予绕过权限。

• 定期审查：根据团队的实际工作流模式调整规则。

• 先行测试：在可能的情况下，先在测试空间中测试规则更改，然后再应用到生产空间。

可用的规则类型

审阅要求

规则	说明
要求至少一次审阅	确保在变更请求可以合并之前至少有一名团队成员审阅了变更请求。
要求所有审阅被批准	所有 已完成 （非被请求）审阅必须为批准。如果任何审阅者请求更改或拒绝该变更请求，合并将被阻止。
要求由指定参与者审阅	要求所有指定用户的批准。您可以选择必须审阅并批准变更请求的特定团队成员，才能合并。
要求由指定参与者中的某一人审阅	要求至少由指定用户中的一人批准。当您有多个合格审阅者但只需要组内一人批准时，这很有用。
要求 Docs Agent 审阅（即将推出）	要求来自 GitBook AI 代理的审阅。这确保在合并之前对内容更改执行自动化质量检查。

变更请求要求

规则	说明
要求变更请求是最新的	变更请求必须与主内容分支保持同步。如果主内容在创建变更请求后已被更新，则在合并前需要对其进行变基或更新。
要求主题	变更请求必须有描述性的主题/标题。空主题将阻止合并。
要求描述	变更请求必须包含说明，解释所做的更改及原因。

高级选项

规则	说明
允许指定参与者绕过要求	您可以指定允许绕过所有其他合并规则要求的特定用户。这对于管理员或需要覆盖规则的紧急情况很有用。
自定义表达式	您可以使用自定义 JavaScript 表达式创建高级合并规则。这允许您基于评估上下文定义复杂逻辑，并可访问变更请求、审阅以及尝试合并的用户的属性。

自定义表达式

当您创建自定义表达式时，每次有人尝试合并变更请求时都会对其进行评估。如果表达式返回 true，则允许合并。如果返回 false，则合并被阻止。

自定义表达式支持标准 JavaScript 语法（ES2022），并且最大长度为 1024 个字符。

可用的上下文变量：

• changeRequest.subject - 变更请求的主题/标题

• changeRequest.description - 变更请求的描述

• changeRequest.outdated - 变更请求是否已过时（布尔值）

• changeRequest.createdBy.id - 创建变更请求的用户 ID

• reviews - 审阅对象数组，每个对象包含：

  • reviews[].status - 审阅状态（"approved" 或 "changes_requested")

  • reviews[].reviewer.id - 审阅者的 ID

• actor.id - 尝试合并的用户 ID

常见表达式示例：

要求多个已批准的审阅

reviews.filter(r => r.status === "approved").length >= 2

要求特定用户的批准

reviews.some(r => r.reviewer.id === "harry" && r.status === "approved")

要求对紧急更改提供描述

!changeRequest.subject.includes("[URGENT]") || !!changeRequest.description

仅允许自合并用于小幅更改

changeRequest.createdBy.id === actor.id ? changeRequest.subject.startsWith("[minor]") : true