Myrmica Lobicornis - 自动化Pull Request更新与合并工具

]([***]

1. 镜像概述与主要用途

Myrmica Lobicornis是一款GitHub Pull Request（PR）自动化处理工具，旨在通过自动化流程减少人工干预，实现符合条件的PR自动更新与合并。该工具可管理用户或组织的所有仓库，自动筛选、验证、更新并合并PR，同时处理相关Issue、错误标签及协同作者信息，适用于需要标准化PR合并流程的开发团队。

2. 核心功能与特性

2.1 PR筛选与优先级处理

• 自动查找所有带有特定标签（marker.needMerge）的开放PR
• 优先处理带有marker.mergeInProgress标签的PR，若无则按最近更新时间升序处理（即 least recently updated）

2.2 PR合并前验证

• 验证GitHub检查状态（CI、测试等）
• 验证PR"可合并性"（Mergeability）
• 验证审查数量（minReview配置，支持marker.lightReview标签降低审查要求）

2.3 PR更新机制

• 自动检测PR是否需要与基准分支（如master）同步
• 若需同步，支持通过rebase或merge方式更新PR

2.4 PR合并处理

• 支持多种合并方式（mergeMethod配置，可通过marker.mergeMethodPrefix标签覆盖默认方式）
• 合并时自动关闭相关Issue，并同步PR的里程碑
• 若PR描述包含Co-authored-by信息，自动将协同作者添加至合并提交

2.5 错误处理与标签管理

• 合并失败时自动添加marker.needHumanMerge标签，提示需人工介入
• 支持合并重试机制（retry配置，通过marker.mergeRetryPrefix标签管理）

3. 使用场景与适用范围

3.1 适用场景

• 团队协作流程标准化：需统一PR合并条件（如审查数量、CI状态）的团队
• 多仓库管理：用户或组织下多仓库PR的批量自动化处理
• 减少人工干预：重复PR验证、同步、合并流程的自动化，提升开发效率
• 合规性保障：确保PR合并前满足预设条件（如审查、测试通过），降低合入风险

3.2 适用范围

• GitHub个人账号或组织账号下的公开/私有仓库
• 支持GitHub Enterprise（通过github.url配置私有GitHub地址）
• 需自动化PR流程的中小型开发团队或开源项目

4. 使用方法与配置说明

4.1 环境依赖

• 必要环境变量：GITHUB_TOKEN（GitHub访问令牌，需具备repo权限）
• 配置文件：YAML格式，默认路径为./lobicornis.yml（可通过-config参数指定）

4.2 命令行参数

4.3 Docker部署示例

4.3.1 docker run命令

bash
docker run -d \
  --name lobicornis \
  -e GITHUB_TOKEN="your_github_token" \
  -v $(pwd)/lobicornis.yml:/app/lobicornis.yml \
  traefik/lobicornis \
  -config /app/lobicornis.yml

4.3.2 Docker Compose配置

yaml
version: "3"
services:
  lobicornis:
    image: traefik/lobicornis
    container_name: lobicornis
    environment:
      - GITHUB_TOKEN=your_github_token  # 替换为实际GitHub令牌
    volumes:
      - ./lobicornis.yml:/app/lobicornis.yml  # 挂载本地配置文件
    command: -config /app/lobicornis.yml  # 指定配置文件路径
    restart: unless-stopped

4.4 配置文件详解

配置文件采用YAML格式，包含github、git、server、extra、markers、retry、default及repositories等核心模块，示例及参数说明如下：

yaml
# 完整配置文件示例
github:
  user: "foo"               # GitHub用户名或组织名（必填）
  token: "XXXX"             # GitHub令牌（必填，也可通过环境变量GITHUB_TOKEN覆盖）
  url: "[***]"  # GitHub Enterprise地址（可选，公开GitHub无需配置）

git:
  *** "***"  # Git提交用户***（必填）
  userName: "botname"       # Git提交用户名（必填）
  ssh: false                # 是否使用SSH协议拉取代码（默认false，即HTTPS）

server:
  port: 80                  # Web服务器端口（仅在-server模式下生效）

extra:
  debug: false              # 调试模式（默认false）
  dryRun: true              #  dry run模式（默认true，仅模拟操作不实际执行）

markers:
  lightReview: "bot/light-review"          # 降低审查要求的标签
  mergeInProgress: "status/4-merge-in-progress"  # PR更新中标签
  mergeMethodPrefix: "bot/merge-method-"   # 覆盖合并方式的标签前缀（如bot/merge-method-squash）
  mergeRetryPrefix: "bot/merge-retry-"     # 合并重试标签前缀（如bot/merge-retry-3）
  needHumanMerge: "bot/need-human-merge"   # 需人工合并标签
  needMerge: "status/3-needs-merge"        # 需自动合并标签
  noMerge: "bot/no-merge"                  # 禁止合并标签

retry:
  interval: "1m0s"          # 重试间隔（默认1分钟）
  number: 1                 # 最大重试次数（默认1次）
  onMergeable: false        # 是否因"不可合并"状态重试（默认false）
  onStatuses: false         # 是否因GitHub检查失败重试（默认false）

default:
  checkNeedUpToDate: false  # 是否使用GitHub仓库配置检查PR是否需同步（默认false）
  forceNeedUpToDate: true   # 是否强制PR与基准分支同步（需checkNeedUpToDate=false，默认true）
  mergeMethod: "squash"     # 默认合并方式（merge|squash|rebase|ff，默认squash）
  minLightReview: 0         # `lightReview`标签下的最小审查数量（默认0）
  minReview: 1              # 默认最小审查数量（默认1）
  needMilestone: true       # 是否强制PR必须关联里程碑（默认true）
  addErrorInComment: false  # 错误时是否在PR添加评论（默认false）
  commitMessage: "empty"    # squash合并时的提交信息策略（github|empty|description，默认empty）

repositories:
  # 按仓库覆盖默认配置（key为"用户/仓库名"）
  "foo/myrepo1":
    minLightReview: 1
    minReview: 3
    needMilestone: true
  "foo/myrepo2":
    minLightReview: 1
    minReview: 1
    needMilestone: false

4.4.1 核心配置模块说明

• github：GitHub连接配置，user为用户名/组织名，token为访问令牌（优先级：环境变量GITHUB_TOKEN > 配置文件github.token），url用于GitHub Enterprise。
• git：Git提交用户信息，email和userName为必填，ssh控制是否使用SSH协议拉取代码。
• markers：标签配置，定义各流程中使用的GitHub标签名称，需确保仓库中已创建对应标签。
• retry：合并重试配置，控制重试间隔、次数及触发条件。
• default：全局默认PR合并策略，可通过repositories配置按仓库覆盖。

5. 环境变量

6. 相关工具

Myrmica Lobicornis是Myrmica系列工具之一，该系列还包含：

• Myrmica Aloba：PR与Issue标签及里程碑自动管理
• Messor Structor：Mkdocs多文档版本管理
• Lasius Mixtus：跨仓库文档发布工具
• Myrmica Bibikoffi：陈旧Issue自动关闭工具
• Chalepoxenus Kutteri：GitHub仓库活动Slack通知工具
• Myrmica Gallienii：Fork仓库同步工具

7. 名称含义

Myrmica Lobicornis（中文：角头蚁）是一种蚂蚁物种，工具命名寓意其"协作高效、自动化流程"的特性。

!Myrmica Lobicornis# Myrmica Lobicornis - 自动化Pull Request更新与合并工具

]([***]

1. 镜像概述与主要用途

Myrmica Lobicornis是一款GitHub Pull Request（PR）自动化处理工具，旨在通过标准化流程实现PR的自动筛选、验证、更新与合并。该工具可管理用户或组织的所有仓库，自动处理PR的同步、审查验证、合并及错误标签等流程，适用于需减少人工干预、提升PR处理效率的开发团队。

2. 核心功能与特性

2.1 PR筛选与优先级

• 自动识别所有带marker.needMerge标签的开放PR
• 优先处理带marker.mergeInProgress标签的PR，若无则按最近更新时间升序处理（least recently updated）

2.2 PR合并前验证

• 验证GitHub检查状态（CI、测试等）
• 验证PR"可合并性"（Mergeability）
• 验证审查数量（minReview配置，支持marker.lightReview标签降低审查要求）

2.3 PR自动更新

• 检测PR是否需与基准分支（如master）同步
• 支持通过rebase或merge方式更新PR至最新基准分支

2.4 PR合并处理

• 支持多种合并方式（mergeMethod配置，可通过marker.mergeMethodPrefix标签覆盖默认方式）
• 合并时自动关闭相关Issue，并同步PR的里程碑
• 若PR描述含Co-authored-by信息，自动添加协同作者至合并提交

2.5 错误处理与标签管理

• 合并失败时自动添加marker.needHumanMerge标签，提示人工介入
• 支持合并重试机制（retry配置，通过marker.mergeRetryPrefix标签管理）

3. 使用场景与适用范围

3.1 适用场景

• 团队PR流程标准化：需统一PR合并条件（如审查数量、CI状态）的团队
• 多仓库批量管理：用户/组织下多仓库PR的自动化处理
• 减少人工重复操作：PR验证、同步、合并流程自动化，提升效率
• 合规性保障：确保PR合并前满足预设条件（如审查、测试通过）

3.2 适用范围

• GitHub个人账号或组织账号下的公开/私有仓库
• 支持GitHub Enterprise（通过github.url配置私有GitHub地址）
• 中小型开发团队或开源项目的PR流程自动化

4. 使用方法与配置说明

4.1 环境依赖

• 必要环境变量：GITHUB_TOKEN（GitHub访问令牌，需具备repo权限）
• 配置文件：YAML格式，默认路径./lobicornis.yml（可通过-config参数指定）

4.2 命令行参数

4.3 Docker部署示例

4.3.1 docker run命令

bash
docker run -d \
  --name lobicornis \
  -e GITHUB_TOKEN="your_github_token" \
  -v $(pwd)/lobicornis.yml:/app/lobicornis.yml \
  traefik/lobicornis \
  -config /app/lobicornis.yml

4.3.2 Docker Compose配置

yaml
version: "3"
services:
  lobicornis:
    image: traefik/lobicornis
    container_name: lobicornis
    environment:
      - GITHUB_TOKEN=your_github_token  # 替换为实际GitHub令牌
    volumes:
      - ./lobicornis.yml:/app/lobicornis.yml  # 挂载本地配置文件
    command: -config /app/lobicornis.yml  # 指定配置文件路径
    restart: unless-stopped

4.4 配置文件详解

配置文件结构

yaml
github:
  user: "foo"               # 用户名/组织名（必填）
  token: "XXXX"             # GitHub令牌（优先级：环境变量GITHUB_TOKEN > 配置文件）
  url: "[***]"  # GitHub Enterprise地址（可选）

git:
  *** "***"  # Git提交***（必填）
  userName: "botname"       # Git提交用户名（必填）
  ssh: false                # 是否使用SSH协议（默认false，即HTTPS）

server:
  port: 80                  # Web服务器端口（仅-server模式生效）

extra:
  debug: false              # 调试模式（默认false）
  dryRun: true              # 模拟运行（默认true，不实际执行合并）

markers:
  lightReview: "bot/light-review"          # 降低审查要求标签
  mergeInProgress: "status/4-merge-in-progress"  # PR更新中标签
  mergeMethodPrefix: "bot/merge-method-"   # 合并方式覆盖标签前缀（如bot/merge-method-squash）
  mergeRetryPrefix: "bot/merge-retry-"     # 合并重试标签前缀（如bot/merge-retry-3）
  needHumanMerge: "bot/need-human-merge"   # 需人工合并标签
  needMerge: "status/3-needs-merge"        # 需自动合并标签
  noMerge: "bot/no-merge"                  # 禁止合并标签

retry:
  interval: "1m0s"          # 重试间隔（默认1分钟）
  number: 1                 # 最大重试次数（默认1次）
  onMergeable: false        # 是否因"不可合并"状态重试（默认false）
  onStatuses: false         # 是否因GitHub检查失败重试（默认false）

default:
  checkNeedUpToDate: false  # 是否使用GitHub仓库配置检查PR同步状态（默认false）
  forceNeedUpToDate: true   # 是否强制PR与基准分支同步（需checkNeedUpToDate=false，默认true）
  mergeMethod: "squash"     # 默认合并方式（merge|squash|rebase|ff，默认squash）
  minLightReview: 0         # lightReview标签下的最小审查数量（默认0）
  minReview: