GitLab Runner API 將 Runner 狀態列為 online、offline、stale、never_contacted 四類，但狀態本身不能證明主機端的故障原因。GitLab API 文件
症狀：GitLab macOS Runner 重啟後離線。最快檢查：確認執行帳號已登入 macOS 圖形工作階段，再核對使用者級 LaunchAgent 是否啟動、Runner 是否連回 GitLab。
若需要無人值守恢復，先評估自動登入帶來的帳號與實體存取風險，不要把它當成預設修復。
這篇適合在旅途中維護 iOS 建置流程的數字遊民與遠端開發者。
如果你是獨立開發者，Runner 需要存取使用者工作階段、模擬器或簽署環境，也可以按症狀逐項排查。
小型遠端團隊則可用文中的重啟驗收，判斷自管 macOS Runner 的維護責任是否符合現況。
先判斷 GitLab macOS Runner 重啟後離線發生在哪一層
「流水線沒有可用 Runner」不是單一故障訊息。問題可能在 GitLab 調度，也可能在 Mac 主機、使用者工作階段或建置環境。先看專案中的 Runner 狀態，再看主機端服務；不要一開始就重新註冊 Runner，否則可能改動原有設定，卻沒有找出真正原因。
重開主機後，應先看 GitLab 頁面還是 Mac？
先看專案是否能辨認該 Runner，以及 Runner 顯示的狀態；接著登入 Mac 檢查服務。GitLab API 的狀態欄位能幫你判斷 Runner 是否被視為在線、離線、過期或從未聯絡，但你仍要在主機端核實登入工作階段和服務狀態。Runner API 狀態欄位說明
先按症狀分流：
- Runner 顯示離線，主機剛重啟： 優先確認原本執行 Runner 的帳號是否已登入，以及對應的
LaunchAgent是否載入。 - Runner 顯示在線，但任務沒有交給它： 檢查專案是否有權使用該 Runner、任務標籤是否符合 Runner 設定。
- Runner 接到任務，作業卻失敗： 到作業日誌確認是權限、命令、開發者目錄，還是 Xcode 元件問題。
- Runner 與作業都正常，iOS 建置仍失敗： 這才進一步檢查專案設定、簽署條件與建置工具；服務在線不等於應用程式一定能建置成功。
GitLab CI/CD 的標籤會影響工作分派。工作需要的標籤必須與 Runner 標籤設定相符；若標籤不匹配，即使主機服務運作正常，該 Runner 也可能不會接到任務。GitLab Runner 標籤與工作分派說明
第一步：確認執行帳號與 macOS LaunchAgent
GitLab 的 macOS Runner 安裝文件說明，Runner 可透過使用者層級的 LaunchAgent 執行，並依賴相應的使用者登入工作階段。GitLab macOS Runner 安裝說明 這表示只看到 Mac 開機完成，不能推定 Runner 已經開始工作。
LaunchAgent 與 LaunchDaemon 不應混為一談：前者與登入使用者的工作階段相關；後者屬於系統層級的背景服務。若你的安裝方式是使用者層級 LaunchAgent，換成檢查系統服務，未必能找到實際執行的 Runner。
按以下順序核對：
- 確認執行帳號。 查明安裝及執行 Runner 的 macOS 帳號，不要只確認你現在登入的帳號。
- 確認該帳號已登入圖形工作階段。 透過遠端桌面或主機管理方式檢查；單有 SSH 連線，不代表圖形工作階段已登入。
- 查看
LaunchAgent狀態。 在該帳號的工作階段檢查是否已載入，並查看服務日誌或系統日誌有沒有啟動錯誤。 - 使用 Runner 命令查狀態。 在安裝 Runner 的環境執行
gitlab-runner status；若要核對註冊後的連線驗證，可參照 GitLab Runner 命令文件所列的verify用法。Runner 命令文件 - 回到 GitLab 對照狀態。 如果主機端服務未運作，先處理登入或載入問題；若服務看似正常但 GitLab 仍顯示離線，則繼續檢查網路連線、Runner 註冊資訊及日誌。
macOS 重啟後，Runner 為什麼沒有自行回來？
若執行帳號尚未登入，而 Runner 以使用者層級 LaunchAgent 運作，問題可能是工作階段尚未建立，不一定是 Runner 註冊失效。先確認實際的登入狀態及服務載入結果，再決定是否調整啟動方式。
提醒：從 SSH 工作階段離線，不等於 macOS 使用者已登出；反過來說，SSH 還連得上，也不能證明 Runner 所需的圖形工作階段存在。請分別記錄 SSH、使用者登入、Runner 狀態，避免由其中一項推斷其餘項目。
退出登入後離線：區分工作階段、SSH 與主機重啟
若 Runner 在使用者登入時可用，但登出後又離線，先記錄「使用者登出」前後的狀態。不要把登出、主機重啟、SSH 中斷當成同一種情境：它們各自改變的條件不同，Runner 的實際結果取決於安裝方式及主機當時的工作階段狀態。
遠端 Mac 登出後，Runner 還會繼續工作嗎？
若你的 Runner 依賴使用者層級 LaunchAgent，登出可能影響該工作階段中的服務；應透過登出前後的服務狀態、GitLab 頁面及作業結果確認，不要只憑 SSH 是否斷線下結論。
在可安排的維護時段，分開做以下檢查：
- 只中斷 SSH： 觀察 Runner 是否仍在線，以及是否能接到測試工作。
- 登出執行帳號： 再檢查服務狀態與 GitLab 頁面；記下 Runner 是否仍可接單。
- 重新登入帳號： 確認
LaunchAgent是否載入，並觀察 Runner 是否重新連回 GitLab。 - 重啟主機： 從登入前開始記錄；確認使用者工作階段建立後，Runner 是否恢復，接著是否能完成一筆代表性的專案建置。
這幾種驗收能幫你找出依賴點。若只有圖形使用者登入後才恢復，就應把使用者登入列為復原程序的一部分；若登入後 Runner 仍離線，再查日誌與連線，而不是直接把責任歸到 macOS 啟動順序。
自動登入能恢復 Runner，但會改變安全邊界
GitLab 的 macOS 安裝文件提及自動登入與重啟後 Runner 可用的關係；Apple 也提供 macOS 自動登入設定說明。GitLab macOS 安裝文件；Apple 自動登入說明 這些文件可協助你理解機制，但不等於官方建議所有遠端 Mac 都開啟自動登入。
啟用自動登入後，Runner 能否在重新開機後接單？
若 Runner 必須依賴登入的使用者工作階段，自動登入可能使工作階段建立，進而讓 LaunchAgent 啟動；是否實際恢復仍要用你的主機設定演練確認。不要只看到 Runner 顯示在線就結案，還要確認一筆實際 CI 作業能執行。
評估自動登入前，逐項看以下風險：
- 實體存取： 主機若被他人接觸，自動登入可能讓使用者工作階段直接可用。
- 帳號與憑據： 建置環境可能保存專案存取權、簽署相關資料或其他工作憑據，需確認存取控制及撤銷流程。
- 遠端管理： 若遠端控制入口或帳號保護不足，自動登入會增加主機暴露後的影響範圍。
- 故障恢復： 自動登入只處理登入工作階段的其中一環，不能替代 Runner 連線檢查、日誌監控或備援建置路徑。
若你的建置憑據或實體主機存取無法妥善控管，就不要為了讓 Runner 自動接單而貿然開啟自動登入。先保留人工登入復原，並安排可重複的重啟測試。
Runner 在線但流水線失敗：分開驗收三個結果
Runner 顯示在線，只能說明 GitLab 與 Runner 的狀態符合在線條件；它不能證明作業一定成功，也不能證明 Xcode 建置環境正確。排查時分成三個結果：Runner 是否在線、GitLab 工作是否成功執行、Xcode 專案是否建置成功。
Runner 已在線，為何仍找不到合適的工作？
先核對專案是否有權使用 Runner，再檢查工作標籤是否符合 Runner 標籤。標籤設定不匹配時，調度問題與服務離線是兩回事；依 GitLab 的標籤說明逐項比對工作需求和 Runner 設定。GitLab Runner 標籤文件
工作已經啟動但建置失敗時，按作業日誌的第一個實際錯誤往回查：
- 權限或帳號問題： 核對工作由哪個 macOS 帳號執行，確認它有權存取專案目錄與所需工具。
- Xcode 路徑問題： 在作業使用的帳號環境執行
xcode-select -p，確認目前選取的開發者目錄符合該專案需求。Apple 提供命令列工具安裝說明；若缺少元件，再核對 Xcode 元件文件中的安裝方式。Apple 命令列工具說明；Apple Xcode 附加元件說明 - 作業環境不一致： 比較互動式終端機與 CI 作業實際使用的帳號、環境變數、路徑及權限。終端機手動成功，不代表 Runner 使用相同環境。
- 專案建置或簽署問題： 依日誌中最早出現的具體錯誤檢查專案設定與憑據；不要把所有建置失敗都歸類成 Runner 離線。
修復後，回到 GitLab 確認工作真的由預期 Runner 接手，再檢查作業輸出與 Xcode 結果。只看主機服務狀態，驗收還沒有完成。
用重啟演練選擇自管 Runner 或備援建置
以下比較表用來決定下一步，不代表某種方式對所有團隊都安全或適用。
| 選項 | 適合情況 | 優點 | 代價與判斷 |
|---|---|---|---|
保留使用者層級 LaunchAgent |
可以確保執行帳號登入，並能處理重啟後的登入與檢查 | 保留目前 Runner 與 Mac 工作環境 | 需要監測工作階段及服務狀態；若無法維持登入，需準備復原流程 |
| 評估自動登入 | 需要主機重啟後自動建立登入工作階段，且能接受相應安全責任 | 可能減少人工登入這個恢復環節 | 擴大實體存取及帳號安全風險；須先完成存取控制評估與實際演練 |
| 建立備援建置路徑 | 不能接受自動登入，或無法保證遠端 Mac 的登入狀態 | Runner 暫時不可用時，仍可評估其他建置安排 | 需要驗證替代環境能否滿足專案的 Xcode、憑據與工作流程需求 |
要完成一次有效驗收，依序記下：
- 重啟前，確認 Runner 狀態、執行帳號及目前建置結果。
- 重啟主機，記錄執行帳號是否登入；不要假設它會自動登入。
- 檢查
LaunchAgent是否載入，以及gitlab-runner status的結果。 - 回到 GitLab 確認 Runner 是否恢復連線、標籤是否符合測試工作的需求。
- 提交一筆代表性 CI 作業，確認 Runner 接單、作業完成，並核對 Xcode 建置結果。
每一環都通過，才表示目前的恢復方式經過驗收。若必須手動登入但團隊無法及時登入，就要調整值班流程或建立備援；若自動登入的安全代價不可接受，也不要用「服務有上線」掩蓋風險。對正在旅途中維護遠端 Mac iOS 建置的人而言，這份驗收記錄比只記一個 Runner 在線狀態更能說明流程是否可靠。
如果你要比較遠端 Mac 的使用方式與接入安排，可先從 MACCOME 繁體中文服務入口查看相關資訊，再評估它是否符合你現有的 Runner 維護流程。
若你的現況是把 Runner 放在個人 Mac 上，主要缺點可能是重啟後需要人工恢復、旅途中難以處理實體或登入問題，以及主機不可用時建置工作跟著中斷。若你確認專案需要持續可存取的 macOS 建置環境，可評估租用 MACCOME 遠端 Mac，把 Runner 放在可遠端管理的主機上；但仍須自行驗證登入模式、憑據控管與備援流程，不能把租用本身視為 CI 恢復保證。你可先查看遠端 Mac 接入與使用方案，再依重啟演練結果決定是否適合。