GitHub Actions CI performance

GitHub Actions CI performance 表示把 CI 当作一个由触发器、DAG、runner 准备、编译、fixture、测试层级、产物传递和质量门禁共同组成的系统来优化。它同时追求可重复降低开发者等待的 required wall-clock / critical path，以及在同等完整 workload 下不增加 runner total、run/job 数、无必要的 cache/artifact 字节和 retention；速度收益必须与测试意图、真实运行边界和失败传播保持等价（projects/codex-vibe-monitor.md、docs/solutions/performance/github-actions-ci-performance-optimization.md）。

这个 Topic 不是“把更多 job 并行起来”，也不是某次 Actions run 的 benchmark 或固定 SLA。它要求维护者能解释候选改变了哪段关键路径、复用了哪份不可变输入、保留了哪些真实环境证据，以及失败时 required gate 如何仍然 fail-closed。GitHub Actions scheduling 专门解释事件、concurrency 和取消；Quality gates 专门解释 required-check / merge contract；本 Topic 连接两者与测试、缓存、fixture 的性能实验，但不替代它们（skills/style-playbook/references/topics/github-actions-scheduling/TOPIC.md、skills/style-playbook/references/topics/quality-gates/TOPIC.md）。

当改动会影响 .github/workflows/*.yml 的 needs、producer/consumer、并行或分片、runner/worker、cache、artifact、fixture、Playwright 与 Vitest 的层级、Stateful SQLite 测试、path filter、run class、concurrency 或 aggregate gate 时使用。也适用于需要解释“墙钟变短但总工作是否增加”的 CI 诊断、A/B 实验和性能回归评审（docs/solutions/performance/github-actions-ci-performance-optimization.md）。

不应仅因为仓库有 GitHub Actions、某个测试函数变慢，或某次 warm-cache run 变快就命中。若问题只涉及事件取消或 required check 可见性，先使用 GitHub Actions scheduling；若问题只涉及检查是否 required、签名或分支保护，先使用 Quality gates；若只是新增浏览器测试或 SQLite persistence contract，则分别使用 Playwright e2e / SQLite，只有在它们被纳入 CI 拓扑和成本实验时才叠加本 Topic（skills/style-playbook/references/topics/playwright-e2e/TOPIC.md、skills/style-playbook/references/topics/sqlite/TOPIC.md）。

• 先固定双指标和比较口径。 至少记录同一 base SHA / head SHA、run class、workflow、runner、工具链、浏览器版本、cold/warm/partial cache 状态和完整适用 workload。用 required_wall_clock = required_gate_end - first_applicable_required_start、critical_path = longest effective dependency chain、runner_total = sum(applicable job wall time) 解释结果；wall-clock 变短但 runner_total 增加时，候选不通过。不要把 hosted runner 的单次波动写成 SLA 或固定节省秒数（docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• 把 DAG 设计成 Producer-Consumer-Gate。 Classifier 先决定 run class、变更域和适用 workload；Producer 在固定 SHA 上生成完整、不可变、可校验的输入；Consumer 只下载并消费必要输入，不能重复编译或重复 fixture；aggregate Gate 使用 needs 和 if: always() 观察所有适用结果，但必须把 producer/consumer 的 failed、cancelled、missing 或意外 skipped 显式判为失败。always() 只保证 gate 有机会观察上游，不是无条件成功（docs/solutions/performance/github-actions-ci-performance-optimization.md、.github/scripts/check_quality_gates_contract.py）。
• 并行和分片按资源与语义切。 没有真实共享输入的 lint、frontend、docs/demo 和 backend producer 可以并行；共享 archive 或 fixture 的 consumer 应复用同一 producer。分片前记录分片键、测试意图、线程、连接、临时空间、文件和 aggregate 规则；Stateful SQLite、Archive/File I/O 和 Playwright 不能只按测试数量平均切片，因为锁、文件、server readiness 和 deadline 可能决定真实成本（docs/solutions/performance/github-actions-ci-performance-optimization.md、.github/workflows/ci-pr.yml）。
• 把 cache、artifact 和诊断附件分成不同边界。 可由 source key 重建的依赖或编译输入优先作为 cache；需要在同一 run 中精确交接的不可变 binary、archive、bundle 或报告才作为 artifact；失败诊断只保留定位所需的日志、trace、screenshot 或 video。上传前写清消费者、身份和生命周期，成功路径不要长期上传完整 workspace、node_modules、浏览器安装目录或没有消费者的文件，retention 取满足交接、诊断和审计的最短期限（docs/solutions/performance/github-actions-ci-performance-optimization.md、.github/workflows/docs-pages.yml）。
• 按 run class 设计触发和 concurrency。 PR candidate 可以只取消同一 PR 的旧候选；merge_group、main、release 和完整诊断要有独立 namespace，不能被普通 PR 规则误取消。path filter 只能减少已证明不适用的 workload，不能让 required check 长期缺失或 pending；workflow、质量门禁、共享 fixture、构建输入和真实浏览器/数据库边界改动默认走完整验证。pull_request、merge_group、main push 和 workflow_dispatch 的行为要用代表性矩阵复核（.github/workflows/ci-pr.yml、.github/workflows/ci-main.yml、docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• 按测试意图选择层级，不以删测换速度。 纯函数、序列化、状态机、React 状态和 DOM 语义优先使用 Vitest/jsdom；viewport、CSS geometry、scroll、focus、keyboard/touch、真实 route、导航、SSE、网络失败、Service Worker 或 PWA runtime 仍保留真实 Playwright。Stateful SQLite fixture 可以用 current-schema template/backup 减少重复 setup，但不能替代 migration、真实文件、连接池、锁、权限、archive、跨进程恢复和正式 deadline；这些边界仍由真实文件或 contention fixture 证明（docs/solutions/performance/github-actions-ci-performance-optimization.md、skills/style-playbook/references/topics/playwright-e2e/TOPIC.md、skills/style-playbook/references/topics/sqlite/TOPIC.md）。
• 用 A/B 实验而不是直觉收敛。 每次只改变一个主要变量：DAG 依赖、producer/consumer、cache key、线程/分片、fixture、测试层级或 trigger。分别覆盖 cold、warm、partial/miss cache、完整 workload、producer/consumer failure 和 trigger matrix；重要候选重复运行并报告中位数、离散范围、失败/重试和异常原因。新 head 会使旧 SHA 证据失效，实验必须重新绑定（docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• 把 Actions 消耗不增加设为硬门禁。 在同等 workload 上检查 run/job 数、runner_total、cache key/目录/次数/字节、artifact 数量/大小和 retention；不能通过更多 runner、无上限并行、重复 run、大附件、长 retention 或把工作偷偷转移到 Main/manual run 来换取墙钟收益。最低判断是 runner_delta <= 0，且 required checks、覆盖边界、失败传播和生产行为等价（docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• 让质量 gate 对失败和缺片 fail-closed。 Gate 必须有稳定 required check 名、输入 job、适用性以及 success、failure、cancelled、missing、skipped 的处理规则；不能用 continue-on-error、更窄 filter、增加 retry、降低 timeout/阈值或减少断言把回归藏起来。PR 描述至少携带候选边界、双指标、资源/传输对照、测试意图映射、producer/consumer/gate 传播和回退结论（.github/quality-gates.json、.github/scripts/check_quality_gates_contract.py、docs/solutions/performance/github-actions-ci-performance-optimization.md）。

• projects/codex-vibe-monitor.md：代表一个同时有 Rust backend、React/Playwright、SQLite、PR/main/release gates 和多个 workflow 的多交付面仓库；它说明 CI 性能不能只看单个测试命令，必须同时检查测试层级、真实 runtime 边界、required check 和 workflow scheduling。
• docs/solutions/performance/github-actions-ci-performance-optimization.md：这是本 Topic 的主要抽象来源，覆盖双指标、关键路径、Producer-Consumer-Gate、并行/分片、cache/artifact、run class、测试层级、Stateful SQLite、A/B 实验、失败传播和回退条件；Topic 保留这些跨项目规则，不复制其中的历史时间样本或一次性实现清单。
• .github/workflows/ci-pr.yml：代表 PR candidate 与 merge_group 的完整质量拓扑，包括 producer/consumer、backend profile、真实浏览器边界和 aggregate gate；适合审查共享输入是否被重复构建，以及 required 失败是否传播。
• .github/workflows/ci-main.yml：代表 merge 后 mainline 的完整 workload 与不受 PR cancellation 破坏的验证边界；它提醒维护者不要只优化 PR 等待时间而把同等工作转移到主干。
• .github/workflows/docs-pages.yml 与公开 PR #1232：代表通过去除重复 Docs Pages build、保留 main Pages 部署来减少重复工作，同时保持 PR/main 的触发和 concurrency 语义可解释；它不是通用的固定 workflow 模板。
• .github/quality-gates.json 与 .github/scripts/check_quality_gates_contract.py：代表把 workflow 拓扑、artifact/cache 边界和 fail-closed 检查写进 checked-in contract，避免性能重构只在 YAML 结构上“看起来更快”。

• 只看墙钟，不看 runner total。 把一个长 job 拆成多个 runner 可能让关键路径变短，却增加总工作、cache restore、artifact transfer 或失败面；必须在完整 workload 上比较两项指标，runner_delta > 0 时拒绝候选（docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• 用局部或 warm-cache 结果代表整个 CI。 单个 Vitest、Playwright、backend profile、producer step 或一次 cache hit 不能证明 whole-CI 优化；补做 cold/miss、完整 required workload、重复运行和失败路径，直到结果能绑定 SHA、run、attempt、workflow、runner 和候选变量（docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• Producer 不完整或 Consumer 偷偷重建。 半成品 artifact、缺少身份校验、重复编译/fixture 或把 producer 失败转成 consumer skipped，会同时浪费资源并掩盖回归；Producer 必须完整成功后上传，Consumer 先校验输入，Gate 显式检查每个适用结果（docs/solutions/performance/github-actions-ci-performance-optimization.md、.github/scripts/check_quality_gates_contract.py）。
• 把 always()、continue-on-error 或 retry 当成 gate。 always() 只负责观察上游；如果 gate 不检查 failed、cancelled、missing 和异常 skipped，上游失败可能显示绿色。受控 retry 只能处理有证据的瞬态基础设施故障，不能用来掩盖 flaky、锁竞争、超时或测试回归（docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• 混淆 cache、artifact 和诊断附件。 把完整 workspace、依赖目录、浏览器安装目录或成功 run 的大报告放进 artifact，会让 transfer 和 retention 抵消 wall-clock 收益；按消费者、可重建性、不可变身份和失败诊断需要重新划界，并删除没有消费者的文件（docs/solutions/performance/github-actions-ci-performance-optimization.md、.github/workflows/docs-pages.yml）。
• 触发器或 concurrency 优化造成重复 run、pending check 或错误取消。 用全局 group、把 merge_group/main/manual 混入 PR cancellation，或用 path filter 让 required check 消失，都会把性能问题变成质量门禁问题；逐一验证 PR、merge queue、main、手动诊断、文档-only、frontend-only、backend-only、workflow-only 和跨域矩阵（.github/workflows/ci-pr.yml、.github/workflows/ci-main.yml、skills/style-playbook/references/topics/github-actions-scheduling/TOPIC.md）。
• 盲目把真实边界下沉到轻量测试。 用 jsdom 替代 layout、focus、真实 navigation、SSE 或 PWA runtime，或用 current-schema SQLite template 替代 migration、文件、锁、权限和跨进程恢复，会让 CI 更快但失去原有证据；迁移必须维护“下沉的语义证据 + 保留的真实边界”映射（docs/solutions/performance/github-actions-ci-performance-optimization.md）。
• 用固定数字、账单叙事或一次合并结果夸大收益。 hosted runner 有波动，单次合并后 required checks 通过也不等于 runner total 有稳定改善；Topic 的硬约束是 Actions 消耗不增加，性能结论必须来自可重复对照，不把“降低账单”写成独立目标（docs/solutions/performance/github-actions-ci-performance-optimization.md、PR #1231）。
• 只改 workflow，不更新合同和回退路径。 没有质量脚本、required-check 名、artifact 消费者、失败传播和回退点的同步验证，后续维护者很容易重新引入重复工作或静默跳过；将 workflow、.github/quality-gates.json、合同检查和实验记录作为一个变更面审查（.github/quality-gates.json、.github/scripts/check_quality_gates_contract.py）。

• projects/codex-vibe-monitor.md
• docs/solutions/performance/github-actions-ci-performance-optimization.md
• .github/workflows/ci-pr.yml
• .github/workflows/ci-main.yml
• .github/workflows/docs-pages.yml
• .github/quality-gates.json
• .github/scripts/check_quality_gates_contract.py
• skills/style-playbook/references/topics/github-actions-scheduling/TOPIC.md
• skills/style-playbook/references/topics/quality-gates/TOPIC.md
• skills/style-playbook/references/topics/playwright-e2e/TOPIC.md
• skills/style-playbook/references/topics/sqlite/TOPIC.md
• PR #1231: document GitHub Actions performance strategy
• PR #1232: avoid redundant Docs Pages builds