GitHub Enterprise Server 3.22 升級檢查：/repos、防火牆與 Dependabot
GitHub Enterprise Server 3.22.0 已在 2026 年 9 月 8 日正式推出。這次升級不能只確認 .pkg 能否安裝：/repos 路徑開始承載新功能、自訂 firewall rules 會在升級時被移除，既有 Dependabot 設定也有可能停止排程；HA 環境還要控制 primary、replica 與 maintenance mode 的順序。
直接結論是：先把路徑、防火牆、Dependabot 與複寫狀態保存成升級前證據，再決定是否使用 phased upgrade。完成安裝後，要逐項恢復設定並等待背景工作與複寫正常，才算升級完成。
本文的指令依 GitHub 官方文件整理，未在實際 GHES appliance 上執行。正式操作前仍要依來源版本、拓撲與 GitHub Support 建議製作 rollback 計畫。
升級前先盤點五個風險面
先建立一張有負責人、證據位置與 rollback 條件的表格：
| 檢查面 | 升級前證據 | 3.22 要注意的事 |
|---|---|---|
| 來源版本與套件 | ghe-version、目標 .pkg、官方 upgrade path | phased upgrade 只支援從 3.21 或更新版本開始 |
/repos 路徑 | reverse proxy、SSO、integration 與自訂路由清單 | 3.22 會用這個保留路徑提供新功能 |
| Firewall | 所有自訂規則、套用順序與外部備份 | 3.22 已知問題會在升級時移除自訂規則 |
| Dependabot | 使用排程 version updates 的 repository 與最近成功時間 | 升級前就存在的設定可能停止排程 |
| HA／cluster | primary、replica、replication status 與健康檢查 | primary 完成設定後才升 replica，期間維持 maintenance mode |
不要只把畫面截圖當成 firewall 備份。需要保留可重新套用的規則來源、變更紀錄與驗證請求；否則升級後即使知道規則消失，也無法確認恢復內容是否完整。
/repos 已是保留路徑，先找衝突再維護
GitHub 自 3.20 起已將 /repos 標示為保留路徑，3.22 開始用它提供新功能。若 reverse proxy、內部入口、GitHub App、webhook receiver 或其他 integration 仍把 /repos 導向自訂服務，升級後可能出現路由衝突。
升級前應搜尋：
- load balancer、WAF 與 reverse proxy 是否有
/repos的 rewrite 或 exception。 - 內部文件、監控探針與 automation 是否把
/repos當成自訂入口。 - 使用者、organization、GitHub App 或外部整合是否依賴會碰撞的名稱或路徑。
- 備援站與 staging appliance 是否套用相同 routing rules。
找到衝突時，先替自訂服務安排新路徑並驗證 consumer，再進 maintenance window。不要在升級過程才臨時改 proxy，否則 GitHub 版本變更與網路變更會混在同一個故障面。
來源是 3.21 以上，可考慮 phased upgrade
GHES 3.22 支援把部分工作放到 maintenance window 之前執行。官方指出 phased upgrade 最多可縮短約 20 分鐘的 maintenance 時間，但前提是來源版本至少為 3.21。
預先階段使用：
ghe-upgrade --phase pre-upgrade GITHUB-UPGRADE.pkg進入排定的 maintenance mode 後，再執行：
ghe-upgrade --phase upgrade GITHUB-UPGRADE.pkgGITHUB-UPGRADE.pkg 要換成已下載並核對的 upgrade package。若來源低於 3.21，或官方 upgrade path 要求先經過中繼版本，不要套用 phased 指令；依標準 feature upgrade 流程逐段執行。
phased upgrade 只是移動執行時點，不會省略 package signature、backup、maintenance mode、restart 或升級後驗收。若 pre-upgrade 階段失敗，先保存輸出與 /data/user/common/ghe-config.log，不要把失敗狀態直接帶進正式窗口。
維護窗口內的執行順序
單節點可依這個順序安排 runbook：
- 再次確認可用 backup、upgrade package、磁碟空間與 appliance health。
- 啟用 maintenance mode，確認一般使用者流量已停止。
- 執行標準 upgrade，或完成已預先執行的 phased upgrade 第二階段。
- 等待 appliance restart 與設定套用，確認
ghe-version已回報 3.22.x。 - 使用
ghe-check-background-upgrade-jobs查看背景工作，不要因 UI 已能登入就提前宣布完成。 - 檢查
/data/user/common/ghe-config.log、系統健康與核心 Git 操作，再進入已知問題的修復清單。
若升級失敗需要向 GitHub Support 送資料，可參考 GHES support bundle 上傳遭拒的分流方法，先分辨 bundle 建立、連線與上傳政策，避免重複產生無法送出的檔案。
升級後立刻處理兩個已知問題
1. 重新套用並驗證自訂 firewall rules
3.22.0 release notes 明列：升級期間自訂 firewall rules 會被移除。完成設定套用後，從升級前保存的受控來源重新套用規則，再驗證必要的 inbound、outbound、DNS、SMTP、storage、runner 與 identity provider 路徑。
不要只確認規則文字存在。至少執行一組允許與拒絕測試，並檢查是否有 emergency rule、臨時 exception 或順序差異未被恢復。
2. 檢查 Dependabot 排程是否繼續
另一個 3.22.0 已知問題是：升級前已存在的 .github/dependabot.yml，其 scheduled version updates 可能停止。先列出原本應在窗口後執行的 repository，對照最近一次成功更新與下一次排程。
若確定受影響，GitHub 官方 workaround 是對每個受影響的 .github/dependabot.yml 保存一項變更。建議透過可 review 的 PR 完成並記錄 repository 清單，合併後再觀察 Dependabot update log 與下一次排程；不要只批次碰檔案時間，因為那不會留下可稽核的設定變更。
HA 環境不要同時放行所有節點
HA 環境先升 primary。等 primary 的設定與背景工作達到官方流程要求後，再依序升級 replica；所有節點完成前保持 maintenance mode。可用以下兩個檢查作為 runbook 的固定證據：
ghe-versionghe-repl-status每個節點都應回報預期版本，replication 也要恢復 current。不要在 replica 還落後時先對外開站，否則使用者操作、複寫追趕與升級後背景工作會同時競爭資源。
3.22 升級完成條件
把「SSH 指令成功」改成下面這組完成定義：
- 所有 appliance 都回報預期的 3.22.x，背景升級工作已完成或有可追蹤的處理單。
/repos沒有 proxy、SSO、App 或 integration 路由衝突。- 自訂 firewall rules 已恢復，允許與拒絕路徑都有實際驗證結果。
- 受影響 repository 的 Dependabot 設定已保存變更，update log 或下一次排程可確認恢復。
- HA replica 已完成升級且 replication current，再關閉 maintenance mode。
- Git clone、push、web、API、Actions runner、package 與身份驗證都有 smoke test。
GHES 3.22 也帶來 air-gapped Copilot CLI technical preview 等新能力，但新功能驗收應和 appliance 升級拆成不同變更。先證明平台穩定，再用最小範圍評估 preview，才能保留清楚的故障邊界。
常見問題
Q: 從 GHES 3.20 可以直接用 phased upgrade 升到 3.22 嗎？
A: 不行直接套用本文的 phased 指令。官方文件要求來源版本至少是 3.21；3.20 應先依 Upgrade Assistant 與官方 upgrade path 確認中繼版本，再安排各階段窗口。
Q: 升級成功後，firewall rules 會自動恢復嗎？
A: 3.22.0 release notes 將自訂 firewall rules 被移除列為已知問題，因此 runbook 必須包含外部備份、重新套用與連線驗證，不能假設自動恢復。
Q: Dependabot 沒有準時開 PR，就一定是 3.22 的已知問題嗎？
A: 不一定。先看 update log、排程、repository 權限與設定語法；只有在升級前可正常執行、升級後既有排程停止時，才依官方 workaround 保存一項可審查的設定變更並再次觀察。
參考資料：
GitHub Changelog：GitHub Enterprise Server 3.22 is generally available
回報錯字、失效連結，或告訴我你想看的延伸主題。