Mastra 仓库 GitHub Actions CI 失败修复实战从 gh pr checks 到全量验证的系统化排查流程【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南以 Mastra现代 TypeScript AI 应用与 Agent 框架仓库的.cursor/commands/gh-fix-ci.md命令为骨架面向在本地或 Agent 环境中接到当前分支关联 PR 的 CI 红了这一任务时的完整应对流程先用 GitHub CLI 定位 PR 与检查状态再对失败进行深度分类分析随后实施修复并用本地测试验证最后推回远端确认全部检查通过。读完本文你将掌握一套可复用的 CI 故障处置方法论并了解 Mastra 仓库真实 CI 拓扑Prebuild、Quality assurance、Changed Test Gate、E2E 等从而能快速判断一次失败到底是 flaky、真 bug 还是环境问题。预备知识先理解 Mastra 仓库的 CI 全景在动手修复之前先弄清楚失败的是什么检查比盲目看日志更高效。从源码结构看Mastra 是一个 pnpm turbo vitest 的大型 monorepo根目录package.json、pnpm-workspace.yaml、turbo.json、vitest.config.ts都在仓库根部其 CI 由.github/workflows/下数十个工作流文件组成。与日常 PR 最相关的几组是prebuild.ymlPR 触发opened / synchronize / reopened分支main、0.x先由changesjob 判断是否涉及代码再依次跑 Build、affected-tests 计算并根据路由结果调用 test-suite、e2e-tests、mastracode-e2e、combined-stores-tests、workspace-tests、memory-test 等下游工作流lint.yml名为 Quality assurance包含pnpm lint、check-bundle构建后校验产物是否被提交见.github/scripts/check-clean-worktree.bash、示例校验、AGENTS.md 校验、README 校验、peer 依赖校验scripts/validate-peerdeps.mjs与 package.json 校验等多个 jobtest-suite.yml以workflow_call方式被 prebuild 复用把单测拆成 4 个 shard 并行另含 affected 单测、按包分组的 E2E 与报告合并changed-test-gate.yml一个很有特点的突变门它把 PR 新增/修改的测试文件恢复到 base 分支上运行期望其失败以证明测试确实覆盖了新代码。这些工作流都通过 setup-pnpm-node 这个复合动作安装 Node.js 24.18.0 与 pnpm并带有 pnpm store 损坏自愈逻辑。知道这些后看到哪个 job 红了就能立刻联想到对应的职责范围。第一步定位 PR 并检查 CI 状态命令文档给出的起点非常明确先识别当前分支关联的 PR再看它的检查状态。gh pr status gh pr checks在非交互环境中例如 Agent 执行建议用GH_PAGERcat避免进入分页器导致命令挂起——这与仓库中同主题的.github/prompts/gh-fix-ci.prompt.md的写法一致GH_PAGERcat gh pr status GH_PAGERcat gh pr checksgh pr status会列出当前分支关联的 PR或提示当前分支没有关联 PR并给出每个 PR 的合并状态、检查概览与 review 状态gh pr checks会以清单形式列出该 PR 上的全部 CI 检查项及其结论pass / fail / pending是确定到底挂了哪些 job的最直接手段。拿到失败项列表后如果 PR 不在当前分支上也可以用gh pr checks PR_NUMBER仓库的.github/prompts/gh-bulk-issues.prompt.md中即有该用法显式指定 PR 编号。第二步深度分析失败——错误消息、模式与根因分类文档要求think deeply about the failures并给出了四个递进的分析动作。以 Mastra 仓库的实际 CI 为例逐条展开1. 分析错误消息与失败测试输出点击失败 job 展开日志按错误类型归类。仓库中最常见的几类失败形态测试断言失败vitest 输出会明确标出FAIL的测试文件与断言位置。这类失败大多对应真实行为变化是修复的主战场类型检查失败单测 job 同时运行--project unit:* --project typecheck:*见 test-suite.yml类型错误与运行期失败混在同一报告里需要在分析时先区分构建失败pnpm turbo build失败往往源于依赖图内的编译错误或产物不完整产物校验失败check-bundlejob 构建后执行check-clean-worktree.bash如果生成了未提交的产物文件CI 会直接失败——这类失败与测试逻辑无关属于忘记提交生成物依赖安装失败pnpm store 缓存损坏在自托管 runner 上是已知风险setup-pnpm-node 专门实现了自愈检测到 SQLite 索引损坏database disk image is malformed或内容哈希不匹配ERR_PNPM_MODIFIED_DEPENDENCY时只删除 store 索引、保留内容寻址文件必要时在 install 时追加--force。看到这类报错可以判断为环境/缓存问题而非代码问题。2. 识别跨失败的共同模式不要逐个 job 孤立地看而是横向扫描多个包同时失败且报错相似如同一依赖的导入路径错误通常指向共享代码或 monorepo 内依赖关系被破坏只有新增测试文件失败可能指向测试环境配置vitest config、fixtures缺失——changed-test-gate.yml 里专门有一段为 base 分支上的新包补回package.json/vitest.config.ts的逻辑正说明新包测试常因缺少支撑文件而失败失败集中在某个 shard可先怀疑该 shard 内的资源竞争或超时。3. 判断失败类型flaky、真 bug 还是环境问题这是整个流程中最关键的一步文档明确要求区分三类类型特征处置方向Flaky不稳定测试相同 commit 重跑有时过有时挂失败点常是网络请求、时间敏感断言、并发资源重跑确认必要时记录并单独修复测试本身而非改业务代码真 bug稳定复现、断言与实现预期确实不符修改业务代码或补正测试期望进入正式修复流程环境问题安装失败、store 缓存损坏、service 容器未就绪、runner 超时重跑或清理缓存一般无需改动代码判断 flaky 与真 bug 的最直接办法是在不改任何代码的前提下对同一 commit 重新触发一次 CI例如gh pr checks --watch或重新 push 空提交。若失败消失则高度怀疑 flaky。4. 制定系统性修复计划文档强调create a systematic plan to address each failure type。建议按先环境、后 flaky、再代码的优先级排序先重跑/清理环境类失败排除噪音再对 flaky 做复现确认最后集中火力处理真 bug并把相同根因的失败归并到同一次修复中避免边修边 push 造成 CI 反复排队。第三步实施修复——改动、本地验证与提交1. 做出必要的代码修改根据分析结果修改代码。Mastra 仓库的测试分布在packages/*、stores/*、workspaces/*、e2e-tests/*等目录不同位置的测试失败对应不同的源码模块。修改时注意只修与失败相关的代码不要顺手做无关重构以免扩大 CI 验证面。2. 在本地尽可能复现并验证文档要求 run tests locally if possible to verify fixes。Mastra 仓库提供了极有针对性的本地工具 scripts/affected-tests.mjs它先用 madge 构建全量模块图并反转成反向依赖索引再对每个变更的源文件做反向 BFS找出所有传递依赖到该文件的测试。典型用法# 显式指定变更的源文件找出受影响的测试 node scripts/affected-tests.mjs packages/core/src/storage/index.ts # 自动从 git diff 检测变更文件并直接交给 vitest 执行 node scripts/affected-tests.mjs --git | xargs pnpm vitest run # 输出结构化 JSONCI 中 prebuild.yml 使用的正是这个模式 node scripts/affected-tests.mjs --git --json支持--verbose展示依赖链、--symbol-aware按符号级依赖遍历 barrel 文件默认开启、--file-level回退到文件级遍历等选项。这与 CI 中prebuild.yml的 affected-tests job 使用的是同一套逻辑——本地跑通它就基本等价于在 CI 的最小验证面上跑通。对于大型测试CI 使用分片运行--shard${{ matrix.shard }}/4、blob 报告合并--reporterblob与--reportergithub-actions把失败直接渲染为 GitHub Actions 注解见 test-suite.yml。本地复现时可以只跑目标文件例如pnpm vitest run packages/memory/src/__tests__/xxx.test.ts如果失败源于 lint 或格式本地执行pnpm lint如果源于构建产物未提交本地执行pnpm turbo build后再确认工作区是否干净。3. 用清晰的提交信息提交全部改动提交信息应直接说明修了什么 CI 问题便于后续回溯。例如git add -A git commit -m fix(ci): resolve failing memory integration tests on pgvector service ... 从仓库现有的工作流命名fix(ci):风格在 Mastra 的 changeset 与提交实践中常见可以推断一条fix(ci): 具体失败项的提交信息最容易被维护者与自动化工具理解。若改动涉及对外发布行为版本号、依赖声明还需按仓库惯例补充.changeset否则peerdeps-check等 job 会检测到版本不一致而失败。第四步验证修复——推送并监控新的 CI 运行修复后的闭环是文档的最后一步push 并确认所有检查通过。git push origin branch gh pr checks --watch值得注意的几个 Mastra 特有验证点Changed Test Gate 会反着验证你的测试changed-test-gate.yml 会把新增测试放到 base 分支上运行并期望失败Changed tests failed against the base branch as expected。如果你新增的测试在 base 上居然通过了说明它没有真正覆盖新代码CI 会显式报错拦截。因此写测试时务必保证它确实依赖新实现Prebuild 的 fail-closed 设计prebuild.yml中如果 GitHub Compare API 调用失败或返回超过 300 个文件会保守地按有代码变更处理并跑全量构建prebuild.yml避免漏检路由决定验证范围不是每次 push 都会全量跑。affected-testsjob 会按变更文件计算受影响测试命中超过 50% 阈值才切到全量模式stores、workspaces、memory、mastracode、e2e 各有独立路由涉及pnpm-lock.yaml、e2e-tests/、packages/server/等路径时会强制触发对应 E2E见 prebuild.yml。所以确认哪些 job 被触发同样重要——如果改动文件本应触发某类测试但对应 job 没跑本身就是一种 CI 配置层面的异常。附一份可复用的 CI 修复检查清单综合以上流程收尾前逐项核对GH_PAGERcat gh pr status/gh pr checks确认失败 job 清单按错误消息 → 模式 → 根因分类flaky / bug / 环境完成分析环境类优先重跑排除用node scripts/affected-tests.mjs --git计算受影响测试并本地跑通需要时本地执行pnpm lint、pnpm turbo build验证非测试类检查以fix(ci):风格提交清晰的修复信息发布相关改动记得补 changesetpush 后用gh pr checks --watch监控确认本次触发的全部检查通过同时留意 Changed Test Gate 的新测试必须在 base 上失败这一反向约束。这套方法论直接来源于仓库内 .cursor/commands/gh-fix-ci.md 命令并被 .github/prompts/gh-fix-ci.prompt.md 以 Agent prompt 形式固化为可自动执行的流程。掌握它你就能在 Mastra 这样的复杂 monorepo 中把一次 CI 红变绿从试错变成可预期的系统工程。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Mastra 仓库 GitHub Actions CI 失败修复实战：从 gh pr checks 到全量验证的系统化排查流程
Mastra 仓库 GitHub Actions CI 失败修复实战从 gh pr checks 到全量验证的系统化排查流程【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本指南以 Mastra现代 TypeScript AI 应用与 Agent 框架仓库的.cursor/commands/gh-fix-ci.md命令为骨架面向在本地或 Agent 环境中接到当前分支关联 PR 的 CI 红了这一任务时的完整应对流程先用 GitHub CLI 定位 PR 与检查状态再对失败进行深度分类分析随后实施修复并用本地测试验证最后推回远端确认全部检查通过。读完本文你将掌握一套可复用的 CI 故障处置方法论并了解 Mastra 仓库真实 CI 拓扑Prebuild、Quality assurance、Changed Test Gate、E2E 等从而能快速判断一次失败到底是 flaky、真 bug 还是环境问题。预备知识先理解 Mastra 仓库的 CI 全景在动手修复之前先弄清楚失败的是什么检查比盲目看日志更高效。从源码结构看Mastra 是一个 pnpm turbo vitest 的大型 monorepo根目录package.json、pnpm-workspace.yaml、turbo.json、vitest.config.ts都在仓库根部其 CI 由.github/workflows/下数十个工作流文件组成。与日常 PR 最相关的几组是prebuild.ymlPR 触发opened / synchronize / reopened分支main、0.x先由changesjob 判断是否涉及代码再依次跑 Build、affected-tests 计算并根据路由结果调用 test-suite、e2e-tests、mastracode-e2e、combined-stores-tests、workspace-tests、memory-test 等下游工作流lint.yml名为 Quality assurance包含pnpm lint、check-bundle构建后校验产物是否被提交见.github/scripts/check-clean-worktree.bash、示例校验、AGENTS.md 校验、README 校验、peer 依赖校验scripts/validate-peerdeps.mjs与 package.json 校验等多个 jobtest-suite.yml以workflow_call方式被 prebuild 复用把单测拆成 4 个 shard 并行另含 affected 单测、按包分组的 E2E 与报告合并changed-test-gate.yml一个很有特点的突变门它把 PR 新增/修改的测试文件恢复到 base 分支上运行期望其失败以证明测试确实覆盖了新代码。这些工作流都通过 setup-pnpm-node 这个复合动作安装 Node.js 24.18.0 与 pnpm并带有 pnpm store 损坏自愈逻辑。知道这些后看到哪个 job 红了就能立刻联想到对应的职责范围。第一步定位 PR 并检查 CI 状态命令文档给出的起点非常明确先识别当前分支关联的 PR再看它的检查状态。gh pr status gh pr checks在非交互环境中例如 Agent 执行建议用GH_PAGERcat避免进入分页器导致命令挂起——这与仓库中同主题的.github/prompts/gh-fix-ci.prompt.md的写法一致GH_PAGERcat gh pr status GH_PAGERcat gh pr checksgh pr status会列出当前分支关联的 PR或提示当前分支没有关联 PR并给出每个 PR 的合并状态、检查概览与 review 状态gh pr checks会以清单形式列出该 PR 上的全部 CI 检查项及其结论pass / fail / pending是确定到底挂了哪些 job的最直接手段。拿到失败项列表后如果 PR 不在当前分支上也可以用gh pr checks PR_NUMBER仓库的.github/prompts/gh-bulk-issues.prompt.md中即有该用法显式指定 PR 编号。第二步深度分析失败——错误消息、模式与根因分类文档要求think deeply about the failures并给出了四个递进的分析动作。以 Mastra 仓库的实际 CI 为例逐条展开1. 分析错误消息与失败测试输出点击失败 job 展开日志按错误类型归类。仓库中最常见的几类失败形态测试断言失败vitest 输出会明确标出FAIL的测试文件与断言位置。这类失败大多对应真实行为变化是修复的主战场类型检查失败单测 job 同时运行--project unit:* --project typecheck:*见 test-suite.yml类型错误与运行期失败混在同一报告里需要在分析时先区分构建失败pnpm turbo build失败往往源于依赖图内的编译错误或产物不完整产物校验失败check-bundlejob 构建后执行check-clean-worktree.bash如果生成了未提交的产物文件CI 会直接失败——这类失败与测试逻辑无关属于忘记提交生成物依赖安装失败pnpm store 缓存损坏在自托管 runner 上是已知风险setup-pnpm-node 专门实现了自愈检测到 SQLite 索引损坏database disk image is malformed或内容哈希不匹配ERR_PNPM_MODIFIED_DEPENDENCY时只删除 store 索引、保留内容寻址文件必要时在 install 时追加--force。看到这类报错可以判断为环境/缓存问题而非代码问题。2. 识别跨失败的共同模式不要逐个 job 孤立地看而是横向扫描多个包同时失败且报错相似如同一依赖的导入路径错误通常指向共享代码或 monorepo 内依赖关系被破坏只有新增测试文件失败可能指向测试环境配置vitest config、fixtures缺失——changed-test-gate.yml 里专门有一段为 base 分支上的新包补回package.json/vitest.config.ts的逻辑正说明新包测试常因缺少支撑文件而失败失败集中在某个 shard可先怀疑该 shard 内的资源竞争或超时。3. 判断失败类型flaky、真 bug 还是环境问题这是整个流程中最关键的一步文档明确要求区分三类类型特征处置方向Flaky不稳定测试相同 commit 重跑有时过有时挂失败点常是网络请求、时间敏感断言、并发资源重跑确认必要时记录并单独修复测试本身而非改业务代码真 bug稳定复现、断言与实现预期确实不符修改业务代码或补正测试期望进入正式修复流程环境问题安装失败、store 缓存损坏、service 容器未就绪、runner 超时重跑或清理缓存一般无需改动代码判断 flaky 与真 bug 的最直接办法是在不改任何代码的前提下对同一 commit 重新触发一次 CI例如gh pr checks --watch或重新 push 空提交。若失败消失则高度怀疑 flaky。4. 制定系统性修复计划文档强调create a systematic plan to address each failure type。建议按先环境、后 flaky、再代码的优先级排序先重跑/清理环境类失败排除噪音再对 flaky 做复现确认最后集中火力处理真 bug并把相同根因的失败归并到同一次修复中避免边修边 push 造成 CI 反复排队。第三步实施修复——改动、本地验证与提交1. 做出必要的代码修改根据分析结果修改代码。Mastra 仓库的测试分布在packages/*、stores/*、workspaces/*、e2e-tests/*等目录不同位置的测试失败对应不同的源码模块。修改时注意只修与失败相关的代码不要顺手做无关重构以免扩大 CI 验证面。2. 在本地尽可能复现并验证文档要求 run tests locally if possible to verify fixes。Mastra 仓库提供了极有针对性的本地工具 scripts/affected-tests.mjs它先用 madge 构建全量模块图并反转成反向依赖索引再对每个变更的源文件做反向 BFS找出所有传递依赖到该文件的测试。典型用法# 显式指定变更的源文件找出受影响的测试 node scripts/affected-tests.mjs packages/core/src/storage/index.ts # 自动从 git diff 检测变更文件并直接交给 vitest 执行 node scripts/affected-tests.mjs --git | xargs pnpm vitest run # 输出结构化 JSONCI 中 prebuild.yml 使用的正是这个模式 node scripts/affected-tests.mjs --git --json支持--verbose展示依赖链、--symbol-aware按符号级依赖遍历 barrel 文件默认开启、--file-level回退到文件级遍历等选项。这与 CI 中prebuild.yml的 affected-tests job 使用的是同一套逻辑——本地跑通它就基本等价于在 CI 的最小验证面上跑通。对于大型测试CI 使用分片运行--shard${{ matrix.shard }}/4、blob 报告合并--reporterblob与--reportergithub-actions把失败直接渲染为 GitHub Actions 注解见 test-suite.yml。本地复现时可以只跑目标文件例如pnpm vitest run packages/memory/src/__tests__/xxx.test.ts如果失败源于 lint 或格式本地执行pnpm lint如果源于构建产物未提交本地执行pnpm turbo build后再确认工作区是否干净。3. 用清晰的提交信息提交全部改动提交信息应直接说明修了什么 CI 问题便于后续回溯。例如git add -A git commit -m fix(ci): resolve failing memory integration tests on pgvector service ... 从仓库现有的工作流命名fix(ci):风格在 Mastra 的 changeset 与提交实践中常见可以推断一条fix(ci): 具体失败项的提交信息最容易被维护者与自动化工具理解。若改动涉及对外发布行为版本号、依赖声明还需按仓库惯例补充.changeset否则peerdeps-check等 job 会检测到版本不一致而失败。第四步验证修复——推送并监控新的 CI 运行修复后的闭环是文档的最后一步push 并确认所有检查通过。git push origin branch gh pr checks --watch值得注意的几个 Mastra 特有验证点Changed Test Gate 会反着验证你的测试changed-test-gate.yml 会把新增测试放到 base 分支上运行并期望失败Changed tests failed against the base branch as expected。如果你新增的测试在 base 上居然通过了说明它没有真正覆盖新代码CI 会显式报错拦截。因此写测试时务必保证它确实依赖新实现Prebuild 的 fail-closed 设计prebuild.yml中如果 GitHub Compare API 调用失败或返回超过 300 个文件会保守地按有代码变更处理并跑全量构建prebuild.yml避免漏检路由决定验证范围不是每次 push 都会全量跑。affected-testsjob 会按变更文件计算受影响测试命中超过 50% 阈值才切到全量模式stores、workspaces、memory、mastracode、e2e 各有独立路由涉及pnpm-lock.yaml、e2e-tests/、packages/server/等路径时会强制触发对应 E2E见 prebuild.yml。所以确认哪些 job 被触发同样重要——如果改动文件本应触发某类测试但对应 job 没跑本身就是一种 CI 配置层面的异常。附一份可复用的 CI 修复检查清单综合以上流程收尾前逐项核对GH_PAGERcat gh pr status/gh pr checks确认失败 job 清单按错误消息 → 模式 → 根因分类flaky / bug / 环境完成分析环境类优先重跑排除用node scripts/affected-tests.mjs --git计算受影响测试并本地跑通需要时本地执行pnpm lint、pnpm turbo build验证非测试类检查以fix(ci):风格提交清晰的修复信息发布相关改动记得补 changesetpush 后用gh pr checks --watch监控确认本次触发的全部检查通过同时留意 Changed Test Gate 的新测试必须在 base 上失败这一反向约束。这套方法论直接来源于仓库内 .cursor/commands/gh-fix-ci.md 命令并被 .github/prompts/gh-fix-ci.prompt.md 以 Agent prompt 形式固化为可自动执行的流程。掌握它你就能在 Mastra 这样的复杂 monorepo 中把一次 CI 红变绿从试错变成可预期的系统工程。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考