# 合并规则

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

这些规则有助于保持内容质量，并确保你的文档工作流中有适当的审核流程。

当你配置了合并规则后，它们会在变更请求可被合并之前自动进行评估。如果某条规则未满足，合并将被阻止，直到要求得到满足。

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

## 使用合并规则

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

### 组织级配置

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

要为你的组织配置合并规则，请打开侧边栏顶部的组织菜单并选择 **设置** <picture><source srcset="broken-reference" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FwkBqgOPry9HAcW4cxJk0%2Fsettings.svg?alt=media&#x26;token=67bdbb00-ebf3-4a2d-9df8-0c822406f71c" alt=""></picture>。在“设置”页面中，选择侧边栏中 **合并规则** 下的 **组织** 部分。在这里，你可以为整个组织指定合并规则。

你可以选择不受限制地合并，或者从预设列表中进行选择，以将其应用到整个组织中的变更请求。

### 空间级配置

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

这让你可以灵活地为重要文档设置更严格的规则，并为草稿内容设置更宽松的规则。

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

* **继承** 来自你的组织的合并规则
* **定义自定义规则** 特定于该空间
* **禁用合并规则** 完全

{% hint style="info" %}
如果你继承组织规则，那么对组织合并规则的任何更改都会自动应用到该空间。
{% endhint %}

要为你的组织配置合并规则，请打开编辑器左上角的 **操作菜单** <i class="fa-ellipsis">:ellipsis:</i> ，然后选择 **合并规则**。在这里，你可以指定是继承组织的合并规则，还是配置该空间特有的新规则。

## 规则评估

### 规则如何工作

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

* 配置中的所有规则都必须通过，才允许合并
* 规则会按照它们在你的配置中出现的顺序进行评估
* 如果任何一条规则失败，合并将被阻止，并显示相应的错误消息
* 具有绕过能力的规则可以覆盖之前的失败

### 绕过规则

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

## 最佳实践

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

* **从简单开始**：从基础规则开始，例如要求至少一次审核。
* **逐步扩展**：随着团队成长和工作流程成熟，添加更具体的要求。
* **谨慎使用绕过**：只向受信任的管理员授予绕过权限。
* **定期审查**：根据团队的实际工作流模式调整规则。
* **先测试**：如果可能，在应用到生产空间之前，先在测试空间中测试规则更改。

## 可用规则类型

### 审核要求

<table><thead><tr><th width="279.703125">规则</th><th>描述</th></tr></thead><tbody><tr><td><strong>要求至少一次审核</strong></td><td>确保在变更请求可被合并之前，至少有一名团队成员审核过该变更请求。</td></tr><tr><td><strong>要求所有审核都已批准</strong></td><td>所有 <strong>已完成的</strong> （非请求中的）审核都必须是批准状态。如果任何审核者请求更改或拒绝该变更请求，合并将被阻止。</td></tr><tr><td><strong>要求由指定操作者审核</strong></td><td>要求所有指定用户都批准。你可以选择在变更请求合并之前必须审核并批准该请求的特定团队成员。</td></tr><tr><td><strong>要求由指定操作者中的一人审核</strong></td><td>要求至少获得指定用户中的一人的批准。当你有多个合格审核者但只需要该组中的一个批准时，这很有用。</td></tr><tr><td><strong>要求 Docs Agent 审核（即将推出）</strong></td><td>要求来自 GitBook AI 代理的审核。这可确保在合并前对内容变更执行自动化质量检查。</td></tr></tbody></table>

### 变更请求要求

<table><thead><tr><th width="279.703125">规则</th><th>描述</th></tr></thead><tbody><tr><td><strong>要求最新的变更请求</strong></td><td>变更请求必须与主内容分支保持最新。如果自变更请求创建以来主内容已更新，你需要在合并前对其执行变基或更新。</td></tr><tr><td><strong>要求主题</strong></td><td>变更请求必须具有描述性的主题/标题。空主题将阻止合并。</td></tr><tr><td><strong>要求描述</strong></td><td>变更请求必须包含说明进行了哪些更改以及原因的描述。</td></tr></tbody></table>

### 高级选项

<table><thead><tr><th width="279.703125">规则</th><th>描述</th></tr></thead><tbody><tr><td><strong>允许指定操作者绕过要求</strong></td><td>你可以指定允许绕过所有其他合并规则要求的特定用户。这对于管理员或需要覆盖规则的紧急情况很有用。</td></tr><tr><td><strong>自定义表达式</strong></td><td>你可以使用自定义 JavaScript 表达式创建高级合并规则。这使你能够基于评估上下文定义复杂逻辑，并可访问变更请求、审核以及尝试合并的用户的属性。</td></tr></tbody></table>

#### 自定义表达式

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

{% hint style="info" %}
自定义表达式支持标准 JavaScript 语法（ES2022），最大长度为 1024 个字符。
{% endhint %}

**可用的上下文变量：**

* `changeRequest.subject` - 变更请求的主题/标题
* `changeRequest.description` - 变更请求的描述
* `changeRequest.outdated` - 变更请求是否已过时（布尔值）
* `changeRequest.createdBy.id` - 创建变更请求的用户 ID
* `reviews` - 审核对象数组，每个对象包含：
  * `reviews[].status` - 审核状态（`"已批准"` 或者 `"已请求更改"`)
  * `reviews[].reviewer.id` - 审核者的 ID
* `actor.id` - 尝试合并的用户 ID

**常见表达式示例：**

{% code title="要求多个已批准的审核" %}

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

{% endcode %}

{% code title="要求特定用户批准" %}

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

{% endcode %}

{% code title="要求紧急更改提供描述" %}

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

{% endcode %}

{% code title="仅允许小改动进行自我合并" %}

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

{% endcode %}