8.2 KiB
8.2 KiB
在线调试工作流功能 - 实现指南
📋 功能概述
这个功能允许开发者在 Gitea 的 Web 界面中在线调试 GitHub Actions 工作流。用户可以：
- 输入或粘贴工作流 YAML 脚本
- 验证脚本语法
- 选择执行分支
- 立即执行工作流
- 查看完整执行日志和输出
🔧 API 使用方法
1. 提交调试工作流
请求：
POST /api/v1/repos/{owner}/{repo}/actions/debug-workflow
Content-Type: application/json
{
"workflow_content": "name: Debug Test\non: workflow_dispatch\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - run: echo 'Hello from debug workflow!'",
"ref": "main",
"inputs": {
"custom_input": "value"
}
}
响应：
{
"id": 123,
"title": "[DEBUG] Debug Test",
"status": "waiting",
"workflow_id": "debug-workflow.yml",
"ref": "main",
"commit_sha": "abc123...",
"created": "2025-11-14T10:00:00Z"
}
2. 获取调试工作流输出
请求：
GET /api/v1/repos/{owner}/{repo}/actions/debug-workflow/{run_id}
响应：
{
"run": {
"id": 123,
"title": "[DEBUG] Debug Test",
"status": "success",
"workflow_id": "debug-workflow.yml",
"logs": [...],
"created": "2025-11-14T10:00:00Z"
},
"workflow_content": "name: Debug Test\non: workflow_dispatch\n..."
}
💻 前端界面集成
建议在以下位置添加调试工作流界面：
位置 1: 仓库 Actions 页面
- 路由:
/repos/{owner}/{repo}/actions - 添加 "Debug Workflow" 标签页
- 显示工作流编辑器和执行按钮
位置 2: 工作流文件详情页面
- 当查看
.gitea/workflows/*.yml文件时 - 添加 "Run Debug Mode" 按钮
- 使用文件内容作为默认值
位置 3: Web UI 模板建议
<div id="workflow-debugger">
<!-- Workflow YAML Editor -->
<div class="workflow-editor">
<textarea id="workflow-content" placeholder="Paste your GitHub Actions workflow YAML here..."></textarea>
</div>
<!-- Options -->
<div class="debug-options">
<label>Select Branch: <select id="ref-select">...</select></label>
<label>Inputs: <textarea id="debug-inputs" placeholder="JSON format"></textarea></label>
</div>
<!-- Actions -->
<button id="validate-workflow">Validate</button>
<button id="run-workflow">Run Debug Workflow</button>
<!-- Output -->
<div id="debug-output" class="hidden">
<div class="logs-viewer">
<pre id="workflow-logs"></pre>
</div>
</div>
</div>
🔍 调试工作流的特殊标记
所有通过调试功能执行的工作流都会：
- WorkflowID: 设置为
debug-workflow.yml（特殊标记） - Title 前缀: 添加
[DEBUG]前缀 - Event: 设置为
workflow_dispatch - Status Tracking: 完整记录所有执行步骤
这使得用户可以轻松区分调试运行和正式运行。
📊 数据流
┌─────────────────────────────────────────────────────────────────────┐
│ 用户操作 │
│ 输入工作流 YAML + 参数 │
└──────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ API /debug-workflow │
│ POST /api/v1/repos/{owner}/{repo}/actions/debug-workflow │
└──────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ services/actions/debug_workflow.go │
│ DebugActionWorkflow() │
│ - 验证 YAML 内容 │
│ - 创建临时 ActionRun │
│ - 创建 ActionRunJob │
│ - 保存工作流内容 │
└──────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 工作流执行引擎 │
│ (现有的 Actions Runner) │
│ - 解析工作流 YAML │
│ - 创建 Jobs │
│ - 执行步骤 │
│ - 记录输出 │
└──────────────────────────┬──────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 查询运行结果 │
│ GET /api/v1/repos/{owner}/{repo}/actions/debug-workflow/{id} │
│ 返回: run 信息 + workflow_content + logs │
└─────────────────────────────────────────────────────────────────────┘
🔐 安全考虑
- 权限检查: 只有具有仓库写权限的用户可以执行调试工作流
- Actions 启用: 仓库必须启用 Actions 单元
- YAML 验证: 所有提交的 YAML 都必须通过解析验证
- 日志隔离: 调试工作流的日志单独存储和标记
- Token 限制: 调试工作流中的 token 应该有相同的限制
📝 日志输出
调试工作流的完整日志包括：
-
工作流启动日志
- 触发时间
- 执行用户
- 分支信息
-
每个 Job 的日志
- Job 名称和 ID
- 步骤执行情况
- 命令输出
- 错误信息
-
工作流完成日志
- 总执行时间
- 最终状态
- 任何错误总结
🚀 后续改进建议
-
工作流模板库
- 提供常用工作流模板
- 一键加载示例
-
语法高亮
- 在编辑器中支持 YAML 语法高亮
- 错误提示
-
步骤预览
- 显示工作流中定义的所有 Job 和步骤
- 验证 Actions 引用的有效性
-
变量预测
- 自动完成 Gitea 环境变量
- 显示可用的上下文
-
历史记录
- 保存最近执行过的调试脚本
- 快速重新运行
📚 相关文件
services/actions/debug_workflow.go- 核心业务逻辑routers/api/v1/repo/actions_debug.go- API 端点routers/api/v1/api.go- 路由注册models/actions/run.go- ActionRun 数据模型models/actions/run_job.go- ActionRunJob 数据模型