GitHub Actions 組織 Workflow Template：用 .github 統一新專案 CI 起點

Workflow Template 和其他重用方式有什麼不同？#

Template 適合「讓新專案少走彎路」；reusable workflow 適合「讓所有專案執行同一套中央流程」。兩者可以一起用：Template 只負責產生 caller workflow，caller 再呼叫中央 reusable workflow。

如果 caller 需要傳遞 secrets，先對照站內的 secrets: inherit 與 reusable workflow 權限檢查；如果重點是限制誰能觸發 workflow，則應另外閱讀 workflow execution protections 的 ruleset 設計。

先建立組織的 .github repository#

GitHub 官方流程的第一步，是在 organization 中建立一個名稱正好為 .github 的 repository。接著在該 repository 建立：

1
.github/
2
└── workflow-templates/
3
    ├── zeroone-node-ci.yml
4
    └── zeroone-node-ci.properties.json

如果需要自訂圖示，再把 SVG 放在同一個 workflow-templates 目錄，並在 metadata 的 iconName 參照檔名（不含副檔名）。也可以使用 GitHub 支援的 Octicon；不需要為了 template 另建一個公開 action repository。

Workflow 檔案：把安全預設放進起點#

以下 zeroone-node-ci.yml 是一個可再依組織 Node／pnpm 規範調整的起始檔案：

1
name: Organization Node CI
2

3
on:
4
  push:
5
    branches: [$default-branch]
6
  pull_request:
7
    branches: [$default-branch]
8

9
permissions:
10
  contents: read
11

12
jobs:
13
  check:
14
    runs-on: ubuntu-latest
15
    steps:
16
      - name: Check out repository
17
        uses: actions/checkout@v6
18

19
      - name: Enable Corepack
20
        run: corepack enable
21

22
      - name: Set up Node.js
23
        uses: actions/setup-node@v6
24
        with:
25
          node-version: '22'
26
          cache: pnpm
27

28
      - name: Install dependencies
29
        run: pnpm install --frozen-lockfile
30

31
      - name: Run checks
32
        run: pnpm check

$default-branch 是 GitHub workflow template 的特殊 placeholder；建立 workflow 時會替換成該 repository 的 default branch。它不是 shell 變數，也不是要在 template repository 先填成 main。若組織有不同的 package manager、Node 版本或檢查命令，應在 template 裡明確寫出規範，不要要求每個新專案建立後再猜。

範例用固定的 Node 22 當作組織起點，避免把 package manager 版本誤當成 Node 版本。如果各 repository 以 .nvmrc、.node-version 或 package.json 的 Node 欄位管理 runtime，應把 template 的 node-version 改成相應的 node-version-file，並把這個檔案契約寫進新專案規範。這也是 Template 需要先在代表性 repository 試跑的原因：起點一致不等於所有專案的 runtime 契約相同。

Metadata：讓 template 出現在正確的清單#

metadata 檔案必須和 workflow 使用相同的基本檔名，副檔名則改成 .properties.json：

1
{
2
  "name": "ZeroOne Node CI",
3
  "description": "Install pnpm dependencies and run the repository checks.",
4
  "iconName": "octicon code",
5
  "categories": [
6
    "JavaScript",
7
    "TypeScript"
8
  ],
9
  "filePatterns": [
10
    "package.json$",
11
    "^pnpm-lock[.]yaml$"
12
  ]
13
}

這幾個欄位的用途是：

• name 和 description：建立 workflow 時顯示給使用者看的文字。
• iconName：可使用 workflow-templates 內的 SVG，或 GitHub 支援的 Octicon。
• categories：使用 starter-workflows 的一般分類、Linguist language 或支援的 tech stack 名稱。
• filePatterns：只在 repository root 有檔案符合正規表示式時，讓 GitHub 推薦這個 template。

filePatterns 是推薦條件，不是安全控制，也不是 workflow trigger。它不會阻止使用者手動選擇 template，更不會代替 workflow 裡的 dependency、Node 版本和權限檢查。

從 GitHub UI 使用組織 Template#

檔案放進組織 .github/workflow-templates 後，成員在 repository 的 Actions 頁面建立新 workflow 時，就能看到組織提供的 template。建議先用一個測試 repository 驗證：

1. repository 的 default branch 名稱不是 main 時，確認 $default-branch 被替換成正確值。
2. 有 package.json 和 pnpm-lock.yaml 時，確認 filePatterns 讓 template 出現在合理的推薦位置。
3. 建立後打開實際產生的 .github/workflows/*.yml，確認 placeholder 已被替換、YAML 結構正確。
4. 在沒有 secrets 的分支先執行 CI，確認 contents: read 足以支援 checkout 與檢查。
5. 檢查組織 Actions policy 是否允許 actions/checkout、actions/setup-node 或 template 內使用的其他 action。

建立後的 workflow 是 repository 自己的檔案。日後修改 .github repository 裡的 template，不會自動修改已經被複製到各專案的 YAML；這個邊界要在 template description 和團隊文件中明確說出來。

需要中央更新時，改用 Reusable Workflow#

如果目標是讓 security check、部署 approval 或 runtime patch 能集中更新，可以讓 template 產生一個 caller：

1
name: Organization controlled CI
2

3
on:
4
  push:
5
    branches: [$default-branch]
6
  pull_request:
7
    branches: [$default-branch]
8

9
permissions:
10
  contents: read
11

12
jobs:
13
  ci:
14
    uses: example-org/platform-workflows/.github/workflows/node-ci.yml@<commit-sha>
15
    permissions:
16
      contents: read

上例把真正的 job 放在另一個 repository 的 reusable workflow，Template 只提供呼叫入口。生產環境應使用受信任的 commit SHA，並在 platform repository 建立 review、測試和變更紀錄；使用 mutable branch 或 tag 會讓 caller 取得未預期的 workflow 版本。

若 reusable workflow 放在 private repository，組織還要設定哪些 private repositories 可以存取它。GitHub 也提醒，允許其他 repository 使用 private action／workflow 時，外部協作者可能透過 workflow log 間接看到該 private repository 提供的內容，因此不能把「共享」當成自動安全隔離。

Template 的安全預設清單#

把 template 當成供應鏈入口，而不是漂亮的 YAML 範本。至少做這些檢查：

• 預設 GITHUB_TOKEN 只開啟 job 真正需要的 permission，CI 起點通常從 contents: read 開始。
• 不要在 template 中放 organization secret、API key、registry token 或示範用的真實值。
• 第三方 action 在穩定後 pin 到受信任的 commit SHA，並安排升級窗口。
• filePatterns 只負責推薦，不要把它當作「只有某類 repository 才能執行」的邏輯。
• 如果 template 會呼叫 reusable workflow，把 caller、called workflow、secret 傳遞和 permission 寫成一份測試案例。
• 若組織啟用了 workflow execution protections，確認新 template 的觸發事件不會被政策意外擋下，或反過來繞過應有的人工核准。

這樣的設計可以把新專案的起點標準化，同時保留 repository 對自身程式碼和部署流程的 ownership。Template 解決複製起點，Reusable Workflow 解決中央執行；不要用其中一個工具假裝另一個工具的生命週期。

常見問題#