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

# 合并规则

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

合并规则允许你定义变更请求合并前必须满足的条件，例如要求特定用户进行审核，或要求变更请求包含主题或描述。

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

配置合并规则后，系统会在合并前自动评估变更请求。如果某条规则未得到满足，合并将被阻止，直到满足相关要求。

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

## 使用合并规则

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

### 组织级配置

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

要为组织配置合并规则，请返回组织 **主页** ，然后点击侧边栏中 **设置** <picture><source srcset="broken://files/CG9bVSmdbJnQxrYiNbRI" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-5b92a51c6dfeecba3e53103f6e8d553bf798e57b%2F25_01_10_settings_icon_light.svg?alt=media" alt=""></picture>，该选项位于 **管理** 下。在设置页面中，点击 **合并规则** ，该选项位于 **组织** 分组下。你可以在此为整个组织指定合并规则。

你可以选择不受限制的合并，也可以从预设列表中选择规则，应用于整个组织的变更请求。

### 分区级配置

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

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

为分区设置合并规则时，你可以选择：

* **继承** 组织的合并规则
* **定义自定义规则** ，专门用于该分区
* **禁用合并规则** ，完全不使用合并规则

{% hint style="info" %}
如果继承组织规则，组织合并规则的任何更改都会自动应用于该分区。
{% endhint %}

要为分区配置合并规则，请打开编辑器左上角的 **操作菜单** <i class="fa-ellipsis">:ellipsis:</i> ，然后点击 **合并规则**。你可以在此指定是继承组织的合并规则，还是为该分区配置新的专用规则。

## 规则评估

### 规则的工作方式

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

* 配置中的所有规则都必须通过，才允许合并
* 规则按照其在配置中出现的顺序进行评估
* 如果任何规则未通过，合并将被阻止，并显示相应的错误消息
* 具有绕过功能的规则可以覆盖先前未通过的结果

### 绕过规则

某些规则具有绕过功能（例如 **允许指定人员绕过要求**）。这些特殊规则可以覆盖其他规则未通过的结果。如果绕过规则的评估结果为真，即使其他规则未通过，也允许合并。

## 最佳实践

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

* **从简单规则开始**：从基本规则开始，例如要求至少有一项审查。
* **逐步扩展**：随着团队发展、工作流程日趋成熟，再添加更具体的要求。
* **谨慎使用绕过权限**：仅向可信的管理员授予绕过权限。
* **定期审查**：根据团队的实际工作流程模式调整规则。
* **先测试**：尽可能先在测试分区中测试规则变更，再将其应用到生产分区。

## 可用的规则类型

### 审查要求

<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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
