必需状态检查是什么
必需状态检查（Status Checks）是分支保护的核心机制：把 CI 作业登记为必需检查后，目标分支的每次合并必须等这些检查全部通过，未通过时合并按钮保持禁用。落地要点有三：作业名即检查项标识，改名等于更换检查，保护规则会一直等一个不再出现的名字；被路径过滤（paths 等条件）跳过的作业不上报成功状态，登记为必需后提交会卡死在等待；与合并队列联用时，判定基于队列中合并后的临时结果，而不是各提交单独跑的结果。GitLab 的对应物是「合并请求流水线必须成功」等合并检查配置。
基本信息
| 配置位置 | 分支保护规则中勾选必需检查 |
|---|---|
| 命名 | 作业名是检查项标识，改名等于更换检查项 |
| 路径过滤 | 被过滤跳过的作业显示为等待状态 |
| 合并队列 | 与 merge queue 联用时按队列内结果判定 |
| strict 模式 | 要求分支先更新到最新再验证（up to date） |
典型使用场景
- 保护主干：main 只允许通过评审与检查的合并，其余入口一律关闭。
- monorepo 路径过滤：只对受影响目录跑重作业，用汇总作业化解与必需检查的冲突。
- 高并发仓库：配合合并队列串行验证「合并后」的组合状态，避免互相踩踏。
- 多工作流聚合：多个 workflow 的结论汇总到一个必过作业上，保护规则只面向它。
- 排查卡合并：提交长时间停在 Expected 时，先核对检查名与跳过原因，再查 Runner 队列。
- 准入类校验：把变更日志、版本号格式这类脚本检查也设为必需，规则面前人人平等。
设置必需检查
设置必需检查
gh api -X PUT repos/OWNER/REPO/branches/main/protection \
-f 'required_status_checks[strict]=true' \
-f 'required_status_checks[contexts][]=ci/test'
# 检查名要与作业名（含矩阵后缀）逐字一致检查状态读法
| 状态 | 含义 | 处理 |
|---|---|---|
| Expected/Waiting | 检查未上报，合并不放行 | 核对检查名、跳过条件与平台设置 |
| Success | 检查通过 | 可合并 |
| Failure/Error | 检查失败 | 修复后重跑；频繁失败查用例稳定性 |
| Queued | 排队等待 Runner | 扩容或减少并发占用 |
路径过滤与必需检查的冲突是经典事故：被跳过的作业不产生成功状态，提交卡在等待；把强制要求绑定到「总会运行」的汇总作业上。
矩阵作业会展开成多个检查项（带后缀），保护规则要么逐一勾选，要么让汇总作业去承载强制点。
合并队列会为每个入队变更生成临时合并结果并重跑检查，失败自动踢出并在变更上留言说明原因。