GitLab Merger Bot 技术文档

镜像概述和主要用途

GitLab Merger Bot 是一款用于自动化处理 GitLab 合并请求（Merge Request, MR）的工具。其核心目标是确保每次合并后 master 分支保持"绿色"（即构建通过），通过自动执行 rebase、检查流水线状态、处理冲突等操作，减少人工维护合并请求的时间成本，尤其适用于需要处理大量合并请求的大型项目或单体仓库。

核心功能和特性

基本功能

1. 自动化合并流程

   • 将合并请求分配给 bot 后，bot 会将其加入按仓库划分的串行（FIFO）队列
   • 队列中轮到该请求时，自动执行 rebase 操作并等待流水线完成
   • 若检测到问题，自动将合并请求重新分配给原作者，问题包括：
     • 流水线失败或等待手动操作
     • 存在未解决的讨论
     • rebase 时发生冲突

2. 状态反馈

   • 通过 GitLab 界面实时反馈处理状态（如分配、合并成功等）

高级功能

• 自动生成提交信息：基于 MR 标题生成提交信息，并附加原 MR 链接
• 自动触发阻塞任务：适用于 E2E 测试等需要手动触发的阻塞性任务
• 标签控制行为：
  • bot:skip-squash：跳过提交压缩
  • bot:high-priority：将 MR 置于队列首位（适用于热修复等紧急场景）

使用场景和适用范围

• 大型项目/单体仓库：需批量处理大量合并请求，减少人工操作
• 持续集成环境：确保合并后 master 分支始终可构建，避免流水线失败
• 紧急修复场景：通过 bot:high-priority 标签优先处理热修复 MR
• 标准化合并流程：统一合并规范（如提交信息格式、分支清理等）

前置要求

获取认证令牌

1. 创建 Bot 用户
   为 bot 创建独立的 GitLab 账户（推荐专用账户，避免使用可能离开项目的个人账户）

2. 生成个人访问令牌

   • 使用 bot 账户登录 GitLab，访问 个人访问令牌页面（自托管实例需替换为对应 URL）
   • 新建令牌，勾选 api 权限范围

配置 GitLab 仓库

1. 权限设置
   确保 bot 用户拥有合并请求的接受权限（如 Maintainer 或 Admin 角色）

2. 合并设置
   在仓库「设置 > 合并请求」中配置：

   • 合并方法：设为「Fast-forward merge」
   • 勾选「仅允许流水线成功后合并」
   • （可选）勾选「所有讨论必须解决」

使用方法

Docker 部署

直接运行

docker run -d --name gitlab-merger-bot --restart on-failure \
  # -e GITLAB_URL="[***]" \  # 自托管 GitLab 实例需指定
  -e GITLAB_AUTH_TOKEN="<your-bot-token>" \
  -v "$(pwd)/data":/data \
  pepakriz/gitlab-merger-bot:latest

Docker Compose 部署

创建 docker-compose.yml：

version: '3'
services:
  gitlab-merger-bot:
    image: pepakriz/gitlab-merger-bot:latest
    container_name: gitlab-merger-bot
    restart: on-failure
    environment:
      # GITLAB_URL: "[***]"  # 自托管实例取消注释并修改
      GITLAB_AUTH_TOKEN: "<your-bot-token>"
      CI_CHECK_INTERVAL: 10  # 流水线检查间隔（秒）
      MR_CHECK_INTERVAL: 20  # MR 检查间隔（秒）
      REMOVE_BRANCH_AFTER_MERGE: "true"  # 合并后删除分支
    volumes:
      - ./data:/data  # 持久化队列数据

启动服务：

docker-compose up -d

Kubernetes 部署（Helm）

1. 添加 Helm 仓库：

helm repo add gitlab-merger-bot [***]

2. 安装 Chart：

helm install gitlab-merger-bot gitlab-merger-bot \
  # --set settings.gitlabUrl="[***]" \  # 自托管实例需指定
  --set settings.authToken="<your-bot-token>"

纯 JS 应用运行

# 克隆代码并安装依赖
git clone [***]
cd gitlab-merger-bot
yarn install

# 构建并启动
yarn run build
GITLAB_AUTH_TOKEN="<your-bot-token>" yarn run start

配置选项

通过环境变量配置 bot 行为，支持以下参数：

开发相关

WebHook 开发调试

使用 *** 暴露本地服务：

***_AUTH=<your-***-auth-token>
docker run -it --rm --net=host -p 4040:4040 -e ***_AUTH="$***_AUTH" wernight/*** *** http 4000

需先启用 HTTP 服务（HTTP_SERVER_ENABLE=true）并配置 WEB_HOOK_TOKEN。

功能演示

!分配给 Bot
!合并成功