企业官网建设流程全解析

IntelliJ Community 仓库 Safe Push 实战：通过 Patronus 工作流将变更推入 master

【免费下载链接】intellij-communityIntelliJ IDEA & IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community

本篇基于 intellij-community 仓库中面向 AI Agent 的技能文档 safe-push/SKILL.md，完整讲解 Safe Push 机制：如何在不打开 IDE 的情况下用safePush.cmd命令行把提交安全地推送到受保护分支，Patronus 机器人如何触发 CI 校验并自动重试失败用例，紧急推送（Emergency Push）的适用边界，以及 Bazel 测试中env_inherit环境变量的传递规则。读完本文，你可以在 JetBrains 内部开发流程中正确发起、监控、排障一次 Safe Push，并理解其底层工作流。

需要说明的适用前提：Safe Push 与 Patronus 是 JetBrains 团队用于守护master等受保护分支的合并门禁系统。当前开源快照中未包含safePush.cmd脚本本体、.patronus/配置目录以及文档中引用的docs/IntelliJ-Platform/2_Running-and-Testing/Safe-Push.md章节，因此下文的命令行与流程细节以 技能文档 的记载为准；仓库内可核实的配套证据（如 Bazel 配置与env_inherit用法）均标注了对应路径。

一、Safe Push 是什么：受保护分支的合并门禁

Safe Push 是一套确保代码变更在合入受保护分支（如master）之前必须通过所有必需测试的系统，其背后由 JetBrains 内部的Patronus平台驱动。它把“直接 push 到 master”这一高风险动作，替换为“推送给机器人代理校验，校验通过后自动合并”的受控流程。

从 技能文档 描述的工作流看，一次 Safe Push 的完整生命周期分为五个阶段：

1. 推送到临时分支：你的变更不会直接落到master，而是先被推到一个临时分支；
2. 触发 CI 检查：Patronus 根据配置触发必需的持续集成检查（测试、编译等）；
3. 失败自动重试：测试用例若出现不稳定（flaky）失败，Patronus 最多会自动重试4 次；
4. 全部通过后自动合并：所有检查通过后，变更才会被合并到目标分支；
5. 结果通知：你会通过 Slack / Space / Email 收到结果通知。

文档同时给出了耗时预期，这对计划合入窗口很重要：

也就是说，无论成功还是失败，一次 Safe Push 都是“小时级”的长任务，这也是后文“监控与托管”一节存在的原因。

二、Safe Push CLI：不依赖 IDE 的命令行入口

仓库根目录提供safePush.cmd脚本（该脚本未包含在当前开源快照中，以下用法依据 SKILL.md 记载），用于在纯命令行环境下发起 Safe Push，无需打开 IDE。

基本用法

# 把当前 HEAD 推送到 master（最常见） ./safePush.cmd HEAD:master # 把指定提交推送到 master ./safePush.cmd <commit-hash>:master # 在 feature 分支上发起，把 HEAD 推送到 master ./safePush.cmd HEAD:master # while on feature branch # 空跑：只跑测试，不实际推送 ./safePush.cmd -dry-run HEAD:master

参数格式为<来源>:<目标分支>，其中来源可以是HEAD或具体 commit hash。-dry-run适合在正式推送前验证本地变更能否通过检查，而不产生真实的合并副作用。

选项一览

其中-autosquash默认开启，意味着如果你按 Git 惯例用git commit --fixup+ rebase 组织提交，Safe Push 会自动把这些fixup!提交折叠进主提交，保持 master 历史整洁，无需手动 rebase。

三、进度监控：Patronus Robot 是唯一的“把手”

Safe Push 发起后，你会收到一个形如https://patronus.labs.jb.gg/robot/<uuid>的 Patronus URL。文档特别强调：必须把这个 URL 原样打印回给用户——它是这次运行的主要把手（primary handle），其中<uuid>段就是robot id，URL 上提供了分享链接、取消（Cancel）按钮和恢复分支（Restore Branch）按钮。取消与恢复分支这两个操作只在浏览器页面中进行，命令行不提供。

针对“长任务无人值守”的场景，文档给出了配套的 Agent 协作路径：

• 查询当前状态、枚举失败的检查项、深入某一次尝试（attempt）的细节、或长时间“看护”（babysit）一个正在运行的 robot 直到其结束，这些能力都在仓库技能体系中的patronus技能里（技能索引见 skills/INDEX.md）；
• 当用户询问运行状态时，或者 Safe Push 已经在跑、你主动提议帮忙跟踪时，应切换到该技能。文档指出主动提出跟踪或托管是合理的，用户可以拒绝；
• 如果需要深入检查某个具体的 TeamCity 构建，patronus技能还记录了向teamcity-cli技能的交接方式。

四、Emergency Push：明确的能力边界

-emergency选项可以跳过测试直接推送，文档用白名单 + 黑名单划定了它的使用边界，这是该文档中约束最严格的部分：

仅允许用于：

• 修复编译损坏（Fixing broken compilation）；
• 回滚破坏安装器（installers）的提交；
• 修复.patronus/config.yaml本身的配置错误。

明确禁止用于：

• 修正 Javadoc 错别字之类的小改动；
• Safe Push 因“看起来不相关”的测试失败时——文档直言这些测试“很可能是相关的”；
• 仅仅因为赶时间而跳过测试；
• 推送与并发推送存在冲突的大变更。

从这条规则可以看出设计取向：跳过测试是最后手段，而“失败测试与我的改动无关”是开发者最常见的自我开脱，文档直接堵死了这个口子。

五、Bazel 测试与环境变量：env_inherit规则

Safe Push 最终跑的是仓库的 Bazel 构建与测试，因此文档专门补充了一条测试编写约束：当测试会派生外部进程（例如bazel.cmd）时，必须显式传递必需的环境变量。

原因：Bazel 沙箱默认不会继承宿主机的环境变量。若测试内部又调用 Bazel（如嵌套构建），子进程拿不到HOME等变量，缓存目录无法定位，测试就会以看似随机的方式失败——这正是 CI 门禁里典型的“本地能过、远端挂掉”来源。

解决办法是在BUILD.bazel的java_test目标上声明env_inherit，文档给出的完整示例：

// In BUILD.bazel for java_test targets: env_inherit = [ "LOCALAPPDATA", // Windows "PROCESSOR_ARCHITECTURE", // Windows "USERPROFILE", // Windows "HOME", // Unix/macOS - required for bazel cache directory ],

四个变量中，LOCALAPPDATA、PROCESSOR_ARCHITECTURE、USERPROFILE是 Windows 平台所需，HOME是 Unix/macOS 上定位 Bazel 缓存目录所必需。

当前快照中可以找到这一用法的真实落地：build/plugin-descriptor-patcher/internal/stamps/BUILD.bazel 中就使用了env_inherit = ["IJ_DESCRIPTOR_CASES"]，印证了“沙箱内按变量名显式继承”是仓库的通行做法。被测试调用的入口脚本 bazel.cmd 位于仓库根目录，配套的 Bazel 配置见 common.bazelrc 与 .bazelrc。编写此类测试前，也建议对照 AGENTS.md 中“After Code Changes”的强制规则：变更后需运行./tests.cmd --module <module> --test <FQN or wildcard>验证受影响的测试——这条本地规则正是 Safe Push 远端门禁的本地镜像。

六、故障排查

文档归纳了三类常见问题与处置路径：

1. Safe Push 卡住或变慢

• 检查#ij-buildsSlack 频道，确认是否有基础设施问题；
• 耗时本身会随基础设施负载波动（对照第一节 3–5 小时的基线判断是否异常）。

2. 失败测试看似与你的改动无关

• 记住重试机制：Patronus 最多重试 4 次；
• 判定规则：如果测试4 次尝试全部失败，且在 master 上是通过的，那大概率就是你的改动导致的，不应归咎于环境；
• 怀疑基础设施问题时，上报到#ij-qa-watch频道。

3. 需要调试一次失败的 Safe Push

1. 在 Patronus 上打开你的 Safe Push 页面；
2. 点击 “commits” 查看本次变更内容；
3. 点击 “Restore Branch”，把变更恢复到本地——这就是临时分支机制的兜底：即使推送失败，你的工作也不会丢。

七、小结

Safe Push 用一条./safePush.cmd <来源>:master命令，把“推送—CI 校验—失败重试—自动合并—结果通知”串成了闭环：临时分支保护了master，4 次重试吸收了 flaky 噪音，Patronus robot URL 与浏览器端的 Cancel / Restore Branch 提供了人工干预通道，而 Emergency Push 被严格限制在修编译、回滚坏提交、修.patronus/config.yaml三类场景。对于在 JetBrains 内部流程中工作的开发者（或代表开发者操作的 AI Agent）而言，掌握这五步工作流、robot 监控方式和env_inherit测试约束，就具备了安全合入受保护分支的完整能力。

【免费下载链接】intellij-communityIntelliJ IDEA & IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community