> 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/xie-zuo/merge-rules.md).

# 合并规则

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

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

配置合并规则后，系统会在变更请求可被合并前自动对其进行评估。如果某项规则未满足，合并将被阻止，直至满足相关要求。

这提供了一种自动化方式来贯彻团队的协作和审核标准。

## 使用合并规则

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

### 组织级配置

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

要为您的组织配置合并规则，请返回您的组织 **主页** 并点击 **设置** <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/xie-zuo/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.