# 發布流程

## 每次發布前

1. 確認 `CHANGELOG.md` 的 Unreleased 內容與目標版本一致。
2. 在本機執行 `npm test`、`npx tsc --noEmit`、`npm run build` 與 `./scripts/backup.sh`。
3. 提交並推送 `main`，確認 Gitea Actions 的 verify workflow 成功；它會執行 production dependency audit、測試、Docker build，並產生 SPDX SBOM artifact。
4. 建立 annotated tag，例如：`git tag -a v0.8.0 -m "Mebbling v0.8.0"`，再執行 `git push origin v0.8.0`。
5. 在 Gitea 的 Releases 以同一個 tag 建立 release；若版本尚供測試，勾選 Pre-release。

## 映像簽章

目前 workflow 只建置本機 Docker image，尚未指定容器 registry，因此不會產生無法驗證的假簽章。要啟用 cosign，先決定可推送的 OCI registry 與 image 名稱，並在 Gitea Actions 設定 `COSIGN_PRIVATE_KEY`、`COSIGN_PASSWORD` 和 registry 登入 secret；之後將 push、`cosign sign` 與 `cosign verify` 加入 tag 工作。部署端應只接受已驗證的 tag digest。

## 升級

升級前先備份。將 `.env` 的 `MEBBLING_VERSION` 改為新 tag，執行 `docker compose pull`（若使用 registry）或重新建置後 `docker compose up -d --no-build`。確認 `/api/health?probe=ready` 與 `/api/metrics`，並觀察 worker log。資料庫 migration 會在 Web／Worker 啟動時自動執行，請勿在升級後直接回退到舊映像。