Dependabot 分支名稱怎麼改？用 pull-request-branch-name 對齊 CI

pull-request-branch-name 可以控制什麼#

官方文件目前列出六個選項：

Dependabot 原本常見的格式是 dependabot/PACKAGE-MANAGER/DEPENDENCY。先確認你的 CI、branch protection 與 release 工具依賴的是哪一段，再決定要改單一選項，還是直接使用 template。

先用基本選項配合現有 CI#

在 .github/dependabot.yml 的特定 update 設定下加入 pull-request-branch-name：

1
version: 2
2

3
updates:
4
  - package-ecosystem: npm
5
    directory: "/"
6
    schedule:
7
      interval: weekly
8
    pull-request-branch-name:
9
      prefix: "deps"
10
      separator: "-"
11
      word-separator: "-"
12
      branch-name-case: lowercase
13
      max-length: 64

例如原本的 dependabot/npm_and_yarn/Lodash-4.17.21，套用前綴、分隔符號與大小寫後，會往 deps-npm-and-yarn-lodash-4.17.21 的方向改變。不要只看單一套件的結果；monorepo、grouped update 與不同 package manager 會產生不同的內容。

如果 CI 使用 dependabot/** 這類 glob，改掉 separator 或 prefix 後，要同步檢查 workflow 的 branches、branches-ignore、if 條件與部署腳本。先找出依賴舊格式的地方：

1
rg -n \
2
  'dependabot[/_-]|branches(-ignore)?:|head_ref|base_ref' \
3
  .github scripts Makefile 2>/dev/null

這個搜尋只是定位，不能取代實際建立一個 Dependabot PR 後的驗證。完成設定後，應確認 branch filter、required checks 與自動合併規則都仍然命中。

需要固定格式時再用 template#

如果團隊需要把 package manager、依賴名稱與版本放在固定位置，可以使用 placeholders：

1
pull-request-branch-name:
2
  template: "deps/{package_manager}/{dependency}-{version}"
3
  separator: "-"
4
  branch-name-case: lowercase
5
  max-length: 80

可用 placeholder 會依 update strategy 而變化，常見的有 {package_manager}、{directory}、{target_branch}、{dependency}、{version}、{group_name} 與 {name}。不要把所有 placeholder 當成任何策略都能用；例如 multi-ecosystem group 沒有單一 package manager，使用 {package_manager} 會造成驗證錯誤。

另外，template 產出的結果仍必須是合法 Git reference。空白、~、^、:、?、*、[、反斜線，以及 .. 或 @{ 等形式都不能出現在分支名稱中。設定檔可以先通過 YAML 解析，卻在 Dependabot 產生 PR 時才暴露格式問題，所以要保留一個實際 PR 的驗收步驟。

長度限制不是單純刪字串#

max-length 的範圍是 20 到 244，超過限制時 Dependabot 會截短分支名稱並附加 hash suffix 以維持唯一性。這代表你不能假設「前 40 個字元相同，就一定是同一條分支」，也不能把截短後的尾端當成完整版本號。

Grouped update 與 multi-ecosystem group 還可能自動加入 10 字元 digest 來確保唯一性，這段不是使用者可以控制的。若外部系統有嚴格長度限制，應把 prefix、template 與 max-length 一起測試，而不是只把最大長度調到最小。

上線前的驗證順序#

1. 先在一個測試 repository 套用設定，保留舊版與新版分支範例。
2. 用一個單獨更新和一個 grouped update 檢查產出的格式；若使用 multi-ecosystem group，也要另外測試。
3. 檢查 Actions 的 branch filter、PR label、required check 與自動合併條件。
4. 確認分支長度、Git reference 合法性與截短後的唯一性。
5. 最後才把同一份設定推廣到其他 repository。

如果你同時在調整 Dependabot 的更新節奏，先把命名變更和 Dependabot cooldown 的安全邊界 分成不同 PR。這樣未來 CI 失效時，才知道是分支名稱改變，還是更新排程與安全修補策略造成的。

Dependabot 分支命名的重點不是做出最漂亮的字串，而是讓 CI、審查與自動化都能穩定辨認它。先以基本選項降低變更面，只有在命名規則真的需要時才使用 template，並用實際 PR 驗證完整流程。

常見問題#