GitLab中禁止同名分支反向合并推送的配置方案

需求背景 #

禁止将remote同名分支合并到本地分支后推送（适用于所有分支），仅允许将本地分支合并到remote同名分支（保留remote分支的线性拓扑），同时允许不同名分支间的任意合并推送。

例如：

• 禁止场景：remote main领先于本地main，本地提交后执行git pull（merge）再推送，导致remote分支拓扑被分叉
• 允许场景：将本地分支合并到remote分支（如变基后推送、或通过合并提交将本地变更合入remote分支），以及不同名分支间的合并推送（main→dev、dev→main等）

实现方案 #

通过GitLab保护分支规则+**自定义预接收钩子（pre-receive hook）**实现：

1. 保护分支禁止强制推送，作为基础限制
2. 自定义钩子识别并拒绝「同名分支合并remote后推送」的场景

具体配置步骤 #

1. 配置保护分支 #

在GitLab项目的「设置」→「仓库」→「保护分支」中：

• 添加需要限制的分支（可使用通配符*匹配所有分支，或指定main、dev等）
• 勾选「允许开发者推送」（满足命令行推送需求）
• 取消勾选「允许强制推送」，防止历史被改写

2. 添加自定义预接收钩子 #

GitLab的预接收钩子会在推送前执行逻辑判断，需在服务器端配置：

1. 登录GitLab服务器，定位到项目仓库目录，路径通常为：

   /var/opt/gitlab/git-data/repositories/<命名空间>/<项目名>.git
   

2. 进入hooks子目录，创建pre-receive文件，写入以下脚本：

   #!/bin/bash
   
   while read oldrev newrev refname; do
       # 忽略标签推送，只处理分支
       if [[ "$refname" != refs/heads/* ]]; then
           continue
       fi
   
       target_branch=$(basename "$refname")
       # 新建分支直接允许
       if [[ "$oldrev" == "0000000000000000000000000000000000000000" ]]; then
           continue
       fi
   
       # 检查推送的提交区间内是否存在合并提交
       merge_commits=$(git rev-list --merges "$oldrev..$newrev")
       if [[ -n "$merge_commits" ]]; then
           for commit in $merge_commits; do
               parents=$(git rev-parse "$commit"^@)
               parent_count=$(echo "$parents" | wc -w)
               if [[ $parent_count -ge 2 ]]; then
                   has_remote_parent=0
                   has_local_parent=0
                   for parent in $parents; do
                       if git merge-base --is-ancestor "$parent" "$oldrev"; then
                           has_remote_parent=1
                       else
                           has_local_parent=1
                       fi
                   done
                   # 存在同时来自remote和本地的父节点，属于禁止的合并场景
                   if [[ $has_remote_parent -eq 1 && $has_local_parent -eq 1 ]]; then
                       echo "ERROR: 禁止将remote同名分支合并到本地后推送，请使用rebase或MR将本地变更合入remote分支" >&2
                       exit 1
                   fi
               fi
           done
       fi
   done
   
   exit 0
   

3. 设置文件权限（确保Git用户可执行）：

   chmod 755 pre-receive
   chown git:git pre-receive
   

4. 重启GitLab服务使配置生效：

   gitlab-ctl restart
   

验证方法 #

1. 禁止场景测试：
   • 本地分支落后于remote，本地提交后执行git pull（merge），尝试推送同名分支，会被钩子拒绝
2. 允许场景测试：
   • 本地分支落后于remote，执行git pull --rebase后推送，可正常提交（快进推送）
   • 将本地分支合并到不同名remote分支（如git push origin dev:main），可正常提交
   • 新建分支推送，可正常提交

扩展说明 #

• 若仅需限制特定分支，可在脚本中添加分支判断（如if [[ "$target_branch" != "main" ]]; then continue; fi）
• 如需多项目统一应用规则，可使用GitLab的组级别自定义钩子，在组的「设置」→「仓库」→「组钩子」中配置

内容的提问来源于stack exchange，提问作者user2518618