mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-08 19:06:15 -08:00
74 lines
8.8 KiB
Markdown
74 lines
8.8 KiB
Markdown
# GitHub CI/CD 优化与验收
|
||
|
||
2026-09-10 用户明确要求在本次重构中优化和增强 GitHub CI/CD。范围包含仓库检查、测试矩阵、构建产物、文档站部署和 npm 发布准备，并持续维护脚本文档及故障处理指南。ENG-02 已实现初步检查与部署隔离，CI-01 已扩展系统矩阵、下载缓存、失败报告与稳定 CI result，操作见 [ci-setup.md](ci-setup.md)。CI-01 仍在进行：最低 Node 消费环境、全生态安装组合和影响调度尚未完成；CI-04 远端验收仍缺证据。
|
||
|
||
## ENG-02 前源码基线
|
||
|
||
[nodejs.yml](../.github/workflows/nodejs.yml) 曾是唯一 workflow：仅 push master 触发，Ubuntu + Node 20.x，checkout/setup-node 使用 v2；单一 job 执行 yarn 安装、两组 Node 测试、lint 和 build:all，再提交 docs、subtree split 并 force push gh-pages。
|
||
|
||
改造前 [package.json](../package.json) 中 lint 使用 --fix，build:all 又包含 lint；当前 workflow 没有 PR 触发、真实浏览器矩阵、类型消费者/tarball 检查、显式权限、并发取消、超时或报告上传。上述是文件检查结果，尚未核对 GitHub 的实际历史运行、Pages 配置、分支保护、环境规则或 npm 账号配置。旧流程的部署目标与访问路径必须先核实，不能仅改 YAML 就宣称迁移完成。
|
||
|
||
## 目标流水线
|
||
|
||
CI-02的本地Pages产物链已实现：build后在独立目录更新全部旧开发入口，验证路径/
|
||
域名/分发一致性并检查暂存播放，然后上传准确输出。只读远端配置快照、迁移与恢复
|
||
顺序见[Pages记录](pages-deployment.md)；实际部署仍待CI-04和明确授权。
|
||
|
||
| 流程 | 触发和范围 | 交付/门槛 |
|
||
| --- | --- | --- |
|
||
| PR 和主线 CI | PR、主线及重构分支的相关提交；支持人工重跑 | 固定安装、只读 lint、类型、单元/生命周期、影响范围内的浏览器和产物测试、计划/文档检查 |
|
||
| 完整兼容回归 | 共享核心/构建变更、候选准备、定期或手动执行 | 全生态构建、新旧组合、所需 Node/TS/浏览器/系统矩阵、docs 编辑器及 HTML、性能/资源证据 |
|
||
| 候选产物准备 | 明确源码 ref 与包/版本范围的手动或受控调用 | 构建、pack、隔离消费者、完整性清单及报告；不发布 npm |
|
||
| 文档站部署 | 仅受信任主线或明确发布操作，依赖对应 CI | 部署已验证 Pages artifact，保留域名/CNAME、旧 URL、语言页和 compiled 路径，发布后探测 |
|
||
| npm 候选/正式发布 | 明确包批次、registry、版本、tag 和已批准的候选内容 | 三轮复盘与真实环境门槛通过后发布准确 tarball，读回版本/integrity并记录回退 |
|
||
|
||
ENG-02 先建立只读 PR 检查和部署隔离框架，后续 CI 任务逐步接入已完成的测试基础；不能等全套回归齐备才给 PR 加基础检查。定期 workflow 是拟实现仓库能力，本文不创建 Codex 定时任务，也不即时启用远程作业。
|
||
|
||
## CI 的可靠性与运行成本
|
||
|
||
- Node/TS/包管理器版本来自 ENG-01/ENG-PM-01 和 BASE-08；用户指定 Yarn 为包管理器，Bun 仅隔离评估。最低消费者兼容与构建所需运行时分别验证，不因 Actions 升级静默提高消费者要求。
|
||
- 覆盖 Linux 与 Windows 的关键脚本；浏览器覆盖 Chromium/Firefox/WebKit 和有需要的正式 Chrome。真机、Cast 等证据仍使用环境矩阵，不将 hosted runner 通过当作真机通过。
|
||
- 安装使用选定包管理器的锁定模式；缓存按 OS、运行时、包管理器及锁文件隔离，浏览器缓存还绑定测试工具版本。禁止无关 PR 缓存/产物进入有发布权限的任务。
|
||
- 快速检查依据依赖图而非简单路径过滤；共享核心/构建/锁文件变化扩大检查，影响不确定时完整回归。文档单改可缩小范围，但 required 汇总检查必须给出真实结果，不能将失败/取消误报成功或留下永久 pending。
|
||
- PR 同分支的新提交取消过期检查；发布与部署按目标串行，不能取消一半已发生写入的发布。设置任务超时、合理并行/分片和报告保留期，避免重复 build:all 或重复 lint。
|
||
- 只读检查不改源码；显式构建在指定输出目录生成产物。记录生成漂移，确保 build/test 不包含提交、推送或部署副作用。
|
||
- 报告包含 commit、运行链接、工具版本、测试计数/跳过/重试、逐包结果、覆盖率、大小和性能；失败也上传可获得的日志、截图和 trace。大媒体/录像不提交源码，报告避免凭据泄露。
|
||
- YAML/actionlint 等静态检查与真实 Actions 执行分别留证。至少演练正常 PR、失败测试、文档单改、核心变更及发布 dry run；旧问题按 ENG-10 台账处理，不用 continue-on-error 掩盖发布相关失败。
|
||
|
||
## 权限和第三方 Actions
|
||
|
||
普通 CI 默认只读 contents，fork PR 不获取发布 secrets；不使用有写权限的 pull_request_target 执行外部 PR 代码。部署/发布权限仅授予相应 job。固定第三方 Actions 的完整提交 SHA 并注释版本，建立可审阅的升级流程，具体版本在实施时验证 runner 兼容性。GitHub 建议参见 [安全使用参考](https://docs.github.com/en/actions/reference/security/secure-use)。
|
||
|
||
required checks、环境审批、Pages source、npm trusted publisher 等是外部配置：记录现状、目标、所需权限和完成证据。仓库代码可先实现并提交；缺少远端配置时不得声称已启用发布能力。工作流配置优化不等于本次已经授权推送、部署或 publish；按已有发布授权规则操作，不重复询问常规本地修改。
|
||
|
||
## Pages 与 npm 分发
|
||
|
||
Pages 优先评估官方 artifact 部署流程，替代 CI 内提交/force push gh-pages 的耦合；先核对当前站点来源、域名、静态目录及保留文件，迁移前准备恢复旧部署方式的步骤。具体权限及 artifact 约束依据 [GitHub Pages workflow 文档](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)。尚未迁移远端设置时，旧站点仍须可恢复。
|
||
|
||
npm 保持 Lerna independent 的分包版本；用户已要求全部包分别升级到自身下一个大版本，按 [版本策略](version-policy.md) 校验版本清单，不把所有包统一为核心版本。优先评估 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) 的 OIDC 和 provenance；逐包核对支持环境、CLI 版本及信任配置，不能因支持 OIDC 就假定本仓库已配置。发布 CLI 环境要求不自动改变消费者最低 Node 要求。
|
||
|
||
发布只接收明确受信任来源的候选 artifact，并核对源码 SHA、workflow run、包/版本/registry/tag 和 tarball integrity。不能执行任意外部 URL 提供的代码或仅凭 artifact 名称信任内容。避免发布阶段生命周期脚本悄悄重建包；若内容改变，重新验证。dry run 不能证明 npm 权限、OIDC 或真实发布成功。
|
||
|
||
重跑发布先读 registry：相同版本存在时核对 integrity；内容不符则停止，禁止覆盖或默认 unpublish。分包发布部分成功时记录已成功包、失败包及 tag 状态，按兼容依赖顺序恢复；不盲目重发全部。候选 tag 升为正式前重核 REVIEW 和反馈修复证据。发布/部署后分别验证 npm 安装与站点关键路径，并记录分包/tag/站点回退方案。
|
||
|
||
## 任务归属
|
||
|
||
CI-NPM-01 从 CI-03 拆出本地精确候选交付准备，供后续 artifact 工作流复用。
|
||
`yarn release:bundle --packages ... --tag next` 只复制严格准入已通过的登记 tarball，
|
||
保留 publicationAuthorized=false。Git 必须干净，复制前后状态和文件哈希必须一致。
|
||
它不构建、安装或发布，也不证明 artifact 来源可信；CI-03 原依赖和远端/发布
|
||
验收全部保留。当前包仍被准入门槛阻止，详见[记录](changes/2026-09-15-CI-NPM-01-bundle.md)
|
||
及[实现维护](../scripts/release/README.md)。
|
||
|
||
| 任务 | 交付 |
|
||
| --- | --- |
|
||
| ENG-02 | 只读脚本、PR/主线检查及部署隔离基础 |
|
||
| ENG-05/07/08/09/10 | 浏览器、tarball、覆盖/性能、影响图、历史失败的可调用检查 |
|
||
| CI-01 | 完整回归矩阵、缓存/并发/超时、稳定汇总检查和持久报告 |
|
||
| CI-02 | Pages artifact 部署配置、路径保留、预检和恢复指南；远端切换状态明确 |
|
||
| CI-03 | npm 分包候选准备/发布工作流、信任配置清单、artifact 校验及部分失败恢复 |
|
||
| CI-04 | 流水线静态/干净环境/真实 PR 检查证据、dry run 与远端准入状态验收 |
|
||
| REVIEW-03、REL-05/06 | 发布前核对 CI-04；实际发布和部署按明确授权执行，读回真实结果 |
|
||
|
||
CI-04 的仓库实现与远端配置证据分别报告。真实运行或必要配置尚未核实则该验收保持未完成，仍可继续其他独立本地任务；第三轮“发布就绪”不能绕过此缺口。
|