Gitea Server-side 全量 Repo Inventory Runbook

項目	內容
日期	2026-05-12
狀態	第一版，read-only / export-only
工具	`scripts/security/gitea-repo-inventory.py`
事件	`gitea_repo_inventory_v1`
Approval package	`docs/security/GITEA-READONLY-INVENTORY-APPROVAL-PACKAGE.md`
Redaction checklist	`docs/security/GITEA-ADMIN-EXPORT-REDACTION-CHECKLIST.md`
S4.5 export request	`docs/security/GITEA-AUTHENTICATED-INVENTORY-EXPORT-REQUEST.md`
原則	不寫入 Gitea、不搬 secret value、不建立或刪除 repo

0. 核心結論

目前已確認 wooo 在 Gitea 上以 user endpoint 可讀到 2 個 public repos：

wooo/awoooi
wooo/ewoooc

但未提供只讀 token 時，這只能代表 public-only 可見範圍，不等同完整 server-side repo list。要滿足「Gitea 目前所有專案版本都轉移到 GitHub」，仍需要下列其中一種來源：

Gitea 只讀 token。
Gitea 管理介面匯出的 repo list JSON。
由管理者在 Gitea 主機上產出的只含 repo metadata 的脫敏 JSON。

補充：orgs/wooo/repos 未認證查詢目前回 404，已保留於 docs/security/GITEA-ORG-REPO-INVENTORY-BLOCKED-SNAPSHOT.md。後續若確認 wooo 是 org 而非 user，應改用只讀 token 或管理匯出重新驗證。

上述兩條非 public-only 路徑都必須先走 docs/security/GITEA-READONLY-INVENTORY-APPROVAL-PACKAGE.md，不得在對話、文件或 LOGBOOK 中保存 token value。

S4.5 已補 gitea_authenticated_inventory_export_request_v1：正式要求 authenticated inventory 或 admin export 必須解釋 public-only 2 個 repos 與本機 Gitea remote 4 個 unique repos 的 coverage gap，且輸出仍只能是 gitea_repo_inventory_v1.status=ok evidence。

1. Public-only 快照指令

python3 scripts/security/gitea-repo-inventory.py \
  --base-url http://192.168.0.110:3001 \
  --org wooo \
  --scope user \
  --github-owner owenhytsai \
  --output-json docs/security/gitea-repo-inventory.snapshot.json \
  --output-md docs/security/GITEA-REPO-INVENTORY-SNAPSHOT.md

預期狀態：partial。

2. 只讀 token 快照指令

執行前必須先取得 approval_required_event_v1 批准。

GITEA_READONLY_TOKEN='<read-only-token>' \
python3 scripts/security/gitea-repo-inventory.py \
  --base-url http://192.168.0.110:3001 \
  --org wooo \
  --scope user \
  --github-owner owenhytsai \
  --output-json docs/security/gitea-repo-inventory.snapshot.json \
  --output-md docs/security/GITEA-REPO-INVENTORY-SNAPSHOT.md

注意：

Token 只放在環境變數，不寫入文件。
輸出只保存 token_present=true，不保存 token value。
若 token 有權限讀 private/internal repos，狀態才可視為 ok。

3. 管理匯出 JSON 格式

工具接受以下三種結構：

[
  {
    "full_name": "wooo/example",
    "name": "example",
    "owner": {
      "login": "wooo"
    },
    "private": true,
    "archived": false,
    "empty": false,
    "default_branch": "main",
    "clone_url": "http://192.168.0.110:3001/wooo/example.git",
    "ssh_url": "git@192.168.0.110:wooo/example.git"
  }
]

也接受：

{
  "repos": []
}

或：

{
  "repositories": []
}

4. 管理匯入指令

匯入前必須先確認 JSON 已 redacted，不含 token、password、webhook secret、deploy key private key 或 repository secret value。詳細檢查表見 docs/security/GITEA-ADMIN-EXPORT-REDACTION-CHECKLIST.md。

python3 scripts/security/gitea-repo-inventory.py \
  --base-url http://192.168.0.110:3001 \
  --org wooo \
  --github-owner owenhytsai \
  --input-json /path/to/redacted-gitea-repos.json \
  --output-json docs/security/gitea-repo-inventory.snapshot.json \
  --output-md docs/security/GITEA-REPO-INVENTORY-SNAPSHOT.md

預期狀態：ok，且 visibility_scope=admin_export。

5. 不可包含的資料

API token value。
Git remote URL 內嵌 username/password/token。
Webhook secret value。
Deploy key private key。
Repository secret value。
Cookie、session、personal access token。

6. 進入 GitHub migration 前的 gate

只有在 gitea_repo_inventory_v1.status=ok 後，才可以進入下一階段：

每個 repo 建立 GitHub target 決策。
每個 repo 產生 branch/tag SHA diff。
每個 repo 盤點 workflow / webhook / runner / secret 名稱。
每個 repo 建立 mirror / archive / keep-local 判定。
產出 GitHub primary ADR 與 rollback plan。

4.5 KiB Raw Blame History Unescape Escape