206 lines
4.9 KiB
Markdown
206 lines
4.9 KiB
Markdown
# Gitea 工作流在线调试 - 快速使用指南
|
||
|
||
## 🎯 功能特点
|
||
|
||
- ✅ **在线编辑工作流** - 无需本地编辑后推送
|
||
- ✅ **灵活配置参数** - 设置分支、事件、输入、环境变量
|
||
- ✅ **实时日志查看** - 及时反馈执行结果
|
||
- ✅ **多调试会话** - 并发调试多个工作流
|
||
- ✅ **无缝集成** - 使用现有的 Runner 系统
|
||
|
||
## 📖 使用步骤
|
||
|
||
### 1. 进入工作流页面
|
||
|
||
打开仓库的 Actions 页面：
|
||
```
|
||
https://your-gitea-instance/repos/{owner}/{repo}/actions
|
||
```
|
||
|
||
### 2. 选择要调试的工作流
|
||
|
||
在左侧菜单中点击要调试的工作流文件（如 `deploy.yml`）
|
||
|
||
### 3. 点击调试按钮
|
||
|
||
在筛选菜单右侧，会看到"Debug Workflow"按钮，点击进入调试页面
|
||
|
||
### 4. 配置调试环境
|
||
|
||
在调试页面的左侧面板配置：
|
||
|
||
#### 🔧 基础配置
|
||
- **Reference (分支/标签)** - 选择要在哪个分支/标签上执行
|
||
- **Event Type (事件类型)** - 选择触发事件类型
|
||
- `push` - 推送事件
|
||
- `pull_request` - PR 事件
|
||
- `workflow_dispatch` - 手动触发
|
||
- 其他...
|
||
|
||
#### 📝 工作流输入
|
||
如果工作流支持 `workflow_dispatch` 输入：
|
||
1. 点击"Add Input"按钮
|
||
2. 输入参数名称和值
|
||
3. 点击运行时会传递这些参数
|
||
|
||
示例：
|
||
```
|
||
Input Name: environment
|
||
Input Value: production
|
||
|
||
Input Name: version
|
||
Input Value: 1.0.0
|
||
```
|
||
|
||
#### 🔐 环境变量
|
||
添加自定义环境变量：
|
||
1. 点击"Add Environment"按钮
|
||
2. 输入环境变量名和值
|
||
3. 工作流执行时可以访问这些变量
|
||
|
||
示例：
|
||
```
|
||
ENV Name: DEBUG
|
||
ENV Value: true
|
||
|
||
ENV Name: LOG_LEVEL
|
||
ENV Value: debug
|
||
```
|
||
|
||
#### 📄 工作流内容
|
||
直接在编辑框中修改工作流 YAML 内容。支持修改：
|
||
- job 定义
|
||
- step 定义
|
||
- 条件表达式
|
||
- 其他任何工作流语法
|
||
|
||
### 5. 执行调试
|
||
|
||
点击"Run Workflow"按钮启动调试：
|
||
- 工作流会立即开始执行
|
||
- 状态面板会显示运行链接
|
||
|
||
### 6. 查看实时日志
|
||
|
||
在右侧面板查看：
|
||
- 📊 **执行日志** - 实时更新（每2秒刷新）
|
||
- 🔗 **运行链接** - 点击查看完整运行页面
|
||
- 📋 **复制日志** - 复制所有日志内容
|
||
|
||
## 💡 常见场景
|
||
|
||
### 场景 1: 调试部署脚本错误
|
||
|
||
1. 选择 `deploy.yml` 工作流
|
||
2. 点击调试
|
||
3. 修改部署步骤中有问题的命令
|
||
4. 在 ref 选择 `staging` 分支
|
||
5. 设置环境变量 `ENVIRONMENT=staging`
|
||
6. 运行调试
|
||
7. 查看日志找出问题
|
||
8. 修改代码并重新测试
|
||
|
||
### 场景 2: 测试新的工作流输入
|
||
|
||
1. 编辑 `test.yml` 工作流
|
||
2. 点击调试
|
||
3. 添加测试输入参数：
|
||
- `test_level: smoke`
|
||
- `parallel: true`
|
||
4. 运行调试
|
||
5. 验证输入是否正确传递
|
||
|
||
### 场景 3: 验证不同环境下的行为
|
||
|
||
1. 调试工作流
|
||
2. 分别设置环境变量：
|
||
- 第一次：`ENV=dev`
|
||
- 第二次：`ENV=staging`
|
||
- 第三次：`ENV=production`
|
||
3. 对比三次运行的日志
|
||
4. 确保各环境行为正确
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 权限要求
|
||
- 需要对仓库有 **Actions 写入权限**
|
||
- 只有仓库管理员可以创建调试会话
|
||
|
||
### 会话管理
|
||
- 每个调试会话会自动保存编辑的工作流内容
|
||
- 调试会话 24 小时后自动过期并清理
|
||
- 可以创建多个调试会话，互不影响
|
||
|
||
### 工作流执行
|
||
- 调试使用的是真实的 Runner，和正常运行一样
|
||
- 如果工作流有副作用（如部署、数据库操作），请谨慎
|
||
- 建议在测试分支上进行调试
|
||
|
||
### 日志显示
|
||
- 日志实时更新，可能有 1-2 秒延迟
|
||
- 日志存储有保留期，超期会被清理
|
||
- 如需保存日志，请及时复制
|
||
|
||
## 🔍 调试技巧
|
||
|
||
### 技巧 1: 分步验证
|
||
```yaml
|
||
jobs:
|
||
debug:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- name: Print environment
|
||
run: |
|
||
echo "Branch: ${{ github.ref }}"
|
||
echo "Event: ${{ github.event_name }}"
|
||
echo "DEBUG is: $DEBUG"
|
||
```
|
||
|
||
### 技巧 2: 添加详细日志
|
||
```yaml
|
||
steps:
|
||
- name: Run with debug output
|
||
run: |
|
||
set -x # Print each command
|
||
my-command --verbose
|
||
```
|
||
|
||
### 技巧 3: 条件调试
|
||
在工作流中添加调试步骤，使用条件控制：
|
||
```yaml
|
||
- name: Debug output
|
||
if: env.DEBUG == 'true'
|
||
run: |
|
||
# 调试命令
|
||
env
|
||
pwd
|
||
ls -la
|
||
```
|
||
|
||
## 📞 获取帮助
|
||
|
||
如遇到问题：
|
||
|
||
1. **检查权限** - 确保你有 Actions 写入权限
|
||
2. **查看日志** - 详细的日志通常能指出问题
|
||
3. **简化工作流** - 从最简单的步骤开始测试
|
||
4. **查看文档** - Gitea Actions 官方文档和 GitHub Actions 文档
|
||
|
||
## 🚀 最佳实践
|
||
|
||
✅ **推荐做法**
|
||
- 在非生产分支上调试
|
||
- 先用 echo 验证变量和路径
|
||
- 逐步扩展工作流复杂度
|
||
- 保存成功的工作流配置
|
||
|
||
❌ **避免做法**
|
||
- 不要在生产分支上运行有风险的调试
|
||
- 不要频繁修改无关工作流
|
||
- 不要忽视失败的调试运行
|
||
- 不要保留临时的调试代码在最终版本
|
||
|
||
---
|
||
|
||
**提示**: 该调试功能专为开发者设计，可以大幅加快 CI/CD 流程的故障排查和优化。充分利用它可以显著提高开发效率！
|