99 lines
5.3 KiB
Markdown
99 lines
5.3 KiB
Markdown
# GitHub Primary Rollback ADR 草案
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 日期 | 2026-05-13 |
|
||
| 狀態 | 草案，等待 owner review |
|
||
| Schema | `docs/schemas/source_control_primary_rollback_adr_v1.schema.json` |
|
||
| Snapshot | `docs/security/source-control-primary-rollback-adr.snapshot.json` |
|
||
| 模式 | `rollback_adr_only` |
|
||
| runtime 執行授權 | `false` |
|
||
|
||
## 0. 核心結論
|
||
|
||
S4.4 補上 GitHub primary cutover 前必備的 rollback ADR 草案。
|
||
|
||
這不是 cutover plan，也不是 rollback 執行計畫。它只定義：每個 repo 在未來要切 GitHub primary 前，必須先有什麼 evidence、誰是 rollback owner、哪些狀況要停下來、以及切換後 1 小時 / 24 小時要看什麼。
|
||
|
||
目前 `owner_approved_count=0`、`dry_run_completed_count=0`、`active_cutover_count=0`，所以 `primary_ready_count` 仍必須維持 0。
|
||
|
||
## 1. 摘要
|
||
|
||
| 指標 | 數量 |
|
||
|------|------|
|
||
| Candidate repos | 8 |
|
||
| In-scope repos | 7 |
|
||
| External scope review | 1 |
|
||
| Repo rollback plan drafts | 7 |
|
||
| Owner approved | 0 |
|
||
| Dry-run completed | 0 |
|
||
| Active cutover | 0 |
|
||
| Rollback execution authorized | `false` |
|
||
| GitHub primary switch authorized | `false` |
|
||
| Gitea disable authorized | `false` |
|
||
|
||
## 2. Rollback 原則
|
||
|
||
1. GitHub primary 是長期方向，但每個 repo 必須先有 owner-approved rollback plan 才能進入 cutover review。
|
||
2. Gitea 在 cutover 前後都必須保留為本地 mirror / fallback，不得因 GitHub primary 準備而停用、刪除或封存。
|
||
3. Rollback ADR 只定義人工決策、驗證窗口與回退條件；不授權任何 refs sync、primary switch 或 webhook 修改。
|
||
4. 任何回退都必須有新的 runtime gate、人工批准與 evidence snapshot，不得由本 ADR 自動觸發。
|
||
5. 初期只做 observe / approval_required，不把缺 LOW / MEDIUM evidence 變成 production blocker。
|
||
|
||
## 3. 切換前必要 Gate
|
||
|
||
| Gate | 目前狀態 | 必要 evidence |
|
||
|------|----------|---------------|
|
||
| Gitea authenticated inventory | blocked | private/internal 全量 repo list、redacted admin export 或 read-only token evidence |
|
||
| refs truth / parity | waiting owner review | main/dev、release tags、deprecated refs 的 owner 判定 |
|
||
| workflow / secret export | draft only | webhook、runner、deploy key、branch protection、repository secret name parity redacted evidence |
|
||
| owner / visibility / canonical | waiting owner review | 7 個 in-scope repo 的 owner / target / canonical 決策 |
|
||
| rollback owner / monitoring | draft only | 每個 repo 的 rollback owner、1h / 24h 驗證窗口與 decision record 格式 |
|
||
|
||
## 4. Repo Rollback Draft
|
||
|
||
| Repo | Risk | Rollback state | 主要缺口 |
|
||
|------|------|----------------|----------|
|
||
| `owenhytsai/awoooi` | HIGH | waiting owner review | refs parity、deploy workflow、webhook single-sender、runner owner、secret name parity |
|
||
| `owenhytsai/clawbot-v5` | MEDIUM | waiting owner review | tag policy、workflow / secret need attestation、rollback owner |
|
||
| `owenhytsai/wooo-aiops` | MEDIUM | waiting owner review | GitHub-only refs、webhook owner、runner owner |
|
||
| `owenhytsai/wooo-infra-config` | MEDIUM | waiting owner review | 110 internal remote、deploy key、infra secret name parity |
|
||
| `owenhytsai/ewoooc` | HIGH | waiting owner review | target access、canonical repo、unrelated history risk |
|
||
| `owenhytsai/bitan-pharmacy` | MEDIUM | waiting owner review | active status、GitHub target、secret / deploy owner |
|
||
| `owenhytsai/tsenyang-website` | MEDIUM | waiting owner review | active status、GitHub target、secret / deploy owner |
|
||
| `nexu-io/open-design` | LOW | scope review only | 不進 AWOOOI primary cutover queue |
|
||
|
||
## 5. Rollback 觸發條件
|
||
|
||
1. main/dev SHA 或 tag parity 與 owner-approved truth 不一致。
|
||
2. workflow、webhook、runner、deploy key、branch protection 或 repository secret name parity evidence 不完整。
|
||
3. GitHub hosted runner 使用量或 billing risk 超出 owner-approved 範圍。
|
||
4. deploy marker、release workflow 或 required status check 在 cutover 後失敗。
|
||
5. duplicate webhook 造成重複部署、重複通知或 approval queue 重複事件。
|
||
6. owner / visibility / canonical decision 被撤回或出現衝突。
|
||
7. post-cutover 1h 或 24h validation window 未通過。
|
||
|
||
## 6. AwoooP 可做
|
||
|
||
1. 顯示 7 個 in-scope repo 的 rollback ADR draft。
|
||
2. 顯示 owner-approved count、dry-run completed count、active cutover count 都是 0。
|
||
3. 將 rollback owner、precondition、validation window 與 trigger 顯示在 Operator Console。
|
||
4. 把 rollback ADR 缺口寫入 Audit evidence。
|
||
5. 若未來 owner 提交決策，另寫入 `security_approval_decision_record_v1`。
|
||
|
||
## 7. AwoooP 不可做
|
||
|
||
1. 不把 ADR 草案當成 cutover approval。
|
||
2. 不切 GitHub primary。
|
||
3. 不執行 rollback。
|
||
4. 不 sync refs、不 delete refs、不 force push。
|
||
5. 不修改 webhook、workflow、branch protection 或 secret。
|
||
6. 不停用、刪除、封存或降級 Gitea repo。
|
||
7. 不新增 repo、refs、primary switch、rollback 類 action button。
|
||
|
||
## 8. 階段定位
|
||
|
||
S4.0 定義 primary readiness gate，S4.1 到 S4.3 補 workflow / secret inventory 與 export request，S4.4 補 rollback ADR 草案。
|
||
|
||
這讓「長期改回 GitHub primary」有更完整的安全出口，但仍然停在框架期：先讓 AwoooP 看見風險與 owner review，不啟動任何切換、不執行任何回退。
|