GitHub Actions macOS Runner 離線怎麼辦?2026 排障指南

GitHub Actions macOS Runner 離線怎麼辦?2026 排障指南

Runner 顯示離線、工作流一直排隊,或任務剛啟動就失敗?
本週先按症狀分流:離線查主機與網路,在線未接單查標籤和群組,已啟動後失敗則對照工作流與 Runner 日誌;只有確認主機可用性或維護能力不足,才評估更換 Mac 執行環境。

適合維護 GitHub Actions macOS 自託管 Runner、需要排查 iOS 建置佇列的開發者與 CI 工程師。
若你負責決定團隊是否繼續自管 Mac 節點,也能據此區分設定錯誤與主機維運問題。

GitHub Actions macOS Runner 離線、排隊與失敗:先分清狀態

Runner 狀態與工作流任務狀態是兩個不同的觀察點。先查看 GitHub 介面上的 Runner 狀態,再確認工作流停在等待、已開始執行,還是執行後失敗;記下最近一次成功執行及故障發生時間,才容易把症狀和日誌對上。

你看到的現象 優先檢查 定位把握
Runner 顯示離線 Mac 主機、Runner 程式、GitHub 網路連線 高:狀態直接指出 Runner 未連線
Runner 在線但工作流排隊 runs-on 標籤、Runner 群組與存取權限 高:檢查路由條件是否吻合
任務已開始,之後才失敗 工作流日誌、Runner 診斷日誌、建置環境 中:需按錯誤發生階段分辨責任範圍

GitHub 將 Runner 的連線狀態與工作流路由分開處理;官方 Runner 狀態與排障說明可協助你確認離線狀態的定義與排查入口。工作流排隊則不等同於 Runner 離線:只要沒有符合路由條件、可接單的 Runner,任務就可能無法開始。

注意:不要只憑「排隊很久」就重啟 Mac。先確認該 Runner 是否在線,以及它是否符合工作流的路由條件;否則重啟只會增加一次中斷,未必改變任務能否被派送。

Runner 離線:由主機、程式到網路逐層檢查

離線時,先確認 Mac 是否仍開機並可連線,再檢查 Runner 程式或服務是否在執行。主機能透過 SSH 登入,不代表 Runner 已成功連到 GitHub;反過來,Runner 暫時離線也不一定表示整台主機故障。

可依序檢查:

GitHub 提供的網路檢查適合用來驗證 Runner 主機的連線能力;若檢查失敗,應沿著報告中的連線項目追查網路設定。不要把關閉 TLS 憑證驗證當成一般修復方式,因為那會掩蓋憑證或代理伺服器問題,並降低連線安全性。

Runner 在線但沒有接單:比較標籤與群組條件

Runner 顯示在線,只能說明它已與 GitHub 建立連線;工作流能否交給它,仍取決於 runs-on 條件、Runner 標籤及群組權限。這類情況應先查工作流路由,而不是先重裝 Runner 或更換主機。

打開失敗或排隊中的工作流設定,逐項比對 runs-on 指定的標籤與 Runner 頁面實際顯示的標籤。再確認該 Runner 所屬群組是否允許此儲存庫或組織使用。GitHub 的自託管 Runner 路由規則說明了標籤如何參與工作分派;工作流中的標籤與 Runner 群組設定及群組存取權限文件則可用來核對工作流是否有權使用目標 Runner。

常見的誤判,是只確認 macOS 這類作業系統標籤,卻忽略工作流要求了另一個自訂標籤;或標籤吻合,但 Runner 群組並未授權該儲存庫。請以目前儲存庫或組織的實際設定為準,不能僅憑另一個專案的 YAML 推定路由相同。

重啟後失聯:確認 launchd 管理的是服務而非手動程序

手動在終端機啟動 Runner 後能正常工作,不代表重啟 Mac 後它會自動恢復。若問題在重新開機、登出或終端機關閉後出現,應確認 Runner 是否已透過 macOS 的 launchd 以服務方式安裝,並檢查服務的啟動帳戶與狀態。

在 Runner 安裝目錄依照GitHub 的 macOS Runner 服務設定文件查看服務狀態,使用文件列出的服務管理方式啟動或停止服務。若服務狀態不符合預期,再對照 launchd 日誌與 Runner 服務日誌,確認服務是否因帳戶、權限或啟動錯誤而退出。

完成調整後,請驗證服務本身能維持執行,並確認 GitHub 介面中的 Runner 狀態同步恢復。若只在登入使用者的終端機內執行 Runner,登出或終端機結束就可能中斷這個互動式程序;這不等於 launchd 服務已修復。

提醒:服務以哪個帳戶安裝,會影響它能讀取的金鑰、憑證與專案檔案。服務能啟動但建置失敗時,應比較互動式執行與服務執行所使用的環境和權限,而不是假設兩者完全一致。

任務已啟動卻失敗:按故障時間對照兩種日誌

如果 GitHub 顯示任務已開始執行,問題就不再是單純的 Runner 離線或找不到可用節點。先打開工作流執行日誌,找出第一個實際失敗的步驟,再以該時間點對照 Runner 安裝目錄中的診斷日誌。

錯誤訊息、Runner 版本和 macOS 環境都可能影響排查結果,應以目前官方文件及你實際取得的日誌為準。不要只因工作流在另一台機器成功,就預設故障一定來自硬體。

本週可勾選的排障順序

先修設定,還是調整 Mac 主機方案?

標籤錯誤或群組權限不足,應先修正工作流與 Runner 設定;網路連線失敗,先處理主機網路與安全設備;launchd 無法維持服務,先確認服務安裝方式與執行帳戶。只有當 Mac 主機本身經常不可用,或團隊無法穩定照看服務與網路時,才值得評估另一種執行環境。

若要比較以遠端 Mac 承接建置工作,可先閱讀 VPSPull 的雲端 Mac 環境說明,再依工作負載與維運需求查看方案與計價資訊。遠端 Mac 可能讓你不必把建置節點綁在團隊日常使用的個人電腦上,但仍要評估網路連線、帳戶權限和專案環境;它不能代替修正 YAML 標籤或 Runner 群組設定。

常見問題

Runner 顯示離線時,為什麼 SSH 還能連上?

SSH 可用只表示你能連到主機,不代表 Runner 程式也能連到 GitHub。接著確認 Runner 服務狀態並執行官方連通性檢查;若服務仍在執行但無法連線,查看 Runner 診斷日誌,追查代理、防火牆或 DNS 設定。

Runner 在線且沒有錯誤,工作流仍在排隊代表什麼?

通常需要檢查工作流是否找得到符合條件且可接單的 Runner。比對 runs-on 所需標籤和 Runner 現有標籤,再查 Runner 群組是否授權該工作流所在的儲存庫。這些條件不吻合時,重啟主機不會讓工作流自動找到節點。

launchd 服務狀態正常,為什麼建置仍可能失敗?

服務正常只證明 Runner 服務已啟動,不代表建置步驟具備所需的檔案權限、環境變數、憑證或依賴套件。用工作流日誌找出第一個失敗步驟,再比對服務帳戶能否存取該步驟需要的資源。

網路檢查通過,Runner 為什麼仍顯示離線?

網路檢查通過不等於 Runner 已成功註冊並維持連線。確認服務是否持續執行、憑證或註冊狀態是否有效,再依時間對照 Runner 診斷日誌與主機服務日誌;只有查明實際錯誤後,才調整相應設定。

如果你現在的方案依賴一台會休眠、重啟後需手動處理,或必須由團隊自行維護網路與服務的 Mac,這些負擔可能比一次 YAML 修正更值得優先處理。確認故障確實來自主機持續可用性或維護能力後,再評估 VPSPull 的遠端 Mac 是否適合你的建置節奏;若問題只是標籤或權限不符,先修設定即可,無須為此遷移。

常見問題

GitHub Actions 的 macOS 自託管 Runner 顯示 offline,應從哪裡查起?

先確認 Mac 主機是否在線,再查看 Runner 程式與服務狀態,最後依官方網路檢查方式確認能否連到 GitHub。記下介面顯示的狀態和最近一次成功工作流;若主機可用但 Runner 未連線,檢查 Runner 診斷日誌,不要先關閉 TLS 憑證驗證。

macOS Runner 顯示在線,但 GitHub Actions 工作流一直排隊怎麼辦?

先比對工作流的 runs-on 條件、Runner 實際標籤,以及該 Runner 所屬群組是否允許此儲存庫使用。Runner 在線不代表它符合工作流的路由條件;若沒有符合條件且可接單的 Runner,應先修正標籤或群組權限,而不是更換 Mac 主機。

如何確認 macOS 上的 GitHub Actions Runner 已由 launchd 正常啟動?

在 Runner 安裝目錄使用官方提供的服務管理方式查詢狀態,並確認服務是以預期的帳戶安裝及啟動。再查看 launchd 相關系統日誌,對照 Runner 服務日誌中的啟動時間。手動執行 Runner 成功,只能證明互動式執行可用,不能證明重新開機後服務仍會自動啟動。

Runner 網路連線失敗時,應檢查哪些日誌與記錄?

先用官方連通性檢查確認 Runner 主機到 GitHub 的連線,再查看 Runner 診斷日誌中的連線或註冊錯誤,並對照工作流執行日誌確認任務是否曾被接手。若錯誤指向憑證、代理伺服器或防火牆,應修正對應設定;不要以停用 TLS 驗證代替根因排查。

延伸閱讀

為 macOS CI 準備一台可自行管理的遠端 Mac

VPSPull 提供獨享 Apple Silicon 實體 Mac,讓你自行安裝與管理 Runner,更清楚掌握主機環境。