outofcoffee/build-clerk

Build Clerk

镜像概述和主要用途

Build Clerk 是一款用于响应构建管道事件的工具，旨在通过自定义规则自动执行操作（如回滚提交、锁定分支、触发重建等），维护主分支的稳定性。它支持多种构建事件和第三方集成（如 Jenkins、Bitbucket、Slack），并提供强大的 DSL（领域特定语言）来自定义响应逻辑。

核心功能和特性

• 多事件响应：支持 buildFailed、branchStartsFailing、buildPassed、branchStartsPassing、repository、pullRequestMerged 等多种构建事件。
• 灵活操作能力：可执行回滚提交、锁定分支、触发分支重建、发送 Slack 通知等操作。
• 自定义规则 DSL：通过简洁的 DSL 定义事件响应逻辑，满足个性化需求。
• 多平台集成：与 Jenkins、Bitbucket、Slack 等工具无缝集成，接收事件并执行操作。
• 可配置数据存储：支持内存存储（测试用）和 MongoDB 持久化存储。

使用场景和适用范围

• 自动回滚导致主分支构建失败的提交（基于失败阈值规则）。
• 主分支 CI 失败时，通知团队有拉取请求被合并。
• 连续构建失败后锁定分支，防止进一步变更。
• 触发分支重建以识别不稳定测试（Flaky Test）。
• 向 Slack 频道发送自定义消息，通知构建状态或需要人工干预的情况。

使用方法和配置说明

快速启动

使用 Docker 运行 Build Clerk：

bash
docker run --rm -it -p9090:9090 outofcoffee/build-clerk

访问 http://localhost:9090 确认服务运行。

配置选项

基本配置

• RULES_FILE（必填）：响应构建生命周期事件的规则文件路径。

Slack 配置

• SLACK_USER_TOKEN：具有 chat.write 权限的 Slack 用户令牌。

Jenkins 配置

• JENKINS_BASE_URL：Jenkins 服务器基础 URL。
• JENKINS_USERNAME：Jenkins 用户名。
• JENKINS_PASSWORD：Jenkins API 密钥或密码。

Bitbucket 配置

• BITBUCKET_REPO_USERNAME：Bitbucket 仓库用户（或组织）名。
• BITBUCKET_REPO_SLUG：Bitbucket 仓库的 "repo slug" 名称。
• BITBUCKET_AUTH_USERNAME：Bitbucket 认证用户名（若与仓库用户名不同）。
• BITBUCKET_PASSWORD：Bitbucket 认证密码（建议使用 "应用密码"）。

全局过滤器

• FILTER_BRANCHES：仅处理指定 SCM 分支的事件。
• FILTER_REPOS：仅处理指定仓库的事件（仅适用于拉取请求）。

安全配置

• AUTH_CONFIG_FILE：用于 HTTP Basic 认证的 Shiro 属性文件路径（参考 Shiro 文档）。

高级配置

• SERVER_PORT：HTTP 监听端口。

数据存储

• 默认配置：使用内存数据存储（应用重启后数据不持久化，适用于测试/评估）。
• MongoDB 持久化：设置以下环境变量切换至 MongoDB：

  bash
  STORE_IMPL=mongo
  MONGO_HOST=localhost  # MongoDB 主机地址
  MONGO_PORT=27017      # MongoDB 端口
  

Git 仓库访问配置

为分析源代码提交，Clerk 需访问 Git 仓库（本地克隆或远程仓库）：

• GIT_REPO_LOCAL_DIR：本地仓库克隆路径。
• GIT_REPO_REMOTE_URL：远程仓库 URL。
• GIT_REPO_USERNAME：HTTP(S) 远程仓库认证用户名。
• GIT_REPO_PASSWORD：HTTP(S) 远程仓库认证密码（或 SSH URL 的可选密码，若未使用公钥）。

使用 revertCommit 操作时，需设置：

• GIT_REPO_PUSH_CHANGES（默认：false）：是否将更改推送到远程仓库（false 时仅本地修改，适用于测试）。

Git 认证说明

• SSH URL：使用运行 Clerk 的机器的本地 SSH 配置（如公钥）。
• HTTP(S) URL：使用配置的用户名和密码，或假定仓库无需认证。

端点

Clerk 暴露以下端点接收事件：

Jenkins

Jenkins 构建报告（通过 Notification Plugin 或 Clerk Plugin 发送）应指向：

/builds

示例：https://clerk.example.com/builds

Slack

Slack 交互式消息回调应指向：

/actions

示例：https://clerk.example.com/actions

Bitbucket

Bitbucket "Pull request merged" 事件的 Webhook 应指向：

/pull-requests/merged

示例：https://clerk.example.com/pull-requests/merged

端点安全

建议为端点配置认证，防止未授权访问。可使用 Clerk 内置的 HTTP Basic Auth：

1. 设置 AUTH_CONFIG_FILE 指向 Shiro 属性文件（示例见 backend/examples/clerk-auth.properties）。
2. 配置第三方回调时，URL 中包含凭据：

   https://someuser:secretpass@clerk.example.com/actions
   

自定义规则 DSL 示例

通过 DSL 定义事件响应逻辑，例如：

groovy
if (failuresForCommitOnBranch <= 2) {
    rebuildBranch()  // 触发分支重建
} else {
    revertCommit()   // 回滚提交
    lockBranch()     // 锁定分支
}

publishAnalysis("general")  // 发布分析报告

更多示例见 parser 模块测试或官方文档。