GitHub Secret 設定與驗證步驟

目的

本文件說明 DOCS_REPO_DISPATCH_TOKEN 的用途、建立方式、設定位置與驗證方式。

目前文件網站的「目前開發狀態」會讀取文件 repo 內的 status.json。因為程式 repo 與文件 repo 分開，且程式 repo 可能不是公開 repo，所以不能讓公開靜態網頁直接讀 GitHub API 取得最新 commit。

程式 repo push
  -> 程式 repo GitHub Actions 使用 DOCS_REPO_DISPATCH_TOKEN
  -> 通知文件 repo 觸發 repository_dispatch
  -> 文件 repo GitHub Actions 更新 status.json
  -> 文件 repo commit 新狀態
  -> Cloudflare Pages 自動重新部署
  -> 首頁顯示最新開發狀態

Secret 名稱

Secret 必須建立在程式 repo：

Hongsen-tw/hs-device-control-template

Secret 名稱固定為：

DOCS_REPO_DISPATCH_TOKEN

Token 建議權限

建議使用 GitHub Fine-grained personal access token，授權目標為：

Hongsen-tw/hs-device-control-template-docs

權限	設定	用途
Metadata	Read	GitHub API 基本 repo 讀取需求
Contents	Read and write	允許文件 repo workflow 後續寫入 `status.json`

若 GitHub 畫面有提供 Actions 或 Workflows 相關權限，可保持最小權限原則，只開啟觸發 dispatch 所需的權限。

設定位置

進入程式 repo：

https://github.com/Hongsen-tw/hs-device-control-template

Settings
  -> Secrets and variables
  -> Actions
  -> New repository secret

欄位	內容
Name	`DOCS_REPO_DISPATCH_TOKEN`
Secret	GitHub personal access token 的實際值

注意：Token 只貼到 GitHub Secret，不要寫入 repo、文件、程式碼或 commit 訊息。

驗證方式

設定完成後，做一次程式 repo push，例如在 poc/nmodbus-tcp 分支更新一個小文件或後續程式 commit。

程式 repo 的「通知文件 repo 更新開發狀態」workflow 執行成功。
文件 repo 的「同步程式 repo 開發狀態」workflow 被觸發。
文件 repo 產生新的 commit，commit 訊息為 同步程式 repo 開發狀態。
status.json 與 public/status.json 的 source 變成 github-actions。
Cloudflare Pages 重新部署後，首頁「目前開發狀態」顯示最新 commit。

可檢查公開狀態檔：

https://hs-device-control-template-docs.pages.dev/status.json

常見問題

首頁仍顯示舊 commit

Cloudflare Pages 尚未完成部署。
瀏覽器快取尚未更新。
程式 repo 的通知 workflow 失敗。
文件 repo 沒有收到 repository_dispatch。
DOCS_REPO_DISPATCH_TOKEN 尚未設定，或 token 權限不足。

`source` 仍是 `manual-seed`

代表目前顯示的是手動建立的初始狀態，尚未完成自動同步。完成 Secret 設定並測試 push 後，成功時 source 應改為 github-actions。

Token 過期或被撤銷

重新建立 token，並覆蓋程式 repo 內同名 Secret，不需要修改 workflow 檔案。

維護規則

不得將 token 寫入任何 repo 檔案。
不得把 token 貼在 issue、PR、commit message 或公開對話中。
若懷疑 token 外洩，立即撤銷並重建。
若文件 repo 名稱或 owner 改變，需同步調整程式 repo 的通知 workflow。

目的