> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/collaboration/merge-rules.md).

# 合并规则

{% hint style="info" %}
此功能适用于 [专业版和企业版方案](https://www.gitbook.com/pricing).
{% endhint %}

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

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

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

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

## 使用合并规则

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

### 组织级配置

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

要为你的组织配置合并规则，请返回你的组织 **主页** 并点击 **设置** <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>变更请求必须与主内容分支保持同步。如果自变更请求创建后主内容已更新，则需要在合并前重新基于或更新它。</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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.