推送规则

推送规则用于在服务端强制执行提交规范。违反规则的推送会在入库之前被拒绝，并给出指明提交、规则和原因的提示信息。推送规则从 Gitea Enterprise v27.3.8 开始提供，修改推送规则需要有效的许可证。

可以检查什么

检查项	说明
必需的格式	提交信息必须匹配该 RE2 正则表达式，例如“工单号 + 摘要”。
禁止的格式	提交信息不得匹配该 RE2 正则表达式。
匹配完整提交信息	默认只匹配标题（第一行），启用后匹配整条提交信息。
分支名称	新建分支的名称必须匹配该表达式。已有分支和默认分支始终允许。
提交作者邮箱	每个新提交的作者邮箱必须匹配该表达式，例如公司邮箱域名。
禁止的文件名	新提交不得新增或修改路径匹配该表达式的文件。
最大文件大小	新提交不得新增或修改超过该 MiB 数的文件。Git LFS 中的文件不受影响，因为提交的只是体积很小的指针。`0` 表示不限制。
每次推送的最大新提交数	执行提交检查时，一次推送或合并最多可带入的新提交数量。超过则被拒绝，需要拆分。`0` 表示不限制，多条规则都设置时取最小值。

规则可以设置名称、描述和示例，它们会显示在拒绝提示中，让开发者知道期望的格式。

要快速填写提交信息规则，可以勾选一个或多个允许的格式（工单号加摘要、带工单号的 Conventional Commits、Revert、Merge branch），然后点击填充。保存前请检查生成的表达式；规则保存并启用之前不会生效。

不检查的内容

只检查分支上新引入的提交，且仅在创建分支时检查分支名称。仅包含标签的推送、Wiki 页面、导入的历史以及系统生成的提交不会被检查。

在哪里配置

范围	位置
站点	`站点管理 > 推送规则`
组织	`组织 > 设置 > 推送规则`
仓库	`仓库 > 设置 > 推送规则`

每个范围提供两类规则。

强制规则

强制规则对其范围内的每次推送生效，下级无法禁用。站点强制规则适用于所有仓库，组织强制规则适用于该组织的所有仓库。仓库设置中只以只读方式显示当前生效的强制规则及其来源（站点、组织或仓库）。如需修改，请联系站点管理员或组织所有者。

默认规则

默认规则在下级没有选择退出时生效。站点默认规则适用于所有未退出的仓库。组织和仓库可以选择模式：

模式	行为
继承	跟随上级规则，并与其保持同步。
复制	复制一份上级规则的快照，之后可以独立编辑。
自定义	只为当前范围定义规则。
无	在当前范围禁用默认规则，即使上级启用了规则。

页面会显示当前生效的默认规则。强制规则始终叠加在默认规则之上。

保留独立推送规则的仓库被转移后，请对照新所有者的强制规则重新检查该规则。

测试规则

每个页面的测试推送规则部分可以用示例提交信息、新分支名称、作者邮箱或文件路径来评估当前生效的规则，包括表单中尚未保存的修改，只测试填写了的字段。启用规则之前可以用它验证表达式。

被拒绝的推送

被拒绝的推送会列出前几个被拒绝的提交以及未通过的规则，例如：

Commit message does not meet the requirements.
2 commit(s) rejected, showing the first 2:
Mandatory rule "Ticket ID": the message does not match the required format.
Example: PROJ-123 fix login redirect

一次写入检查的新提交数量有上限，推送过大时请拆分。当 PR 的默认合并信息不满足提交信息规则时，请在合并前修改合并标题，或在目标分支中添加合规的模板，例如 .gitea/default_merge_message/MERGE_TEMPLATE.md。

Agents

Agents 同样遵守推送规则的其他检查：Gitea 会在 Agent 工作前把规则交给它，以便它自行测试。规则可以让 Agent 跳过部分检查（提交信息、分支名称、作者邮箱、禁止的文件名、最大文件大小）。被跳过的检查只对 Agent 运行创建的分支以及 Agent 自己编写的提交生效，且每次使用都会被审计。对于分支名称检查，还可以设置 Agent 分支名称模板，支持 {agent} 和 {issue} 占位符（没有工单时用 work），让 Agent 的分支满足规则。分支名称被拒绝的 Agent 不会启动。

审计

推送规则的变更，以及跳过推送规则的写入（包括 Agent 跳过的检查），会记录到审计日志。