同步管線 (Sync Pipeline)¶

概述¶

sync-docs.sh 是 ekkorn-doc 的核心腳本，負責從所有 repo 拉取 docs/ 目錄並聚合至 site/docs/，供 MkDocs 建置靜態網站。

運作原理¶

repos.yml (repo 清單)
    │
    ▼  yq 解析
遍歷每個 repo：
    │
    ├─ git clone --depth 1 --sparse (只拉取 metadata)
    ├─ git sparse-checkout set docs/ (只下載 docs 目錄)
    ├─ cp -r docs/ → site/docs/<name>/
    └─ 失敗時記錄，繼續處理下一個
    │
    ▼
rsync workspace/docs/ → site/docs/workspace/ (排除 workspace-sync.md)
    │
    ▼
完成，回報失敗數量（若有則 exit 1）

關鍵設計決策¶

Sparse checkout：避免完整 clone 整個 repo，只拉取 docs/ 目錄，節省頻寬
Fail-and-continue：單一 repo 同步失敗不中斷整個流程，最後彙報失敗清單
workspace-sync.md 排除：此檔案為內部流程文件，不需出現在公開靜態網站中

repos.yml 格式¶

repos:
  - name: app-server          # 必填：site/docs/ 下的子目錄名稱
    github: SHOW-YOU-APP/app-server  # 必填：GitHub repo 路徑
    docs_path: docs            # 選填：預設 "docs"
    branch: master             # 選填：預設 "main"

新增 repo 流程¶

在目標 repo 中建立 docs/ 目錄並放入文件
編輯 scripts/repos.yml，新增一筆記錄
（選擇性）更新 site/mkdocs.yml 的 nav 區塊
提交 PR，合併後下次 CI 自動同步

GitHub Actions 觸發條件¶

定義於 .github/workflows/sync-and-build.yml：

觸發方式	條件
排程	每天 UTC 19:00（台灣凌晨 3 點）
Push	`main` 分支，且變更了 `workspace/`、`site/mkdocs.yml`、`scripts/repos.yml`、workflow 自身
手動	GitHub Actions UI → workflow_dispatch

認證¶

CI 環境：透過 GH_TOKEN 環境變數注入 Fine-grained PAT（DOCS_PULL_TOKEN secret），對所有 repo 需有 Contents: Read 權限
本地環境：若 repo 為公開則不需 token，私有 repo 需設定 GH_TOKEN 環境變數

錯誤處理¶

Clone 失敗：記錄 repo 名稱，繼續處理下一個，最終 exit 1
Sparse checkout 失敗：同上
docs/ 不存在：印出警告，略過（不計入失敗）
yq 未安裝：立即 exit 1 並提示安裝方式