# GitHub Secret 設定與驗證步驟

## 目的

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

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

因此採用以下流程：

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

## Secret 名稱

Secret 必須建立在程式 repo：

```text
Hongsen-tw/hs-device-control-template
```

Secret 名稱固定為：

```text
DOCS_REPO_DISPATCH_TOKEN
```

## Token 建議權限

建議使用 GitHub Fine-grained personal access token。

Token 授權目標：

```text
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：

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

依序進入：

```text
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。

預期結果：

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

可檢查公開狀態檔：

```text
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` 應改為：

```text
github-actions
```

### Token 過期或被撤銷

重新建立 token，並覆蓋程式 repo 內同名 Secret：

```text
DOCS_REPO_DISPATCH_TOKEN
```

不需要修改 workflow 檔案。

## 維護規則

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