RisingWave 持续集成（CI）实战指南：Fork PR 审批、CI 标签体系与回归二分定位-平芜编程栈

数据库
流处理
后端
数据工程

【免费下载链接】risingwave

Event streaming platform for agentic AI. Continuously ingest, transform, and serve event streams in real time, at scale.

项目地址：https://gitcode.com/gh_mirrors/ri/risingwave

点击查看免费下载

RisingWave 的持续集成体系以 Buildkite 为核心，通过pull-request与main-cron两条流水线覆盖从代码提交到发布验证的全过程。本文基于仓库中的 CI 开发文档，结合ci/workflows/下的真实流水线定义与ci/scripts/find-regression.py实现，完整讲解 Fork PR 的构建审批机制、CI 标签（Label）的触发规则，以及用二分法自动定位回归提交的实操方案，帮助贡献者与维护者高效驾驭这套 CI 工作流。

RisingWave CI 概览：两条核心流水线

在动手之前，先理解 RisingWave 的 CI 是由Buildkite承载的。仓库中所有流水线定义都集中在ci/workflows/目录下，其中两条流水线与日常开发关系最密切：

pull-request流水线（定义于 ci/workflows/pull-request.yml）：每个 Pull Request 的常规检查流水线，包含build、build-other（构建 Java connector node、UDF 等组件）、docslt、单元测试、E2E 测试、确定性模拟测试等步骤。
main-cron流水线（定义于 ci/workflows/main-cron.yml）：更完整的主分支回归与发布流水线，包含 release 版 E2E 测试（覆盖 SQLite / PostgreSQL / MySQL 三种 Meta 存储后端）、确定性（madsim）集成测试、向后兼容测试、Sqlsmith 差分测试、微基准测试，以及打 tag 时的发布与多架构 Docker 镜像构建步骤。

两条流水线都大量使用 YAML 锚点（anchors）来复用公共配置。例如 ci/workflows/main-cron.yml 中定义的auto-retry锚点，会在 Agent 被 AWS EC2 spot 实例回收（signal_reason: agent_stop）或进程异常退出（exit_status: -1）时自动重试最多 3 次，这体现了 CI 基础设施针对云上不稳定环境的容错设计。

Fork PR 的 Buildkite 审批机制

为什么 Fork PR 需要人工审批

Buildkite 会对分支位于 RisingWave 仓库内的、符合条件的 Pull Request 自动运行流水线；但对于从 Fork 仓库发起的 PR，出于安全考虑，必须先获得维护者审批，Buildkite 才会执行 PR 中的代码。

审批方式非常简单：维护者审阅完改动后，在 GitHub 的 PR 评论区原样发布如下评论即可：

/approve-run-bk

谁的命令会被采纳

Buildkite 只接受来自以下身份的/approve-run-bk命令：

受信任的 GitHub 仓库 owner、member 或 collaborator；
或关联到 Buildkite 用户、且具备该流水线运行权限的 GitHub 账号。

来自外部贡献者的同一条评论不会触发构建。

审批的有效范围与重新审批

这条命令会为 PR 的当前 head commit创建一次新的构建。有两个关键细节需要留意：

审批不随提交延续：贡献者每次新推送 commit 之后，之前获得的审批自动失效，维护者必须重新发布/approve-run-bk评论，才能对新 commit 触发构建。
pull-request与main-cron可一并触发：审批通过后，当 PR 进入 ready-for-review 状态时pull-request流水线就会运行。若还想为 Fork PR 运行main-cron流水线，需要先添加相应的标签（见下文 CI 标签指南），再发布/approve-run-bk。一条审批评论在其各自条件满足时可以同时触发两条流水线。

CI 标签（Label）完全指南

RisingWave 通过给 PR 打 GitHub Label 来控制 CI 运行哪些步骤。所有标签对应的触发条件都写在两条流水线的 YAML 中——各步骤的if条件会同时检查 PR 标签和CI_STEPS环境变量，例如 ci/workflows/main-cron.yml 中 e2e 测试步骤的if就是：

!(build.pull_request.labels includes "ci/main-cron/run-selected") && build.env("CI_STEPS") == null || build.pull_request.labels includes "ci/run-e2e-tests" || build.env("CI_STEPS") =~ /(^|,)e2e-tests?(,|$$)/

标签体系分为四类，官方文档原意如下：

标签	作用
`ci/run-xxx ...`	在 PR 工作流中运行`ci/run-xxx`所指示的额外步骤
`ci/pr/run-selected`+`ci/run-xxx ...`	在DRAFT PR中只运行`ci/run-xxx`选中的步骤
`ci/main-cron/run-all`	为你的 PR 运行完整的`main-cron`工作流
`ci/main-cron/run-selected`+`ci/run-xxx ...`	在你的 PR 中只运行来自`main-cron`工作流的、由`ci/run-xxx`指定的步骤；可用于验证某个`main-cron`修复是否生效

ci/run-xxx的具体候选值，可以直接从pull-request.yml和main-cron.yml各步骤的if条件中查到。例如在 ci/workflows/pull-request.yml 中可以找到ci/run-e2e-tests、ci/run-unit-test、ci/run-check、ci/run-e2e-test-deterministic-simulation、ci/run-recovery-test-deterministic-simulation、ci/run-sqlsmith-fuzzing-tests等；在 ci/workflows/main-cron.yml 中则有ci/run-e2e-tests、ci/run-e2e-source-tests、ci/run-e2e-sink-tests、ci/run-micro-benchmarks、ci/run-backwards-compat-tests等。从源码结构看，main-cron中绝大多数步骤都保留了ci/run-xxx标签与CI_STEPS环境变量两条触发路径，这正是“在 PR 中验证 main-cron 修复”的设计基础。

实战示例：为 PR 运行 main-cron 的指定步骤

以官方文档给出的案例（对应 upstream PR #17197）说明：假设你想在自己的 PR 中运行main-cron工作流里的e2e-test和e2e-source-test，只需要依次添加三个标签：

添加ci/run-e2e-test（注意：该标签同时会被 pull-request 与 main-cron 两条流水线的相应步骤识别）；
添加ci/run-e2e-source-tests；
添加ci/main-cron/run-selected，跳过所有未被ci/run-xxx选中的其他步骤。

添加标签后，main-cron中两个对应步骤的if条件分别命中build.pull_request.labels includes "ci/run-e2e-tests"与... includes "ci/run-e2e-source-tests"（见 ci/workflows/main-cron.yml 与 ci/workflows/main-cron.yml），而其余步骤由于ci/main-cron/run-selected标签存在而被第一条条件否定，从而实现“精准定向验证”。

Main Cron Bisect Guide：自动二分定位回归提交

当main-cron流水线在某个提交上失败、需要定位是哪一次提交引入回归时，可以使用仓库内置的main-cron-bisect流水线，它会基于二分查找自动缩小问题区间。

第一步：创建 Bisect 构建

在 Buildkite 的main-cron-bisect流水线页面新建构建（builds/#new），并配置以下环境变量：

环境变量	含义
`GOOD_COMMIT`	已知正常的提交哈希
`BAD_COMMIT`	已知异常的提交哈希
`BISECT_BRANCH`	执行二分定位的分支名
`CI_STEPS`	二分过程中要运行的 CI 步骤名，多个步骤用逗号分隔

其中CI_STEPS的候选值同样可以从 ci/workflows/main-cron.yml 中每个步骤的if条件里查到（例如e2e-tests、unit-tests、recovery-tests-deterministic-simulation等）。

第二步：官方示例配置

文档给出的可直接尝试的完整示例：

GOOD_COMMIT=29791ddf16fdf2c2e83ad3a58215f434e610f89a BAD_COMMIT=7f36bf17c1d19a1e6b2cdb90491d3c08ae8b0004 BISECT_BRANCH=kwannoel/test-bisect CI_STEPS="test-bisect,disable-build"

注意示例中CI_STEPS带上了disable-build：main-cron的build、build-other、build-simulation、docslt四个步骤都会检查build.env("CI_STEPS") !~ /(^|,)disable-build(,|$$)/（见 ci/workflows/main-cron.yml），因此把disable-build写进CI_STEPS可以跳过重复构建，让二分过程更快。

第三步：二分流程的底层原理

main-cron-bisect流水线定义在 ci/workflows/main-cron-bisect.yml 中，它的第一步find-regressed-step会调用 ci/scripts/find-regression.py 的start命令，并在满足CI_STEPS != null时运行。真正执行二分逻辑的是该脚本（262 行，自带单元测试，可直接./ci/scripts/find-regression.py运行测试）。

从 ci/scripts/find-regression.py 的注释与实现看，算法核心如下：

以GOOD_COMMIT（含）与BAD_COMMIT（不含）为区间上下界，取中间提交：git rev-list --count GOOD..BAD统计提交数，再git rev-list --reverse GOOD..BAD | head -n N | tail -n 1取出中间那一条；
通过buildkite-agent pipeline upload动态上传一个新的 pipeline（format_step），其中包含一个trigger: "main-cron"的步骤，在BISECT_BRANCH分支的中间提交上、以CI_STEPS环境变量运行main-cron，并标记soft_fail: true；
后续的check命令读取该步骤的 outcome：若soft_failed，说明回归在前半段，把BAD_COMMIT收缩到该提交；若passed，说明回归在后半段，用git log --reverse --ancestry-path取该提交的下一个提交更新GOOD_COMMIT；
当GOOD_COMMIT == BAD_COMMIT时，通过report_step上报 “Regressed Commit” 结果，二分结束。

整个过程中，脚本只运行CI_STEPS指定的步骤而非整条流水线，且每一步都会等待上次运行成功后再继续，从而把每次验证的开销降到最低。这种“动态上传 pipeline + 软失败收集结果 + 迭代收缩区间”的模式，是定位大规模分布式系统回归的高效做法。

延伸：CI 中的 Meta 后端矩阵与失败信息收集

理解 CI 全貌对日常排查也很有帮助。main-cron的 release E2E 测试通过sql-backend锚点（见 ci/workflows/main-cron.yml）以矩阵方式同时验证三种 Meta 存储后端：

SQLite：sqlite:///tmp/rwmeta.db?mode=rwc
PostgreSQL：postgres://postgres:postgres@db:5432/rwmeta
MySQL：mysql://root:123456@mysql-meta:3306/rwmeta

这些端点通过RISEDEV_SQL_ENDPOINT环境变量注入测试脚本，保证流式计算引擎在不同元数据存储下的兼容性。

此外，几乎所有 E2E 步骤都挂载了./ci/plugins/upload-failure-logs插件，失败时会把容器日志上传，方便贡献者直接下载日志定位问题；确定性恢复测试则改用upload-failure-logs-zipped（压缩后上传，避免日志量过大）。main-cron的结尾还会在测试全部结束后（即使部分失败）上传覆盖率报告（ci/workflows/main-cron.yml），并通过ci/scripts/notify.py对失败测试发送通知。

小结

RisingWave 的 CI 体系围绕“安全、可控、可定向”三条原则设计：Fork PR 用/approve-run-bk评论把执行权交还给维护者；ci/run-xxx与ci/main-cron/run-selected标签让贡献者可以在不跑完整流水线的前提下定向验证特定步骤；main-cron-bisect配合 ci/scripts/find-regression.py 把回归定位变成一次自动化的二分搜索。掌握了这三块内容，无论是提交代码、review Fork PR，还是追踪主分支回归，都能在 ci/workflows/pull-request.yml、ci/workflows/main-cron.yml 与 ci/workflows/main-cron-bisect.yml 三份配置中找到清晰的依据与入口。