MongoDB 的 Evergreen CI 配置体系：项目、组件化 YAML 与发布分支流程

MongoDB 的 Evergreen CI 配置体系：项目、组件化 YAML 与发布分支流程

【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo

本文基于 MongoDB 官方开源仓库（The MongoDB Database）中的 docs/evergreen-testing/yaml_configuration/configuration.md 文档，系统讲解 MongoDB 如何在 Evergreen 持续集成平台上组织mongodb-mongo-master、mongodb-mongo-master-nightly、sys_perf三个 CI 项目，剖析etc/evergreen.yml、etc/evergreen_nightly.yml、etc/system_perf.yml的组件化配置结构，并完整还原其发布分支（Release Branching）的变体取舍策略。读完本文，你将掌握 MongoDB 仓库中 Evergreen 项目配置的完整脉络、各配置文件之间的引用关系，以及为发布分支裁剪构建变体的实操方法。

一、Evergreen 与 MongoDB 的 CI 概览

Evergreen 是 MongoDB 团队自研并开源的持续集成（Continuous Integration, CI）系统，其核心概念包括：

• Project：一个 CI 项目的配置单元，绑定特定分支与配置文件；
• Build Variant（构建变体）：对应一种编译或测试环境（如操作系统、架构、编译选项的组合）；
• Task：构建变体内运行的具体任务，通常一个任务运行一个或多个测试；
• Patch：针对开发者提交的补丁（patch）触发的验证运行；
• Expansions：配置中的变量占位符，形如${key|default}，运行时由执行器解析。

MongoDB 的主仓库通过一套组件化 YAML 配置体系驱动 Evergreen，将任务（tasks）、函数（functions）、构建变体（buildvariants）拆分为多个独立 YAML 组件，再通过 Evergreen 的include机制合并进顶层项目配置文件。这套体系的核心目标是在 master 分支（开发）与发布分支（release）之间复用尽可能多的配置，同时允许按需裁剪。

术语细节可参考 Evergreen 官方的 Project Configuration 文档（Evergreen wiki），本文聚焦 MongoDB 仓库内的实际配置实现。

二、Evergreen 项目（Projects）布局

MongoDB 的 CI 由多个 Evergreen 项目协同支撑，其中三个核心项目定义在关联文档中：

2.1mongodb-mongo-master

MongoDB 开发环境测试的主项目。它包含大量构建变体，每个变体对应一种特定的编译或测试环境，用于支撑日常开发。每个构建变体会运行一组任务，每个任务通常运行一个或多个测试（例如 resmoke 测试套件、单元测试、编译任务、代码检查任务等）。

• 项目配置文件：etc/evergreen.yml；
• 定位：开发主力，包含所有功能相关（feature-specific）、补丁构建必需（patch build required）以及建议（suggested）的变体。

2.2mongodb-mongo-master-nightly

与mongodb-mongo-master跟踪同一条分支，但每个构建变体对应一个受支持的 MongoDB nightly 版本的(version, OS, architecture) 三元组，即面向公开 nightly 发布构建。

• 项目配置文件：etc/evergreen_nightly.yml；
• 定位：仅包含公开 nightly 构建所需的变体，例如亚马逊、Debian、IBM、macOS、RHEL、SUSE、Ubuntu、Windows 等平台的test_release.yml变体。

2.3sys_perf

系统性能测试项目（system performance project），负责 MongoDB 的系统级性能基准测试。

• 项目配置文件：etc/system_perf.yml。

三、项目配置文件体系（Project Configurations）

上述 Evergreen 项目由以下配置文件定义，构成了 MongoDB CI 配置的完整骨架：

配置文件	对应 Evergreen 项目	职责
etc/evergreen_yml_components/**.yml	全部	存放任务、函数、构建变体等定义的 YAML 组件，由原evergreen.yml拆分而来
etc/evergreen.yml	mongodb-mongo-master	导入组件，包含全部开发用构建变体
etc/evergreen_nightly.yml	mongodb-mongo-master-nightly	仅含公开 nightly 构建变体，导入与evergreen.yml相似的组件以保持一致
etc/system_perf.yml	sys_perf	系统性能项目的配置

3.1etc/evergreen_yml_components：组件化拆分

etc/evergreen_yml_components目录存放从原evergreen.yml中拆分出来的 YAML 组件，涵盖任务定义、函数定义、构建变体定义等。这些组件文件通过 Evergreen 的include特性被合并进顶层配置文件。

从仓库引用看（etc/evergreen.yml 与 etc/evergreen_nightly.yml），组件按功能目录组织：

• configuration.yml、definitions.yml：基础配置与公共定义；
• tasks/compile_tasks*.yml：编译类任务；
• tasks/resmoke/...：按服务团队划分的 resmoke 测试任务（如clusters_and_integrations、durable_transactions_and_availability、query、non_server_teams）；
• tasks/misc_tasks.yml、tasks/security_tasks.yml、tasks/coverity_tasks.yml、tasks/release_tasks.yml：杂项、安全、静态分析、发布任务；
• variants/<平台>/test_dev.yml/test_release.yml：按平台（amazon、macos、rhel、ubuntu、windows、debian、ibm、suse 等）或变体分组（sanitizer、mongot、codecoverage、wiredtiger、coverity、release）组织的构建变体定义；
• custom_builds/：自定义构建的任务与变体；
• copybara/copybara.yml：与外部仓库同步的 copybara 相关配置。

需要说明的是：该目录在当前开源仓库快照中并未直接检出（其内容由 MongoDB 内部同步机制维护，仓库中的buildscripts/tests/test_sync_repo_with_copybara.py会校验相关文件的同步规则），但其文件名与路径在 etc/evergreen.yml 和 etc/evergreen_nightly.yml 中被大量include引用，读者可据此还原完整的组件树。变体文件的组织约定详见 buildvariants.md。

3.2etc/evergreen.yml：master 项目配置

etc/evergreen.yml是mongodb-mongo-master的项目配置，其头部注释详尽说明了本仓库的 YAML 编写约定（etc/evergreen.yml）：

Expansions（变量展开）机制

Expansions 通常写作${key|default}形式：若执行器（executor）的展开变量映射中存在key，则使用对应值；否则使用default。任意 expansions 可在以下字段中定义：

• expansions字段（针对 buildvariant，位于分支文件中）；
• expansions字段（针对 distro，位于 distros 文件中）。

此外还有一批内置 expansions 可用，包括：

• 宿主机上的环境变量；
• workdir：执行器的工作目录；
• task_id：执行器正在处理的任务 ID；
• build_variant：正在执行任务的构建变体名；
• config_root：执行器配置产物的根目录。

新任务的环境搭建

文件注释给出了两类新任务环境搭建的标准函数调用序列：

1. 若任务依赖archive_dist_test/archive_dist_test_debug任务，可直接调用"do setup"函数；或者按序调用fetch artifacts→f_expansions_write→kill processes→cleanup environment→set up venv；
2. 若任务不依赖上述归档任务，则按序执行manifest.load→git get shallow project（克隆完整 mongo 与 enterprise 仓库）→restore git history and tags→f_expansions_write→kill processes→cleanup environment→set up venv。

include 组件引用

主配置通过include逐项导入组件文件（etc/evergreen.yml），涵盖基础定义、编译任务、resmoke 任务、各平台开发变体、Atlas 模块配置（src/mongo/db/modules/atlas/atlas_dev.yml等）、copybara 配置以及 monguard 安全配置（monguard/.evergreen/...）。

parameters（参数）

evergreen.yml声明了一批参数（etc/evergreen.yml），例如：

• evergreen_config_file_path：值为"etc/evergreen.yml"，指向本文件路径；
• test_selection_strategies_array：测试选择策略数组；
• use_tss_staging：置为 true 时使用 staging 测试选择部署；
• runtime_params_json：基准测试任务的运行时参数 JSON，例如{"enable_linux_perf":true}用于开启 on-CPU profiling；
• antithesis_suites：逗号分隔的 ds-antithesis 套件任务，用于针对该 patch 的 mongod 镜像运行；为空或未设置则不触发；
• message_filter_plugin_release_version：message filter 插件的 dev 版本字符串，形如YYYYMMDD.hhmmss.<githash>，用于 GA 推广。

Aliases（别名）

• commit_queue_aliases（etc/evergreen.yml）：定义提交队列变体上运行的匹配任务，如commit-queue变体匹配bazel_.*、run_.*、unit_test.*、compile_.*、lint_.*、resmoke_tests等任务；
• github_pr_aliases（etc/evergreen.yml）：GitHub PR 触发的别名，结构与提交队列相似；
• patch_aliases（etc/evergreen.yml）：patch 验证别名，例如：
  • required：通过variant_tags: ["required"]选择所有必需变体；
  • query、query-quick、query-joo、security：按变体正则选择对应的 patch-only 变体；
  • bazel/bazel_variants：运行 Bazel 构建系统测试；
  • search：运行所有$search、$vectorSearch相关测试；
  • required-and-mongot-e2e-tests：选择所有必需变体 + 使用真实 mongot 的变体中的任务；
  • codecoverage/unittestcoverage：代码覆盖率任务；
  • disagg：从每个必需变体中提取 DSC（disaggregated）测试，是required的严格子集。

3.3etc/evergreen_nightly.yml：nightly 项目配置

etc/evergreen_nightly.yml用于 release 构建（etc/evergreen_nightly.yml）。它与evergreen.yml导入相似的组件以确保一致性，但存在明显差异：

• 发布组件：额外导入tasks/compile_tasks_nightly.yml、tasks/coverity_tasks.yml、variants/coverity.yml、tasks/release_tasks.yml、custom_builds/、Atlas 发布配置src/mongo/db/modules/atlas/atlas_release.yml；
• 平台差异：使用各平台的test_release.yml（amazon、debian、ibm、macos、rhel、suse、ubuntu、windows），而非test_dev.yml；
• 开发组件被注释：variants/misc/misc.yml、各平台test_dev.yml、sanitizer/test_dev.yml、mongot/test_dev.yml、variants/release/release.yml等均以注释形式保留，并标注 "Uncomment when using this file for a release branch."——即发布分支（release branch）场景下按需取消注释；
• 参数与别名：声明evergreen_config_file_path = "etc/evergreen_nightly.yml"，并定义了coverity_scan、release_smoke_test（匹配crypt_create_lib|package|test_packages|jscore）、blocking-emergency-atlas-release-tasks（通过variant_tags: ["emergency_release"]）等发布相关别名。

3.4etc/system_perf.yml：性能项目配置

sys_perf项目的配置非常轻量（etc/system_perf.yml）：

• modules：声明依赖 DSI 模块（owner: 10gen、repo: dsi、prefix: ${workdir}/src、branch: master）；
• include：导入 DSI 仓库内的性能配置组件，如evergreen/system_perf/master/base.yml、compiles.yml、compiles_pgo.yml、variants.yml、master_variants.yml、shared_tasks.yml。

值得注意的是，文件中的lint_yaml trim start/end注释说明：这些引用 DSI 仓库的行会被yamllinters.sh裁剪，以便evergreen evaluate能对非 DSI 的导入继续工作（详见 buildscripts/yamllinters.py）。同时，etc/evergreen_yml_components/variants下的部分变体文件也可能被复用合并进system_perf.yml。

四、配置的校验、lint 与评估

MongoDB 的 Evergreen 配置并非直接裸奔上线，而是有完整的校验链路：

4.1evergreen evaluate预处理

buildscripts/ciconfig/evergreen.py中的parse_evergreen_file会调用evergreen evaluate <path>命令预处理项目配置文件（evergreen.py）：该命令负责展开include与 expansions，将组件合并为完整的最终配置，随后加载为EvergreenProjectConfig实例供 CI 工具链使用。evergreen可执行文件可通过环境变量或默认位置发现，若找不到会抛出EnvironmentError。

4.2 Evergreen lint 规则

仓库提供了 etc/evergreen_lint.yml 定义配置 lint 规则，作用于evaluated_evergreen.yml与evaluated_evergreen_nightly.yml两个评估产物，代表性规则包括：

• limit-keyval-inc：限制 YAML 中keyval.inc命令的数量（上限 5）；
• no-working-dir-on-shell：禁止在 shell 任务中使用working_dir参数（要求先 sourceprelude.sh且位于${workdir}）；
• no-multiline-expansions-update：禁止多行expansions.update；
• invalid-build-parameter：要求参数名匹配[a-z][a-z0-9_]*且必须有非空描述，防止未经文档化的构建参数泛滥；
• required-expansions-write：要求evergreen/*.sh脚本调用expansions.write，避免 prelude.sh 加载过期的 expansions。

补充：etc/evergreen_lint.yml中的files路径相对配置文件所在目录，lint 的完整执行流程可参考 buildscripts/lint_yaml.sh 等脚本。

五、发布分支流程（Release Branching Process）

关联文档明确规定了 MongoDB 发布分支时 Evergreen 项目的变体取舍原则：

1. 仅mongodb-mongo-master-nightly项目随发布分支分支，并加回必需变体及其他必要变体（如 sanitizers）；
2. mongodb-mongo-master中的大多数变体默认被丢弃，但可根据需要手动将个别变体重新引入发布分支；
3. 对于 Rapid releases（快速发布），mongodb-mongo-master-nightly中除与 Atlas 相关的变体外，其余变体也可能一并丢弃。

这一策略在配置文件层面有直观的落地体现：etc/evergreen_nightly.yml 中所有开发专用组件（test_dev.yml、misc.yml、sanitizer/test_dev.yml、mongot/test_dev.yml、variants/release/release.yml）都被注释，并明确标注 "Uncomment when using this file for a release branch."（使用本文件作为发布分支配置时取消注释）；而 buildvariants.md 中的变体文件约定表进一步细化了分支前后的行为：

YAML 文件	运行位置	master 项目与 YAML	release 项目与 YAML
test_dev.yml	master + releases	mongodb-mongo-master/evergreen.yml	mongodb-mongo-vX.Y/evergreen_nightly.yml
test_dev_master_branch_only.yml	仅 master	mongodb-mongo-master/evergreen.yml	不使用
test_release.yml	master + releases	mongodb-mongo-master-nightly/evergreen_nightly.yml	mongodb-mongo-vX.Y/evergreen_nightly.yml
test_release_master_branch_only.yml	仅 master	mongodb-mongo-master-nightly/evergreen_nightly.yml	注释掉

由此可以推断：分支时实际发生的是——以evergreen_nightly.yml为基础，按需取消注释（加回 sanitizer、release 等必要变体）并启用test_release.yml系列文件，从而生成mongodb-mongo-vX.Y项目的配置；而mongodb-mongo-master的开发变体则不再跟随分支。

六、构建变体补充知识

为了理解上述配置文件中的变体语义，这里补充关联系列文档 buildvariants.md 中的关键约定：

• 必需变体（Required）：display name 前带!的构建变体，同时带有requiredtag，对应补丁构建必需策略；
• 建议变体（Suggested）：display name 前带*的构建变体，同时带有suggestedtag；
• forbid_tasks_tagged_with_experimentaltag：带此 tag 的构建变体不允许运行标记为experimental的任务，该限制由forbid-tasks-with-tag-on-variantsEvergreen lint 规则强制执行；
• 变体文件组织：etc/evergreen_yml_components/variants下的子目录多为平台名（amazon、rhel 等）或变体分组名（sanitizer 等），部分文件可被sys_perf项目复用。

七、延伸阅读

• Evergreen 测试总览
• 构建变体详解
• 任务所有权标签
• 任务选择标签
• 任务生成机制
• resmoke 套件的 Bazel 执行
• 配置评估工具链源码

【免费下载链接】mongoThe MongoDB Database项目地址: https://gitcode.com/GitHub_Trending/mo/mongo