# 合并规则

合并规则可让你定义在变更请求可以合并之前必须满足的要求，例如需要特定用户的审阅，或要求变更请求包含主题或描述。

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

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

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

## 使用合并规则

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

### 组织级配置

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

要为你的组织配置合并规则，请打开侧边栏顶部的组织菜单并选择 **设置** <picture><source srcset="/files/CG9bVSmdbJnQxrYiNbRI" media="(prefers-color-scheme: dark)"><img src="/files/9bcd313f64920f73d3606c61b9fbde5ddf8e3f6b" 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>变更请求必须与主内容分支保持最新。如果自变更请求创建后主内容已有更新，你需要先 rebase 或更新它，然后才能合并。</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` - 审阅状态（`"approved"` 或 `"changes_requested"`)
  * `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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/collaboration/merge-rules.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.