GitHub Actions 自託管 Mac Runner 怎麼部署？2026

症狀：工作流需要 macOS 或 Mac 專用工具，卻沒有可持續使用的 Mac Runner。
最快解法：若主機可保持連線，先在受控倉庫註冊遠端 Mac，再安裝常駐服務並以低風險工作流驗收；不要讓持久主機執行不可信任的外部程式碼。

本文適合需要執行 iOS／macOS 建置工作的獨立開發者，以及替客戶維護 Mac 建置環境的自由工作者。
小型遠端團隊也可用本文檢查 Runner 的維護責任、倉庫權限和外部 Pull Request（PR）風險。

部署前：確認工作流真的需要 Mac

GitHub Actions 自託管 Mac Runner，適用於工作流必須在 macOS 執行，或依賴 Mac 專用工具、專案設定及建置環境的情況。若任務只是跨平台的程式檢查、文件整理或其他不依賴 macOS 的工作，不要只因使用 GitHub Actions 就增加一台 Mac 主機的維護工作。

GitHub 提供託管 Runner，也允許使用者自行管理主機上的 Runner。採用自託管方式後，主機、作業系統及 Runner 軟體的維護責任在使用者一方；主機亦須可連線，才有機會接到派發的工作。GitHub 對自託管 Runner 的說明列出這類 Runner 的管理方式及責任。

先以工作流需求作決定：

• 選自託管 Mac Runner：工作必須使用 macOS，且您需要控制建置主機或其環境。
• 先留在託管 Runner：專案可在 GitHub 提供的環境執行，沒有必須使用自有 Mac 的條件。
• 暫緩部署：沒有可管理的倉庫權限、無法維護主機，或未釐清哪些工作流可以執行時，不要先把 Runner 註冊到正式環境。

這不是單純的主機選擇。自託管 Runner 會執行倉庫工作流；權限設得太寬，或把外部程式碼送到長期運作的主機，都會擴大風險。

準備階段：選好範圍與主機

在 GitHub 設定中新增 Runner 前，先決定它要屬於單一倉庫，還是組織範圍。倉庫級設定適合先驗收單一專案；組織級設定則需確認允許哪些倉庫使用 Runner，避免把可用主機開放給未審核的工作流。

接著確認您有權管理相應範圍的 Runner，並備妥可登入的 Mac 主機、工作目錄和專案依賴。若工作流需要特定工具、簽署材料或建置設定，應先列出其來源與存取權限；不要在註冊後才發現 Runner 雖在線，卻無法完成專案工作。

GitHub 的自託管 Runner 文件另列出系統需求，請在部署前對照官方系統需求。主機能開機，不等於 Runner 一定符合目前的執行條件。

遠端使用也要納入檢查：管理者是否能連上主機、網路中斷時如何恢復、重新啟動後服務能否回來。需要評估所在地與遠端主機條件時，可先查閱資料中心資訊；頁面資訊應與您的專案需求逐項核對，不應代替實際驗收。

安全提醒：註冊流程會使用 GitHub 當下產生的臨時令牌。依設定頁提供的指令操作，不要把令牌貼進程式碼、提交到倉庫或交給其他人重複使用。

註冊階段：照設定頁下載並連結 Runner

GitHub 的倉庫或組織設定頁會提供對應範圍的 Runner 新增指引。先進入正確範圍，再選擇 macOS 及符合主機的架構；接著按照頁面顯示的命令下載 Runner 並完成設定。GitHub 官方的新增自託管 Runner 步驟是應優先採用的依據。

不要從別人的教學複製一整組命令，尤其是包含註冊令牌的部分。介面可能依倉庫或組織範圍產生不同指令；以執行時顯示的官方指引為準。若令牌已意外外洩，應依 GitHub 流程處理，不要假設刪除終端機歷史就能消除風險。

設定完成後，先在終端機前景啟動 Runner，觀察它能否連上 GitHub。此時的目的只是確認註冊和連線流程，不是把終端機視窗當成長期運作方式。

常駐階段：把 Runner 設為 macOS 服務

Runner 在終端機前景運行時，結束該程序便不能再依靠它持續接單。要讓工作流不受管理者是否保持登入終端機影響，需依 GitHub 指引安裝並啟動 macOS 服務。官方的macOS Runner 服務設定步驟提供相應操作方式。

在已完成 Runner 設定的目錄中，按官方文件執行服務指令。常見檢查順序如下；若目前頁面提供的命令有差異，請以頁面為準：

sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

預期應看到服務已安裝、正在運行，並且 GitHub 設定頁顯示 Runner 在線。終端機輸出和 GitHub 頁面要一起核對；其中一項不符，就先不要把部署視為完成。

接著重新啟動主機，確認服務能重新啟動，並回到 GitHub 頁面檢查 Runner 狀態。若狀態沒有恢復，查看服務及 Runner 記錄，依官方監控與故障排除指引排查。首次註冊成功，只能證明註冊當下完成，不能證明主機重啟後仍可接單。

驗收階段：以標籤派發低風險工作流

工作流必須使用與 Runner 相符的標籤，GitHub 才能把任務派到合適的主機。自託管 Runner 可使用系統提供的標籤，也可依設定加入自訂標籤；先從 Runner 頁面確認實際標籤，再按官方標籤說明配置派發條件。

以下僅示範工作流格式。ios-ci 是示意用的自訂標籤，須先確認已加到目標 Runner；架構標籤也應按 Runner 頁面實際顯示內容調整。

name: macOS runner smoke test

on:
  workflow_dispatch:

jobs:
  runner-check:
    runs-on: [self-hosted, macOS, ARM64, ios-ci]
    steps:
      - name: Confirm runner can execute
        run: |
          sw_vers
          uname -m

第一次驗收選可重複、低風險的手動工作流即可。檢查工作是否派發到預期 Runner、日誌是否可讀、輸出是否能交付。若工作停留在等待狀態，先比對 runs-on 與 Runner 標籤，不要直接假設是主機效能或網路問題。

通過基本測試後，再執行一項專案真正需要的 macOS 建置任務，確認依賴、權限及產出都符合預期。一次成功只代表該工作流與當時環境通過；工具版本或專案設定改變後，仍須重新驗證。

維護階段：限制工作流來源並確認責任邊界

自託管主機可能保留工作目錄、工具狀態或工作執行後的環境。若不可信任的程式碼能在持久主機上執行，就可能影響主機及其能接觸的憑據。GitHub 的安全使用文件提醒使用者謹慎處理自託管 Runner 與不可信任工作流的安全邊界。

部署前應確認誰能觸發工作流、哪些倉庫可以使用 Runner，以及秘密資料是否只授予必要工作。尤其不要把日常使用的持久 Runner 直接開放給公開倉庫的外部 PR。若確實需要處理外部貢獻，先設計隔離環境及權限限制，再考慮是否派發到該主機。

如果尚未釐清託管與自託管任務的分工，可先比較遠端 Mac 的使用方式與方案差異。表格不是相容性保證；最後仍應以實際 Runner 標籤、專案依賴和工作流驗收結果作決定。

常見部署疑問

關閉終端機後，Runner 還能接收工作嗎？

只有在 Runner 已配置為 macOS 服務並確認運作時，才應預期它能在終端機關閉後持續執行。前景程序結束後不會替代常駐服務。安裝服務後仍要檢查服務狀態，並在主機重新啟動後確認 GitHub 頁面顯示在線。

怎樣確認工作流使用正確的 Mac Runner？

在倉庫或組織設定中查看 Runner 標籤，讓工作流的 runs-on 條件符合實際標籤。先派發低風險測試，再從工作記錄確認執行結果。若工作沒有派發，先檢查標籤、Runner 是否在線及倉庫是否有使用權限。

外部 Pull Request 可以使用持久的自託管 Runner 嗎？

不應直接讓未審核的外部程式碼在持久主機上執行。此類工作流可能接觸到執行環境及主機可存取的資料。先限制觸發者與倉庫權限；若專案必須處理外部 PR，應先安排隔離與憑據限制，再評估其他執行方式。

依驗收結果選擇遠端 Mac 方案

若專案只需偶爾執行短期任務，維護一台長期在線的自有主機可能不合算；若要把 MacBook 隨身帶著跑，又會增加攜帶負擔，並讓工作環境受個人裝置狀況影響。自行管理遠端主機則仍須安排服務維護、網路連線與安全設定，這些工作不會因 Runner 註冊完成而消失。

如果工作流已在受控倉庫通過驗收，但您需要的是臨時或有週期性的遠端 macOS 環境，可向 OnceMac 確認實際可用環境、存取方式和使用週期，再判斷是否符合工作流；不要只憑本文範例推定權限或相容性。可透過聯絡 OnceMac詢問細節。若工作長期穩定且負載密集、必須使用實體介面，或需要自行控制整套主機維護流程，先比較自購 Mac 與自管方案，租用未必合適。

常見問題