CI/CD 與治理

本儲存庫使用四個 GitHub Actions 工作流程及一套集中式範本系統進行治理。

工作流程

工作流程	檔案	觸發條件	用途
GitHub Pages 部署	`github-pages-deploy.yml`	推送至 `main`（`docs/**`）、手動觸發	建置並部署文件網站至 GitHub Pages
建置並發佈 Docker 映像	`build-image.yml`	推送至 `main`（`docker/*`、`package.json`）、每日排程、`repository_dispatch`	建置 Docker 映像、推送至 GHCR，並觸發下游儲存庫重新建置
要求關聯 Issue	`require-linked-issue.yml`	Pull request 事件	阻擋未引用 GitHub issue 的 PR
強制執行儲存庫設定	`enforce-repo-settings.yml`	每 6 小時、推送至設定檔、手動觸發	從範本套用標準化的儲存庫設定

GitHub Pages 部署

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
  workflow_dispatch:

委派至範本儲存庫中的可重用工作流程：

jobs:
  docs:
    uses: f5-sales-demo/docs-control/.github/workflows/github-pages-deploy.yml@main

權限：contents: read、packages: read、pages: write、id-token: write。使用並行群組 pages 並設定 cancel-in-progress: true 以避免過時的部署。

僅在 docs/ 下的檔案變更時於推送時觸發。也可透過 workflow_dispatch 手動觸發，這也是 build-image.yml 中的 dispatch 工作觸發下游重新建置的方式。

建置並發佈 Docker 映像

on:
  push:
    branches: [main]
    paths:
      - 'docker/**'
      - 'package.json'
      - 'package-lock.json'
  schedule:
    - cron: '0 6 * * *'
  repository_dispatch:
    types: [rebuild-image]

步驟：

檢出程式碼
使用 docker/login-action 登入 ghcr.io
使用 docker/build-push-action 建置並推送，上下文為 .，Dockerfile 為 docker/Dockerfile
標籤：ghcr.io/<owner>/<repo>:latest 和 ghcr.io/<owner>/<repo>:<sha>

成功建置後，dispatch 工作會透過 workflow_dispatch 觸發範本儲存庫 downstream-repos.json 設定中列出的每個下游儲存庫的 github-pages-deploy.yml。這確保所有內容儲存庫使用更新後的建置映像重新建置其文件。

每日排程確保即使沒有程式碼變更，映像仍保持最新狀態（取得相依套件更新）。repository_dispatch 事件允許外部系統觸發重新建置。

僅在 docker/ 檔案或 package*.json 變更時於推送時觸發。僅文件的變更不會觸發映像重新建置。

要求關聯 Issue

on:
  pull_request_target:
    types: [opened, edited, reopened, synchronize]

使用 nearform-actions/github-action-check-linked-issues@v1 來強制要求每個 PR 引用一個 GitHub issue（例如在描述中寫 Closes #42）。Dependabot PR 透過以下設定排除：

exclude-branches: "dependabot/**"

如果檢查失敗，會顯示自訂訊息告知貢獻者預期的格式。請參閱 CONTRIBUTING.md 了解完整的貢獻者工作流程。

強制執行儲存庫設定

on:
  schedule:
    - cron: '0 */6 * * *'
  push:
    branches: [main]
    paths:
      - '.github/config/repo-settings.json'
  workflow_dispatch:

委派至範本儲存庫中的可重用工作流程：

jobs:
  enforce:
    uses: f5-sales-demo/docs-control/.github/workflows/enforce-repo-settings.yml@main
    secrets:
      repo-admin-token: ${{ secrets.REPO_ADMIN_TOKEN }}

每 6 小時及設定檔變更時執行。從 .github/config/repo-settings.json 套用分支保護規則、合併設定及其他儲存庫組態。

治理模型

集中式範本

f5-sales-demo/docs-control 儲存庫是以下項目的單一事實來源：

可重用工作流程定義（文件部署、儲存庫設定強制執行）
同步至組織內所有儲存庫的受管理檔案
標準組態與分支保護規則

此建置器及所有內容儲存庫均從範本繼承其 CI/CD 行為。

受管理檔案同步

範本儲存庫可將受管理檔案（如工作流程定義和設定檔）推送至下游儲存庫。這使所有儲存庫保持一致，無需手動更新。同步透過範本儲存庫中的獨立工作流程執行。

分支保護

enforce-repo-settings 工作流程從範本套用分支保護規則，包括：

合併前要求通過狀態檢查
要求關聯 issue 檢查
偏好壓縮合併（squash merge）
合併後自動刪除來源分支

密鑰

密鑰	來源	用途
`GITHUB_TOKEN`	自動（GitHub）	大多數工作流程用於檢出、套件發佈及 API 呼叫
`REPO_ADMIN_TOKEN`	手動（儲存庫密鑰）	enforce-repo-settings 和 dispatch 工作所需，用於修改分支保護、儲存庫設定及觸發下游工作流程（需要管理員權限範圍）