本週先依序確認 Mac 主機可達、Runner 服務狀態與 GitHub 連線，再檢查標籤和群組權限；不要一開始就刪除 Runner 並重新註冊。適用於主機重啟後 Runner 顯示 Offline，或雖已在線、工作流程仍無法接單的情況；只有代表性工作流程完成接單、建置及結果回傳驗收，才恢復生產派送。
負責 GitHub Actions 自托管 Runner 的平台工程師：用分層方式定位服務未啟動或無法連線的原因。
負責企業 Mac CI 的 IT 團隊：建立可重複執行的故障檢查與恢復驗收。
維護 iOS／macOS 發布流程的技術負責人：確認 Runner 在線不等於建置或發布已恢復。
主機無法連線，還是 Runner 應用離線？
GitHub 顯示 Offline 只表示 Runner 目前不能接單，不能單憑這個狀態判定是註冊故障。GitHub 列出的可能原因包括主機離線、Runner 應用未執行，或 Runner 無法與 GitHub 通訊。先把主機狀態和 Runner 狀態分開確認，才不會在主機根本無法連線時反覆處理 Runner 設定。GitHub 官方排障說明
依序核對：
- [ ] 在 GitHub 的 Runner 清單確認狀態及最後回報資訊。
- [ ] 透過團隊既有的遠端管理方式連線 Mac；同時查看主機監控、電源或機房紀錄。
- [ ] 若遠端連線也失敗，先處理主機啟動、網路路徑或遠端存取，不要直接刪除 Runner 記錄。
- [ ] 若主機可達，再進入 Runner 服務檢查；把主機正常與 Runner 正常分別記錄。
提醒：遠端桌面或 SSH 可連線，只能證明相應的主機存取路徑可用，不能證明 Runner 已啟動，更不能證明工作流程能成功建置。
使用者登入後才啟動，還是無人值守服務？
Mac 已重新啟動但 Runner 仍離線時，先確認 Runner 服務是否安裝、是否正在執行，以及服務採用哪種啟動上下文。macOS 的 LaunchAgent 與 LaunchDaemon 適用的執行上下文不同；若團隊的服務依賴使用者登入才載入，就不能把它當成無人登入時也會自動恢復的系統服務。Apple Service Management 文件
在 Runner 安裝目錄依 GitHub 的 macOS 服務說明檢查狀態：
./svc.sh status
如需啟動服務，先確認目前服務狀態與團隊維護流程，再依官方文件使用相應的服務命令；不要同時以多種方式啟動同一個 Runner。GitHub Runner 服務配置說明
若服務不存在或狀態與 GitHub 頁面不一致，檢查服務是否曾安裝、載入設定是否指向目前的 Runner 目錄，以及主機重啟後服務管理程序是否有錯誤紀錄。LaunchAgent 與 LaunchDaemon 的選擇應符合團隊的登入及服務管理設計；不要只為了讓狀態變綠，就把原本的使用者工作階段服務改成系統服務。
macOS launchd 的執行上下文如何核對？
先確認服務由誰啟動、是否依賴互動式登入，以及服務標籤對應的設定是否仍指向現有 Runner。再把服務管理紀錄與 GitHub Runner 狀態對照。若 Runner 以使用者工作階段執行，登出或重啟後的行為可能不同於系統層級服務；此時應修正服務部署方式或明確安排登入條件，而非把重新註冊當成通用解法。
進程已執行，為何 GitHub 仍顯示離線？
本機看到 Runner 進程，不代表它能連上 GitHub。接著確認 DNS 解析、出站網路路徑、代理設定及 TLS 握手；瀏覽器可以上網，也不能單獨證明 Runner 所需的端點都可用。若企業網路採用代理，需依 GitHub 文件確認 Runner 的代理設定與實際網路政策相符。GitHub 自托管 Runner 代理設定說明
Runner 進程在執行，排查從哪裡開始？
先從 Runner 的診斷紀錄找連線失敗原因，再由網路管理端確認 DNS、代理及 TLS 路徑。需要更詳細線索時，依 GitHub 指引啟用 Runner 診斷記錄，並把記錄時間與服務重啟時間、網路變更時間對照。GitHub 診斷記錄設定說明
檢查時不要關閉 TLS 驗證來「測試修復」。這會掩蓋憑證鏈或代理設定問題，並把原本的連線故障轉成安全風險。若紀錄指出連線問題，修正 DNS、代理政策或信任鏈後，再觀察 Runner 是否重新回報 Online。
若服務狀態正常、網路檢查仍失敗，保留診斷記錄與相關設定變更紀錄，再交由網路及平台負責人一起判讀；不要僅憑一次重新啟動就結案。
Runner 在線，工作流程為何仍留在佇列？
Runner 上線後，工作流程仍要符合排程條件才會派送。核對工作流程 runs-on 指定的標籤、Runner 實際標籤，以及 Runner group 的存取範圍；標籤不匹配或群組不允許該儲存庫使用時，這台 Runner 即使在線也不會承接該工作。GitHub Runner 工作流程選擇說明
- [ ] 對照工作流程中的
runs-on與 Runner 頁面顯示的標籤。 - [ ] 確認工作流程所屬儲存庫有權使用目標 Runner group。
- [ ] 若近期更動過標籤或存取政策，查看變更後的設定是否仍符合工作流程條件。GitHub Runner 標籤管理說明 GitHub Runner group 存取管理說明
- [ ] 對照 Runner 狀態、工作流程佇列與派送目標，確認問題屬於路由而非主機或連線。
若 Runner 記錄、Mac 上的服務設定與目前 Runner 名稱互相矛盾，再調查是否有舊記錄、重複服務或設定指向錯誤目錄。只有證據顯示 Runner 註冊本身異常時，才依官方流程移除並重新配置；先保留舊設定與診斷資料，避免把可修復的服務或網路問題變成新的註冊問題。GitHub Runner 配置說明
恢復在線後，怎樣確認工作流程可以接單？
不要把 Online 當作生產恢復的驗收結果。先挑選不會接觸正式簽名資產的代表性工作流程，逐項核對 Runner 是否接單、工作區是否可讀寫、必要工具是否可呼叫，以及工作結果是否回傳。通過後再依團隊發布門禁決定是否恢復正式派送；若只完成接單而建置或結果回傳失敗，仍應維持非生產狀態。
用哪個結果決定下一步？
| 現象 | 優先判斷 | 下一步 |
|---|---|---|
| Mac 無法遠端連線，Runner 顯示 Offline | 主機或遠端存取路徑 | 查主機啟動、網路及運維紀錄 |
| Mac 可連線，Runner 服務不存在或未執行 | 服務部署或啟動上下文 | 查服務安裝、launchd 設定與服務紀錄 |
| 服務執行，但 GitHub 仍顯示 Offline | 網路連線或 Runner 通訊 | 查診斷記錄、DNS、代理及 TLS |
| Runner Online，工作流程仍排隊 | 標籤或存取條件 | 比對 runs-on、Runner 標籤及群組權限 |
| 工作流程已接單但建置或回傳失敗 | 流水線本身尚未恢復 | 維持非生產派送，查工作區、工具及結果紀錄 |
| launchd 服務型態 | 核對重點 | 適用的判斷方式 |
|---|---|---|
| LaunchAgent | 是否依賴特定使用者工作階段 | 確認登入條件與服務載入狀態 |
| LaunchDaemon | 是否以系統層級服務方式管理 | 確認服務設定、啟動狀態及維護紀錄 |
| 驗收階段 | 必須取得的證據 | 未通過時的處置 |
|---|---|---|
| 主機可達 | 遠端連線結果與主機紀錄一致 | 先修復主機或存取路徑 |
| Runner 可通訊 | Runner 狀態與診斷記錄顯示連線恢復 | 繼續查 DNS、代理、TLS 或服務 |
| 工作流程可派送 | 目標標籤、群組權限及接單紀錄相符 | 修正路由條件，不重複註冊 |
| 建置與結果回傳成功 | 代表性任務完成，且結果可供團隊核驗 | 保持生產派送暫停，定位流水線故障 |
按故障範圍選擇修復路徑
- 若 Mac 本身不可達：先處理主機啟動、電源或遠端網路；否則回頭檢查 Runner 沒有實際意義。
- 若 Mac 可達但服務未運行：查服務安裝與 launchd 執行上下文；只有服務設定損壞或指向錯誤時，才重建服務。
- 若服務運行但 GitHub 顯示離線：查診斷記錄、DNS、代理與 TLS；不要略過憑證驗證。
- 若 Runner 在線但無法接單：先核對標籤和 Runner group 權限，不要刪除 Runner 記錄。
- 若工作流程接單但建置未通過：按流水線故障處理；Online 不是發布驗收。
- 若主機、服務和連線均正常，只有註冊資訊不一致：保存證據後，再評估是否重新配置 Runner。
對長期自行維護的 Mac 打包節點，團隊需自行承擔硬體採購與折舊、重啟後的值班處置，以及服務設定和網路政策的持續維護。若需求是短期增加遠端 Mac CI 容量，租用遠端 Mac 可讓團隊評估按需取得環境的方式，不必為短期需求先購置專用硬體；若工作負載長期固定且持續繁重，或必須直接使用特定實體介面，自購並管理本地 Mac 可能更合適。評估承載方式時，可先從MESHLAUNCH 的遠端 Mac 服務資訊確認可核對的交付與運維內容，再比較是否符合團隊的安全及恢復流程。評估 MESHLAUNCH 的遠端 Mac 方案時，也可查看遠端 Mac 方案頁面，並核對實際交付與運維資訊。