MBE 文档中心

🔍 工作流失败排查指南

❌ 当前状态

工作流 "Complete CI/CD Pipeline" 已找到，但两次运行都失败了：

  • 工作流 #2: 失败（23秒）
  • 工作流 #1: 失败（20秒）

🔍 排查步骤

步骤1: 查看失败日志

  1. 点击失败的工作流

    • 点击 "Complete CI/CD Pipeline #2"（最新的失败运行）
    • 会跳转到详细的运行页面

  2. 查看失败的步骤

    • 页面会显示所有执行步骤
    • 找到标记为 ❌ 红色叉号的步骤
    • 点击失败的步骤查看详细错误日志

  3. 常见失败位置

    • Validate Code - 代码验证失败
    • Lint & Format - 代码格式检查失败
    • Tests - 测试失败
    • Build - 构建失败

步骤2: 常见错误类型

错误类型1: 缺少验证脚本

Error: python tools/dev-workspace/validate_monorepo.py
FileNotFoundError: [Errno 2] No such file or directory

原因: 工作流引用了不存在的验证脚本

解决方案:

  • 创建缺失的脚本文件
  • 或修改工作流，移除/注释掉这些步骤

错误类型2: 测试失败

FAILED tests/test_example.py::test_something
AssertionError: ...

原因: 代码测试未通过

解决方案:

  • 查看测试错误信息
  • 修复代码问题
  • 或临时跳过测试（仅紧急情况）

错误类型3: 代码格式问题

black: would reformat ...
flake8: E501 line too long

原因: 代码格式不符合规范

解决方案:

  • 运行格式化工具修复代码
  • 或调整格式检查规则

错误类型4: 缺少依赖

ModuleNotFoundError: No module named 'xxx'

原因: 缺少Python包或依赖

解决方案:

  • 检查requirements.txt
  • 确保所有依赖已安装

错误类型5: GitHub Secrets缺失

Error: Required secret 'XXX' is not set

原因: 缺少必需的GitHub Secrets

解决方案:

  • 检查GitHub Secrets配置
  • 添加缺失的Secrets

步骤3: 快速修复方案

方案1: 临时禁用验证步骤

如果验证脚本不存在，可以临时注释掉：

# - name: Validate Monorepo Structure
#   run: python tools/dev-workspace/validate_monorepo.py

# - name: Check Module Boundaries
#   run: python tools/dev-workspace/check_boundaries.py --public-only

方案2: 创建缺失的脚本

如果工作流需要验证脚本，创建它们：

# tools/dev-workspace/validate_monorepo.py
#!/usr/bin/env python3
"""简单的monorepo验证脚本"""
import sys
import os

def main():
    # 基本验证逻辑
    print("Monorepo validation passed")
    return 0

if __name__ == "__main__":
    sys.exit(main())

方案3: 跳过测试（仅紧急情况）

在触发工作流时：

  • 勾选 "Skip Tests (Emergency Only)" 选项
  • 这会跳过测试步骤，但其他步骤仍会执行

📋 详细排查清单

检查1: 查看工作流日志

  • 点击失败的工作流
  • 找到失败的步骤
  • 复制错误信息

检查2: 验证脚本存在性

  • tools/dev-workspace/validate_monorepo.py 是否存在？
  • tools/dev-workspace/check_boundaries.py 是否存在？
  • 如果不存在，是否需要创建或移除引用？

检查3: 代码质量

  • 代码是否能通过linter检查？
  • 代码格式是否符合规范？
  • 是否有语法错误？

检查4: 测试状态

  • 本地测试是否能通过？
  • 是否有失败的测试用例？

检查5: GitHub Secrets

  • 所有必需的Secrets是否已配置？
  • Secrets的值是否正确？

🛠️ 修复工作流

选项1: 修复代码问题

如果错误是代码问题：

  1. 查看错误日志
  2. 修复代码
  3. 提交并推送
  4. 重新触发工作流

选项2: 调整工作流配置

如果错误是工作流配置问题：

  1. 编辑 .github/workflows/complete-cicd.yml
  2. 修复配置问题
  3. 提交并推送
  4. 重新触发工作流

选项3: 创建缺失的脚本

如果缺少验证脚本：

  1. 创建必要的脚本文件
  2. 提交到仓库
  3. 重新触发工作流

🚀 重新触发工作流

修复问题后：

  1. 提交修复

    git add .
git commit -m "fix: resolve workflow failures"
git push origin master

  2. 手动触发

    • 访问工作流页面
    • 点击 "Run workflow"
    • 选择参数并运行

📚 相关文档

请先点击失败的工作流查看详细错误日志，然后告诉我具体的错误信息，我可以帮您精确修复！