actions/labeler：依檔案路徑與分支名稱自動標記拉取請求
自動標記拉取請求的操作。 V7 中的變更內部遷移到 ESM 以支援最新的 @actions/* 軟體包版本。
秒懂
- 它是什麼？
- 一個 GitHub Action，根據變更檔案或分支名稱向拉取請求新增標籤。
- 適合誰用？
- actions/labeler 適合能依 README 指定的環境、輸入與權限來操作的人，不適合把未列出的相容性或營運保證當成既定事實。先用官方 README 的入口，在隔離環境記錄命令、設定、輸出與錯誤，再決定是否擴大資料和權限範圍。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 3 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月14日）與我們的分析，不構成法律意見。
開源專案深度解析
這個 Action 做什麼
actions/labeler 是一個 GitHub Action，會自動為拉取請求新增標籤。它根據變更檔案的路径或基礎分支/頭部分支的名稱來決定標籤。標籤定義儲存在 .github/labeler.yml 檔案中。版本 7 在內部遷移到 ESM，以支援最新的 @actions/* 套件，但 README 說明輸入、輸出與行為沒有變化。
actions/labeler 的 README 把「An action for automatically labelling pull requests. What's changed in V7 Migrated to ESM internally to support the latest @actions/* package versions.」放在核心位置。這表示讀者首先要確認的是專案實際處理的輸入、執行入口和產物，而不是只根據倉庫星標或宣傳語句推估能力。README 沒有說明的效能、相容性與安全結果，本文不替它補成承諾。
從 actions/labeler 的使用邊界來看，TypeScript 與 main 分支只是定位線索。把 README 中的命令、檔案名稱和外部服務分開記錄，才能在錯誤發生時分辨是環境、依賴、權限還是專案本身的行為。
設定檔的結構
labeler.yml 將標籤名稱對應到匹配物件。匹配物件可以使用四種 glob 模式檢查變更檔案：any-glob-to-any-file、any-glob-to-all-files、all-globs-to-any-file 與 all-globs-to-all-files。它也可以使用正規表示式檢查 base-branch 與 head-branch。頂層鍵 any 或 all 控制是否必須匹配所有列出的規則。如果未提供頂層鍵，則預設使用 any。README 展示了範例，例如為 docs/ 下的變更新增 Documentation 標籤，或為以 feature 開頭的頭部分支新增 feature 標籤。
actions/labeler 的最小檢查應以官方 README 出現的入口開始，保留實際命令與返回訊息，並對照生成檔、日誌或介面結果。若流程涉及憑證、網路或資料庫，先用隔離帳號與非敏感資料；對只在文件中宣稱、卻沒有範例或數據支持的能力，應維持不確定判斷。
布林組合與路徑排除
匹配物件可以巢狀在 any 與 all 下，用布林邏輯組合條件。頂層物件與 all 內的選項是 AND 關係，any 內的規則是 OR 關係。路徑 glob 可以使用 ! 取反實現排除。例如，source 標籤可以使用 all 區塊，其中包含 any-glob-to-any-file 與 all-globs-to-all-files 配合取反模式，匹配 src/** 下除 src/docs/* 之外的所有檔案。README 也提到 dot 輸入控制是否匹配點開頭的檔案，在版本 5 及之後預設值為 true。
授權標示為 MIT。對 actions/labeler 而言，這只回答程式碼如何再散布或修改，沒有替部署支援、資料責任、第三方依賴與安全維護背書。正式導入仍要把倉庫內容與實際環境的權限、備份和升級方式分開核對。
限制標籤數量與跳過大型 PR
labeler.yml 中有兩個頂層選項用於控制大量標籤。changed-files-labels-limit 限制基於變更檔案規則可新增的新標籤數量。如果新變更檔案標籤的數量超過限制，本次執行會跳過所有新的變更檔案標籤；僅基於分支的標籤不受影響。max-files-changed 在變更檔案總數超過閾值時跳過所有基於檔案的標籤。任何包含 changed-files 規則的標籤定義都被視為變更檔案標籤，即使它透過分支規則匹配。當 max-files-changed 觸發時，已有標籤會被保留。
工作流程設定與輸入
要使用此 Action，請建立使用 pull_request_target 事件的工作流程，並設定 contents: read 與 pull-requests: write 權限。預設情況下，Action 從 .github/labeler.yml 讀取設定，但 configuration-path 可以指向其他檔案，該檔案可以在執行器上，也可以透過 GitHub API 從儲存庫讀取。sync-labels 輸入為 true 時，會移除不再匹配的已設定標籤，但絕不會觸碰未在設定中列出的標籤。pr-number 輸入可接受一個或多個 PR 編號，用於排程執行，而不是從上下文偵測。
輸出與權限需求
Action 提供兩個輸出：new-labels 與 all-labels，分別是以逗號分隔的新增標籤列表與執行後 PR 包含的所有標籤列表。這些輸出可在後續工作流程步驟中透過條件使用。權限取決於標籤是否已存在：新增已有標籤需要 pull-requests: write，建立新標籤需要 issues: write。對於來自 fork 的 pull_request 事件，GitHub 最多只授予唯讀權杖，因此 README 建議使用 pull_request_target 以獲得寫入權限，同時警告必須小心使用該事件，避免執行不可信程式碼。
版本變化、pull_request_target 注意事項與授權
版本 6 將執行時期升級到 Node.js 24，並要求執行器版本 v2.327.1 或更高。版本 5 引入了分支匹配、更改了設定結構、修復了 sync-labels 並將 dot 預設設為 true。使用 pull_request_target 時，首次新增 labeler 的 PR 不會執行工作流程，因為該事件從基礎分支執行。更新 labeler 版本時，如果基礎分支仍使用舊設定，可能會導致失敗；暫時改用 pull_request 可以驗證相容性。專案以 MIT 授權釋出，授予使用、複製、修改與散布權利，軟體按原樣提供，不附帶任何保證。
編輯結論
actions/labeler 適合能依 README 指定的環境、輸入與權限來操作的人，不適合把未列出的相容性或營運保證當成既定事實。先用官方 README 的入口，在隔離環境記錄命令、設定、輸出與錯誤，再決定是否擴大資料和權限範圍。
社群筆記