192 lines
4.9 KiB
Markdown
192 lines
4.9 KiB
Markdown
# Workflow
|
||
|
||
本目录包含 Gitea Actions 的自动化工作流示例，展示如何使用 Gitea Actions 实现 CI/CD 自动化。
|
||
|
||
- 先看仓库总览：回到 [README.md](./README.md)
|
||
- 需要部署或维护 runner：参考 [DEPLOYMENT.md](./DEPLOYMENT.md)
|
||
|
||
---
|
||
|
||
## 📂 文件结构
|
||
|
||
```txt
|
||
.gitea/workflows/
|
||
├── changelog_and_release.yml # CHANGELOG 生成 + Release 创建
|
||
├── update_stats_badge.yaml # 代码行数的统计
|
||
└── ... # 更多 workflow 待添加
|
||
```
|
||
|
||
---
|
||
|
||
## 🧱 运行模型
|
||
|
||
本模板中的 workflow 采用“按职责划分固定 slot”的方案：
|
||
|
||
- 每个会写仓库的 workflow 职责拥有一个固定 slot，slot 本身就是 Git clone 根目录，不额外包含 `repo` 子目录
|
||
- 第一次运行会 clone 仓库，后续运行通过 fetch、`git reset --hard` 和 clean 重置后复用已有 checkout
|
||
- 同一 slot 的任务按 concurrency group 串行执行，不同 slot 之间可以并发运行
|
||
- 任务结束后保留 slot checkout；长期依赖缓存应放在 checkout 之外，避免被清理命令删除
|
||
|
||
这个设计适用于仓库和 workflow 职责固定的自托管 CI 服务器，在减少重复 clone 的同时避免多个任务并发修改同一个工作目录。
|
||
|
||
---
|
||
|
||
## 🎯 功能列表
|
||
|
||
### ✅ 已实现
|
||
|
||
#### 1. 📦 自动发布工作流 (`changelog_and_release.yml`)
|
||
|
||
**功能**：在推送 tag 时自动生成 CHANGELOG 并创建 Release
|
||
|
||
**特性**：
|
||
|
||
- 🏷️ 自动识别语义版本号（SemVer）
|
||
- 📝 智能生成 CHANGELOG 条目
|
||
- 🔄 支持多个开发版本内容叠加
|
||
- 👥 自动提取贡献者列表
|
||
- 🚀 创建 GitHub/Gitea Release
|
||
- 📎 上传附件到 Release
|
||
- 🏷️ 自动识别 Pre-release 标记
|
||
|
||
**触发方式**：
|
||
|
||
```bash
|
||
git tag 1.0.0
|
||
git push origin 1.0.0
|
||
```
|
||
|
||
**文件**：[changelog_and_release.yml](.gitea/workflows/changelog_and_release.yml)
|
||
|
||
💡 **详细配置**：查看 `changelog_and_release.yml` 文件顶部的 `env` 区域，所有配置项都有详细注释说明
|
||
|
||
---
|
||
|
||
#### 2. 📊 代码统计徽章工作流 (`update_stats_badge.yaml`)
|
||
|
||
**功能**：自动统计代码行数并生成 SVG 徽章与统计报告
|
||
|
||
**特性**：
|
||
|
||
- 📈 统计总代码行数和文件数
|
||
- 🌐 按语言分组统计
|
||
- 🎨 自动生成仓库内自托管的 SVG 徽章
|
||
- 📊 在 `stats` 分支根目录生成统计报告 README
|
||
- 🚫 灵活的目录排除配置
|
||
|
||
**触发方式**：
|
||
|
||
```bash
|
||
# 推送到主分支时自动触发
|
||
git push origin main
|
||
|
||
# 手动触发
|
||
# 仓库 → Actions → Update Code Statistics Badge → Run workflow
|
||
```
|
||
|
||
**配置文件**：[update_stats_badge.yaml](.gitea/workflows/update_stats_badge.yaml)
|
||
|
||
**markdown引用格式**: ``
|
||
|
||
**产物结构**：
|
||
|
||
```txt
|
||
stats
|
||
├── README.md
|
||
└── badges/
|
||
├── total-lines.svg
|
||
├── total-files.svg
|
||
├── language-count.svg
|
||
└── <language>-lines.svg
|
||
```
|
||
|
||
💡 **详细配置**：查看 `update_stats_badge.yaml` 文件顶部的 `env` 区域，包含语言分组、颜色、排除目录等配置
|
||
|
||
---
|
||
|
||
### 🔜 待扩展
|
||
|
||
更多自动化场景：
|
||
|
||
- 🧪 **自动测试** - 推送代码时运行单元测试
|
||
- 🏗️ **自动构建** - 构建并发布 Docker 镜像
|
||
- 📊 **代码质量** - 运行代码检查和静态分析
|
||
- 🌐 **自动部署** - 部署到生产环境
|
||
- 📧 **通知集成** - 发送构建结果到 Slack/邮件
|
||
- 🔐 **安全扫描** - 依赖漏洞扫描
|
||
|
||
---
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q1: 如何配置 Token？
|
||
|
||
**步骤**：
|
||
|
||
1. Gitea → 设置 → 应用 → 生成新令牌
|
||
2. 权限：勾选 **repo**
|
||
3. 仓库 → Settings → Actions → Secrets → 添加 Secret
|
||
4. 名称：`WORKFLOW`，值：你的 Token
|
||
|
||
💡 **提示**：一个 Token 即可完成所有操作（Git + API）
|
||
|
||
---
|
||
|
||
### Q2: `changelog_and_release` 没有触发？
|
||
|
||
**检查清单**：
|
||
|
||
- [ ] Workflow 文件在 `.gitea/workflows/` 目录
|
||
- [ ] 文件名正确（如 `changelog_and_release.yml`）
|
||
- [ ] Token 已正确配置（Secret 名称为 `WORKFLOW`）
|
||
- [ ] Tag 格式正确（数字开头，如 `1.0.0`）
|
||
- [ ] Gitea Actions 已启用
|
||
- [ ] Runner 正常运行
|
||
|
||
---
|
||
|
||
### Q3: `changelog_and_release` 版本号格式有要求吗？
|
||
|
||
推荐使用**语义化版本号（SemVer）**：
|
||
|
||
```bash
|
||
✅ 推荐格式：
|
||
1.0.0 # 正式版本
|
||
1.0.0-beta1 # 预发布版本
|
||
|
||
❌ 不推荐：
|
||
v1.0.0 # 不要使用 v 前缀
|
||
1.0.0-b1 # 后缀要完整
|
||
```
|
||
|
||
详细规范请参考 workflow 文件中的注释说明。
|
||
|
||
---
|
||
|
||
### Q4: 如何查看执行日志？
|
||
|
||
仓库 → Actions → 点击对应的 workflow 运行记录 → 查看详细日志
|
||
|
||
---
|
||
|
||
### Q5: Token 权限不足怎么办？
|
||
|
||
确保 Token 具有以下权限：
|
||
|
||
- ✅ **repo** - 完整仓库访问权限
|
||
- 用于读取代码
|
||
- 用于推送提交
|
||
- 用于创建 Release
|
||
|
||
如果还是失败，尝试重新生成 Token。
|
||
|
||
---
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交更多实用的 Workflow 示例！
|
||
|
||
---
|
||
|
||
## 📄 许可 MIT
|