> 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="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2FwkBqgOPry9HAcW4cxJk0%2Fsettings.svg?alt=media&amp;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` - 审核状态（`"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.