csh
50efc4bbfa
- 新增 prepare.yml：统一检查/安装公共工具并集中 fetch 到共享 bare 仓库 - 统计与发布改为消费成功的 Prepare workflow_run，各自维护 stats/release worktree - 四个 workflow name 统一为带 emoji 的中文，同步 workflow_run 触发引用 - 系统信息 workflow 保持独立直接触发 - 删除 tests/ 手动验证脚本
213 lines
6.1 KiB
Markdown
213 lines
6.1 KiB
Markdown
# Workflow
|
||
|
||
本目录包含 Gitea Actions 的自动化工作流示例，展示如何使用 Gitea Actions 实现 CI/CD 自动化。
|
||
|
||
- 先看仓库总览：回到 [README.md](./README.md)
|
||
- 需要部署或维护 runner：参考 [DEPLOYMENT.md](./DEPLOYMENT.md)
|
||
|
||
---
|
||
|
||
## 📂 文件结构
|
||
|
||
```txt
|
||
.gitea/workflows/
|
||
├── prepare.yml # 公共工具 + shared bare repository
|
||
├── changelog_and_release.yml # Prepare 成功后的 Tag 发布消费者
|
||
├── update_stats_badge.yml # Prepare 成功后的主分支统计消费者
|
||
└── ubuntu_system_info.yml # 与仓库无关、独立直接触发
|
||
```
|
||
|
||
---
|
||
|
||
## 🧱 运行模型
|
||
|
||
```text
|
||
push / workflow_dispatch
|
||
├─ Prepare
|
||
│ ├─ 检查并按需安装公共工具
|
||
│ └─ fetch → /data/workspace/<repo>/repository.git
|
||
│
|
||
└─ Ubuntu System Information（自身触发条件命中时独立并行）
|
||
|
||
Prepare completed successfully
|
||
├─ main/master → update_stats_badge.yml
|
||
└─ refs/tags/[0-9]* → changelog_and_release.yml
|
||
```
|
||
|
||
`Prepare` 是仓库相关链路中唯一安装公共工具和 fetch 的 workflow。它保存一个 persistent bare repository，但不创建任何消费者 worktree。
|
||
|
||
统计和发布通过 `workflow_run` 读取上游 `head_sha`；发布还从 Gitea 的 `workflow_run.path`（例如 `prepare.yml@refs/tags/1.2.0`）恢复原始 Tag。两个消费者分别拥有 `worktrees/stats` 和 `worktrees/release`，首次创建时通过 `worktree-admin.lock` 串行修改 Git worktree metadata，每次复用前都执行 detached checkout、hard reset 和 clean。
|
||
|
||
三个仓库相关 workflow 使用各自的 per-repository concurrency group 且不取消排队运行。统计与发布使用不同 worktree，因此可以并行；系统信息 workflow 不依赖仓库或 Prepare，也可以独立并行。
|
||
|
||
---
|
||
|
||
## 🎯 功能列表
|
||
|
||
### ✅ 已实现
|
||
|
||
#### 1. 📦 自动发布工作流 (`changelog_and_release.yml`)
|
||
|
||
**功能**：在推送 tag 时自动生成 CHANGELOG 并创建 Release
|
||
|
||
**特性**：
|
||
|
||
- 🏷️ 自动识别语义版本号（SemVer）
|
||
- 📝 智能生成 CHANGELOG 条目
|
||
- 🔄 支持多个开发版本内容叠加
|
||
- 👥 自动提取贡献者列表
|
||
- 🚀 创建 GitHub/Gitea Release
|
||
- 📎 上传附件到 Release
|
||
- 🏷️ 自动识别 Pre-release 标记
|
||
|
||
**触发方式**：
|
||
|
||
推送数字开头的 Tag 会先触发 `Prepare`。Prepare 成功后，发布 routing job 从 `workflow_run.path` 恢复 Tag，确认 Tag peeled commit 等于 `head_sha`，随后才生成 CHANGELOG 和 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.yml`)
|
||
|
||
**功能**：自动统计代码行数并生成 SVG 徽章与统计报告
|
||
|
||
**特性**：
|
||
|
||
- 📈 统计总代码行数和文件数
|
||
- 🌐 按语言分组统计
|
||
- 🎨 自动生成仓库内自托管的 SVG 徽章
|
||
- 📊 在 `stats` 分支根目录生成统计报告 README
|
||
- 🚫 灵活的目录排除配置
|
||
|
||
**触发方式**：
|
||
|
||
主分支 push 或在 `main`/`master` 上手动运行 Prepare 后，统计 workflow 通过成功的 `workflow_run` 启动，并始终从上游 `head_sha` 的 detached checkout 读取源码。
|
||
|
||
```bash
|
||
# 推送到主分支时自动触发
|
||
git push origin main
|
||
|
||
# 手动触发
|
||
# 仓库 → Actions → Prepare → Run workflow
|
||
```
|
||
|
||
**配置文件**：[update_stats_badge.yml](.gitea/workflows/update_stats_badge.yml)
|
||
|
||
**markdown引用格式**: ``
|
||
|
||
**产物结构**：
|
||
|
||
```txt
|
||
stats
|
||
├── README.md
|
||
└── badges/
|
||
├── total-lines.svg
|
||
├── total-files.svg
|
||
├── language-count.svg
|
||
└── <language>-lines.svg
|
||
```
|
||
|
||
💡 **详细配置**：查看 `update_stats_badge.yml` 文件顶部的 `env` 区域，包含语言分组、颜色、排除目录等配置
|
||
|
||
---
|
||
|
||
#### 3. 🖥️ 系统信息工作流 (`ubuntu_system_info.yml`)
|
||
|
||
该 workflow 不读取仓库内容，保留自己的 `push` 和 `workflow_dispatch` 触发器；它不使用 `workflow_run`、`repository.git` 或任何消费者 worktree。
|
||
|
||
---
|
||
|
||
### 🔜 待扩展
|
||
|
||
更多自动化场景：
|
||
|
||
- 🧪 **自动测试** - 推送代码时运行单元测试
|
||
- 🏗️ **自动构建** - 构建并发布 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
|