ci: add upstream sync workflows and optimize Docker CI builds
- Add auto-upstream-sync workflow with dedup protection for conflict issues - Add upstream-sync build + smoke test workflow - Add smoke-test script and test files - Add upstream sync issue template and documentation - Fix: use --allow-unrelated-histories for merge command - Fix: check for existing open merge-conflict issues before creating duplicates
This commit is contained in:
Your Name
parent
5d421e8a76
commit
171cca98ac
6 changed files with 1205 additions and 3 deletions
280
.github/UPSTREAM_SYNC.md
vendored
Normal file
280
.github/UPSTREAM_SYNC.md
vendored
Normal file
|
|
@ -0,0 +1,280 @@
|
|||
# 🔄 Upstream 自動同步機制
|
||||
|
||||
本專案實作了完整的 upstream 自動同步、變更追蹤與 smoke test 機制。
|
||||
|
||||
## 📋 目錄
|
||||
|
||||
- [功能概述](#功能概述)
|
||||
- [工作流程圖](#工作流程圖)
|
||||
- [Workflow 說明](#workflow-說明)
|
||||
- [Smoke Test 內容](#smoke-test-內容)
|
||||
- [設定說明](#設定說明)
|
||||
- [手動操作](#手動操作)
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
||||
### 1️⃣ 自動同步 Upstream
|
||||
|
||||
| 功能 | 說明 |
|
||||
| ---------- | ---------------------------- |
|
||||
| 觸發方式 | 每 6 小時自動檢查 / 手動觸發 |
|
||||
| 同步目標 | `dev` 分支 |
|
||||
| Merge 策略 | 自動 merge（無衝突時） |
|
||||
| 衝突處理 | 自動建立 GitHub Issue 通知 |
|
||||
|
||||
### 2️⃣ 變更摘要
|
||||
|
||||
同步完成後自動產生：
|
||||
|
||||
- ✅ GitHub Issue（詳細變更記錄）
|
||||
- ✅ `upstream-changelog.md`（累積變更歷史）
|
||||
- ✅ GitHub Actions Summary（快速查看）
|
||||
|
||||
### 3️⃣ Smoke Test
|
||||
|
||||
| 測試項目 | 內容 | 時間限制 |
|
||||
| -------------- | -------------------------------------- | ------------- |
|
||||
| Container 啟動 | 驗證 image 可正常啟動 | 60s |
|
||||
| 工具檢查 | libreoffice, pandoc, ffmpeg, tesseract | 30s |
|
||||
| 最小轉換 | txt → pdf | 60s |
|
||||
| API 端點 | healthcheck, root | 10s |
|
||||
| **總計** | | **< 10 分鐘** |
|
||||
|
||||
---
|
||||
|
||||
## 工作流程圖
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ Upstream 自動同步流程 │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────┐
|
||||
│ Upstream │
|
||||
│ (C4illin/ │
|
||||
│ ConvertX) │
|
||||
└──────┬───────┘
|
||||
│
|
||||
│ 每 6 小時檢查
|
||||
▼
|
||||
┌──────────────┐ 無更新 ┌──────────────┐
|
||||
│ 檢查是否有 │ ─────────────► │ 結束 │
|
||||
│ 新 commits │ └──────────────┘
|
||||
└──────┬───────┘
|
||||
│ 有更新
|
||||
▼
|
||||
┌──────────────┐ 衝突 ┌──────────────┐
|
||||
│ 自動 Merge │ ─────────────► │ 建立 Issue │
|
||||
│ 到 dev 分支 │ │ 需手動處理 │
|
||||
└──────┬───────┘ └──────────────┘
|
||||
│ 成功
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ 產生變更摘要 │
|
||||
│ • Issue │
|
||||
│ • Changelog │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Push 到 dev │
|
||||
└──────┬───────┘
|
||||
│
|
||||
│ 觸發 upstream-sync.yml
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Build 測試 │
|
||||
│ Image (amd64)│
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ Smoke Test │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||||
│ │ Container │ │ 工具 │ │ 轉換 │ │
|
||||
│ │ 啟動 │ │ 檢查 │ │ 測試 │ │
|
||||
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
|
||||
│ │ │ │ │
|
||||
│ └──────────────┼──────────────┘ │
|
||||
│ │ │
|
||||
└───────────────────────┼──────────────────────────┘
|
||||
│
|
||||
┌─────────────┴─────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌────────────┐ ┌────────────┐
|
||||
│ ✅ 通過 │ │ ❌ 失敗 │
|
||||
└─────┬──────┘ └─────┬──────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌────────────┐ ┌────────────┐
|
||||
│ Build 並 │ │ Workflow │
|
||||
│ Push 到 │ │ 失敗 │
|
||||
│ Docker Hub │ │ (不發布) │
|
||||
└─────┬──────┘ └────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────┐
|
||||
│ upstream-YYYYMMDD tag │
|
||||
│ ❌ 不更新 latest │
|
||||
│ ❌ 不打 semver tag │
|
||||
└────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow 說明
|
||||
|
||||
### `auto-upstream-sync.yml`
|
||||
|
||||
**用途：** 自動檢測並同步 upstream 更新
|
||||
|
||||
**觸發條件：**
|
||||
|
||||
- ⏰ 每 6 小時自動執行
|
||||
- 🖱️ 手動觸發
|
||||
|
||||
**主要步驟：**
|
||||
|
||||
1. Fetch upstream 最新程式碼
|
||||
2. 檢查是否有新 commits
|
||||
3. 自動 merge 到 `dev` 分支
|
||||
4. 產生變更摘要（Issue + Changelog）
|
||||
5. Push 到 `dev`
|
||||
|
||||
### `upstream-sync.yml`
|
||||
|
||||
**用途：** 當 `dev` 分支有 push 時，執行 build + smoke test
|
||||
|
||||
**觸發條件：**
|
||||
|
||||
- 📦 `dev` 分支有 push
|
||||
|
||||
**主要步驟：**
|
||||
|
||||
1. Build 測試用 image（僅 amd64，加速測試）
|
||||
2. 執行 Smoke Test（10 分鐘內）
|
||||
3. 測試通過後 build multi-arch image
|
||||
4. Push 到 Docker Hub（tag: `upstream-YYYYMMDD`）
|
||||
|
||||
---
|
||||
|
||||
## Smoke Test 內容
|
||||
|
||||
### Test 1: Container 啟動測試
|
||||
|
||||
```bash
|
||||
# 啟動 container 並等待 healthcheck 回應
|
||||
docker run -d --name convertx-test $IMAGE
|
||||
curl http://localhost:3000/healthcheck
|
||||
```
|
||||
|
||||
### Test 2: 關鍵工具檢查
|
||||
|
||||
```bash
|
||||
# 必須通過（任一失敗則整體失敗）
|
||||
libreoffice --version
|
||||
pandoc --version
|
||||
ffmpeg -version
|
||||
tesseract --version
|
||||
```
|
||||
|
||||
### Test 3: 最小轉換測試
|
||||
|
||||
```bash
|
||||
# txt → pdf 轉換測試
|
||||
echo "test" > test.txt
|
||||
libreoffice --headless --convert-to pdf test.txt
|
||||
```
|
||||
|
||||
### Test 4: API 端點檢查
|
||||
|
||||
```bash
|
||||
# 確認服務正常運作
|
||||
curl http://localhost:3000/healthcheck
|
||||
curl http://localhost:3000/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 設定說明
|
||||
|
||||
### 必要的 GitHub Secrets
|
||||
|
||||
在 Repository Settings → Secrets and variables → Actions 中設定：
|
||||
|
||||
| Secret 名稱 | 說明 |
|
||||
| -------------------- | ----------------------- |
|
||||
| `DOCKERHUB_USERNAME` | Docker Hub 帳號 |
|
||||
| `DOCKERHUB_TOKEN` | Docker Hub Access Token |
|
||||
|
||||
### 分支保護規則
|
||||
|
||||
建議設定：
|
||||
|
||||
**`main` 分支：**
|
||||
|
||||
- ✅ Require pull request before merging
|
||||
- ✅ Require status checks to pass
|
||||
- ❌ Allow force pushes
|
||||
|
||||
**`dev` 分支：**
|
||||
|
||||
- ✅ Allow direct pushes (for automation)
|
||||
|
||||
---
|
||||
|
||||
## 手動操作
|
||||
|
||||
### 手動觸發同步
|
||||
|
||||
1. 前往 Actions → Auto Upstream Sync
|
||||
2. 點選 "Run workflow"
|
||||
3. 可選擇「強制同步」
|
||||
|
||||
### 手動處理 Merge 衝突
|
||||
|
||||
當自動同步發生衝突時：
|
||||
|
||||
```bash
|
||||
# 1. 切換到 dev 分支
|
||||
git checkout dev
|
||||
|
||||
# 2. 添加 upstream remote（如果還沒有）
|
||||
git remote add upstream https://github.com/C4illin/ConvertX.git
|
||||
|
||||
# 3. Fetch upstream
|
||||
git fetch upstream main
|
||||
|
||||
# 4. Merge upstream
|
||||
git merge upstream/main
|
||||
|
||||
# 5. 解決衝突
|
||||
# ... 編輯衝突的檔案 ...
|
||||
|
||||
# 6. 提交並 push
|
||||
git add .
|
||||
git commit -m "Resolve merge conflicts with upstream"
|
||||
git push origin dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 注意事項
|
||||
|
||||
1. **不會自動更新 `latest` tag** - 需要手動發布正式版本
|
||||
2. **不會自動打 semver tag** - 需要手動建立 release
|
||||
3. **`main` 分支不會被自動修改** - 只有 `dev` 會自動同步
|
||||
4. **Smoke test 失敗時不會發布 image** - 確保品質
|
||||
|
||||
---
|
||||
|
||||
## 📊 Docker Image Tag 規則
|
||||
|
||||
| Tag 格式 | 說明 | 自動/手動 |
|
||||
| ------------------- | ---------------------------------- | --------- |
|
||||
| `upstream-YYYYMMDD` | Upstream 同步版（經過 smoke test） | 自動 |
|
||||
| `vX.Y.Z` | 正式版本 | 手動 |
|
||||
| `latest` | 最新穩定版 | 手動 |
|
||||
Loading…
Add table
Add a link
Reference in a new issue