Skip to content

Commit f6dc2ec

Browse files
committed
feat(cicd): enhance GitHub Actions CI/CD workflows (Story 11-4)
- CI workflow (ci.yml): - Add parallel lint and security (govulncheck) jobs - Separate unit-test and build jobs for parallelization - Integration and acceptance tests already included - Use Go 1.24 environment variable - Docker workflow (docker.yml): - Add QEMU for multi-platform builds - Add Trivy security scanning with SARIF upload - Push Agent images to GHCR - Enhanced tag strategy - Release workflow (release.yml): - Matrix strategy for 15 binaries (5 platforms x 3 components) - Add Linux/arm64, macOS/arm64 (Apple Silicon) support - Add CLI binary builds - Generate SHA256 checksums.txt - Improved Release Notes with binary table - Documentation: - Create .github/README.md with CI/CD documentation - Document branch protection rules - Add CI/Docker/Release/Codecov/Go Report badges to README AC Coverage: AC1-AC6 100%
1 parent 18606b4 commit f6dc2ec

86 files changed

Lines changed: 12672 additions & 385 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.github/README.md

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# CI/CD 工作流文档
2+
3+
本目录包含 Waterflow 项目的 GitHub Actions CI/CD 配置。
4+
5+
## 工作流概览
6+
7+
| 工作流 | 文件 | 触发条件 | 用途 |
8+
|--------|------|----------|------|
9+
| CI | `ci.yml` | Push/PR to main/develop | 代码质量检查、测试、构建 |
10+
| Docker Build | `docker.yml` | Push to main/develop, Tags | 构建和推送 Docker 镜像 |
11+
| Release | `release.yml` | Tag v*.*.* | 创建 GitHub Release |
12+
| Stress Test | `stress-test.yml` | Schedule/Manual | 压力测试 |
13+
| Semantic PR | `semantic-pr.yml` | PR | PR 标题规范检查 |
14+
| Labels | `label.yml` | PR | 自动添加标签 |
15+
16+
## CI 工作流 (ci.yml)
17+
18+
### 阶段流程
19+
20+
```
21+
Stage 1 (并行):
22+
├── lint - golangci-lint 代码检查
23+
└── security - govulncheck 漏洞扫描
24+
25+
Stage 2 (需要 lint 通过):
26+
├── unit-test - 单元测试 + 覆盖率
27+
└── build - 构建 server/agent/cli
28+
29+
Stage 3 (需要 Stage 2 通过):
30+
└── integration-tests - 集成测试 (Temporal + PostgreSQL)
31+
32+
Stage 4 (需要集成测试通过):
33+
└── acceptance-tests - 验收测试 (多 Agent 环境)
34+
```
35+
36+
### Jobs 详情
37+
38+
#### lint
39+
- 运行 golangci-lint
40+
- 超时: 5 分钟
41+
- 配置: `.golangci.yml`
42+
43+
#### security
44+
- 运行 govulncheck 检查依赖漏洞
45+
- 与 lint 并行执行
46+
47+
#### unit-test
48+
- 运行 `make test`
49+
- 生成覆盖率报告
50+
- 上传到 Codecov
51+
- 依赖: lint 通过
52+
53+
#### build
54+
- 构建 server、agent、CLI 二进制
55+
- 验证二进制版本信息
56+
- 上传 artifacts
57+
- 依赖: lint 通过
58+
59+
#### integration-tests
60+
- 使用 `docker-compose.test.yaml` 启动环境
61+
- 需要: Temporal, PostgreSQL, Server, Agent
62+
- 超时: 15 分钟
63+
- 依赖: unit-test, build
64+
65+
#### acceptance-tests
66+
- 使用 `docker-compose.acceptance.yaml`
67+
- 多 Agent 测试环境 (web-1, web-2, db-1)
68+
- 运行 PRD 验收场景
69+
- 超时: 25 分钟
70+
- 依赖: integration-tests
71+
72+
## Docker 工作流 (docker.yml)
73+
74+
### 构建矩阵
75+
76+
- **平台**: linux/amd64, linux/arm64
77+
- **镜像**:
78+
- Server: `waterflow/server`
79+
- Agent: `waterflow/agent`
80+
81+
### 镜像标签策略
82+
83+
| 触发条件 | 标签格式 |
84+
|----------|----------|
85+
| Branch push | `{branch}`, `{branch}-{sha}` |
86+
| Tag push | `{version}`, `{major}.{minor}`, `latest` |
87+
| PR | `pr-{number}` |
88+
89+
### 安全扫描
90+
91+
- 使用 Trivy 扫描镜像漏洞
92+
- 结果上传到 GitHub Security
93+
94+
### Registry
95+
96+
- Docker Hub: `docker.io/waterflow/*`
97+
- GHCR: `ghcr.io/{owner}/waterflow-*`
98+
99+
## Release 工作流 (release.yml)
100+
101+
### 触发条件
102+
103+
仅在推送 `v*.*.*` 格式的 tag 时触发。
104+
105+
### 构建矩阵
106+
107+
| 平台 | Server | Agent | CLI |
108+
|------|--------|-------|-----|
109+
| Linux amd64 ||||
110+
| Linux arm64 ||||
111+
| macOS amd64 ||||
112+
| macOS arm64 ||||
113+
| Windows amd64 ||||
114+
115+
### Release 资产
116+
117+
- 15 个二进制文件 (5 平台 × 3 组件)
118+
- `checksums.txt` (SHA256)
119+
- 自动生成的 Release Notes
120+
121+
## Secrets 配置
122+
123+
### 必需 Secrets
124+
125+
| Secret | 用途 | 设置位置 |
126+
|--------|------|----------|
127+
| `DOCKER_USERNAME` | Docker Hub 登录 | Repository Settings |
128+
| `DOCKER_PASSWORD` | Docker Hub 密码/Token | Repository Settings |
129+
130+
### 可选 Secrets
131+
132+
| Secret | 用途 | 默认行为 |
133+
|--------|------|----------|
134+
| `CODECOV_TOKEN` | Codecov 上传 | 上传失败但不阻塞 CI |
135+
| `SLACK_WEBHOOK` | Slack 通知 | 跳过通知 |
136+
137+
### 自动提供的 Secrets
138+
139+
- `GITHUB_TOKEN`: 自动提供,用于 GHCR 和 Release
140+
141+
## 分支保护规则
142+
143+
### main 分支 (推荐配置)
144+
145+
在 GitHub Repository Settings → Branches → Add branch protection rule:
146+
147+
```
148+
Branch name pattern: main
149+
150+
☑ Require a pull request before merging
151+
☑ Require approvals: 1
152+
☑ Dismiss stale pull request approvals when new commits are pushed
153+
154+
☑ Require status checks to pass before merging
155+
☑ Require branches to be up to date before merging
156+
Required status checks:
157+
- lint
158+
- unit-test
159+
- build
160+
161+
☑ Require conversation resolution before merging
162+
163+
☐ Require signed commits (可选)
164+
165+
☑ Do not allow bypassing the above settings
166+
```
167+
168+
### develop 分支 (推荐配置)
169+
170+
```
171+
Branch name pattern: develop
172+
173+
☑ Require a pull request before merging
174+
175+
☑ Require status checks to pass before merging
176+
Required status checks:
177+
- lint
178+
- unit-test
179+
```
180+
181+
## 本地运行
182+
183+
### 运行完整 CI 检查
184+
185+
```bash
186+
# 代码检查
187+
make lint
188+
189+
# 单元测试
190+
make test
191+
192+
# 覆盖率
193+
make coverage
194+
195+
# 构建
196+
make build build-agent cli
197+
198+
# 集成测试
199+
make integration-test
200+
201+
# 验收测试
202+
make acceptance-test
203+
```
204+
205+
### 模拟 CI 环境
206+
207+
```bash
208+
# 使用 act 本地运行 GitHub Actions (需要 Docker)
209+
# https://github.com/nektos/act
210+
act -j lint
211+
act -j unit-test
212+
```
213+
214+
## 手动触发
215+
216+
### 触发 Release
217+
218+
```bash
219+
# 创建并推送 tag
220+
git tag v1.2.3
221+
git push origin v1.2.3
222+
```
223+
224+
### 手动运行压力测试
225+
226+
1. 进入 Actions 页面
227+
2. 选择 "Stress Test" 工作流
228+
3. 点击 "Run workflow"
229+
230+
## 故障排查
231+
232+
### CI 失败
233+
234+
1. 检查失败的 job logs
235+
2. 本地运行相同命令复现
236+
3. 检查最近的代码变更
237+
238+
### Docker 构建失败
239+
240+
1. 检查 Dockerfile 语法
241+
2. 验证基础镜像可用性
242+
3. 检查构建参数
243+
244+
### Release 失败
245+
246+
1. 确认 tag 格式正确 (`v*.*.*`)
247+
2. 检查 secrets 配置
248+
3. 验证构建步骤
249+
250+
## 相关文档
251+
252+
- [开发指南](../../docs/development.md)
253+
- [部署文档](../../docs/deployment.md)
254+
- [故障排查](../../docs/troubleshooting.md)

0 commit comments

Comments
 (0)