218 lines
8.2 KiB
Markdown
218 lines
8.2 KiB
Markdown
# 在线调试工作流功能 - 实现指南
|
|
|
|
## 📋 功能概述
|
|
|
|
这个功能允许开发者在 Gitea 的 Web 界面中在线调试 GitHub Actions 工作流。用户可以：
|
|
|
|
1. **输入或粘贴工作流 YAML 脚本**
|
|
2. **验证脚本语法**
|
|
3. **选择执行分支**
|
|
4. **立即执行工作流**
|
|
5. **查看完整执行日志和输出**
|
|
|
|
## 🔧 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"
|
|
}
|
|
}
|
|
```
|
|
|
|
**响应：**
|
|
```json
|
|
{
|
|
"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}
|
|
```
|
|
|
|
**响应：**
|
|
```json
|
|
{
|
|
"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 模板建议
|
|
```html
|
|
<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>
|
|
```
|
|
|
|
## 🔍 调试工作流的特殊标记
|
|
|
|
所有通过调试功能执行的工作流都会：
|
|
|
|
1. **WorkflowID**: 设置为 `debug-workflow.yml`（特殊标记）
|
|
2. **Title 前缀**: 添加 `[DEBUG]` 前缀
|
|
3. **Event**: 设置为 `workflow_dispatch`
|
|
4. **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 │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 🔐 安全考虑
|
|
|
|
1. **权限检查**: 只有具有仓库写权限的用户可以执行调试工作流
|
|
2. **Actions 启用**: 仓库必须启用 Actions 单元
|
|
3. **YAML 验证**: 所有提交的 YAML 都必须通过解析验证
|
|
4. **日志隔离**: 调试工作流的日志单独存储和标记
|
|
5. **Token 限制**: 调试工作流中的 token 应该有相同的限制
|
|
|
|
## 📝 日志输出
|
|
|
|
调试工作流的完整日志包括：
|
|
|
|
1. **工作流启动日志**
|
|
- 触发时间
|
|
- 执行用户
|
|
- 分支信息
|
|
|
|
2. **每个 Job 的日志**
|
|
- Job 名称和 ID
|
|
- 步骤执行情况
|
|
- 命令输出
|
|
- 错误信息
|
|
|
|
3. **工作流完成日志**
|
|
- 总执行时间
|
|
- 最终状态
|
|
- 任何错误总结
|
|
|
|
## 🚀 后续改进建议
|
|
|
|
1. **工作流模板库**
|
|
- 提供常用工作流模板
|
|
- 一键加载示例
|
|
|
|
2. **语法高亮**
|
|
- 在编辑器中支持 YAML 语法高亮
|
|
- 错误提示
|
|
|
|
3. **步骤预览**
|
|
- 显示工作流中定义的所有 Job 和步骤
|
|
- 验证 Actions 引用的有效性
|
|
|
|
4. **变量预测**
|
|
- 自动完成 Gitea 环境变量
|
|
- 显示可用的上下文
|
|
|
|
5. **历史记录**
|
|
- 保存最近执行过的调试脚本
|
|
- 快速重新运行
|
|
|
|
## 📚 相关文件
|
|
|
|
- `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 数据模型
|
|
|