CI/CD / DevOps

GitHub Actions macOS Runner 2026:遠端 Mac 怎麼配置?

GitHub 官方文件列出自託管 Runner 的三種註冊範圍:倉庫、組織與企業;對需要 Xcode 或 macOS 環境的工作流而言,只要觸發來源可信、存取範圍已限制,就可以將遠端 Mac 配置為 Runner,並先以可信分支的實際專案驗證。若公開倉庫可能接收不受信任的 PR,則不要讓承載敏感憑據的自託管 Runner 執行這些工作。GitHub 的 Runner 註冊與安全說明

使用 GitHub Actions、需要在 macOS 環境建置 iOS App 的獨立開發者,可依本文評估並配置 Runner。
維護小型 iOS 團隊建置流程的人,可檢查存取範圍、服務狀態與工作流驗收證據。
已經有遠端 Mac、但尚未接入自動化工作流的開發者,可判斷它是否適合成為常駐建置節點。

GitHub Actions macOS Runner 2026 遠端 Mac 配置:先確認適用條件

在安裝 Runner 之前,先把工作流和信任邊界寫清楚:目標倉庫是哪一個、哪些事件可以觸發建置、建置目標是什麼,以及工作是否需要簽署憑據。Runner 會在自己的主機環境中執行工作流指令;因此,這不是單純的「把 GitHub 連到一台 Mac」,而是授予工作流在該主機執行程式碼的能力。GitHub 的自託管 Runner 文件也說明了此類 Runner 的使用與管理方式。

公開倉庫可以使用 macOS 自託管 Runner 嗎? 可以配置,但不代表適合讓所有工作流使用。GitHub 特別提醒,公開倉庫的 fork PR 可能執行不可信程式碼;如果 Runner 可接觸到憑據、私有資料或其他敏感資源,應避免讓這類工作流在該主機執行。GitHub 的自託管 Runner 安全警告

部署前可以依以下條件決策:

  • 若工作流只接受受控分支或可信來源,且建置任務確實需要 Xcode,再進入 Runner 配置。
  • 若工作流會執行公開倉庫的外部 PR,且任務可能取得敏感憑據,先改用不接觸該憑據的隔離建置方式;未完成隔離前,不要把遠端 Mac 指派給這類任務。
  • 若目標只是一般程式碼檢查,並不依賴 macOS 工具鏈,先確認是否有必要使用這台 Mac;不要為了接入 Runner 而增加一台需要維護的主機。
  • 若同一組 Runner 要供多個倉庫使用,先確認註冊層級和團隊管理方式,再決定註冊到倉庫、組織或企業。不同範圍會影響哪些工作流能使用 Runner,應依 GitHub 的 Runner 存取管理文件核對設定。

註冊前準備 macOS 與 Xcode 工具鏈

先確認遠端 Mac 可正常登入,並能連線至 GitHub;若預計無人值守運行,也要先確認服務所使用的帳號、工作目錄與網路條件。若主機尚未能穩定取得倉庫程式碼,暫停安裝 Runner,先排除連線或存取問題。

Xcode 是否可用,不應只看應用程式是否已安裝。透過終端機檢查目前選用的開發者目錄:

xcode-select -p

Apple 說明,xcode-select 可用來選擇命令列工具使用的開發者目錄;因此,這項檢查能協助確認命令列目前指向預期的 Xcode 或 Command Line Tools 安裝位置。Apple 關於設定命令列工具的說明

接著以最小查詢確認建置工具能執行:

xcodebuild -version
xcodebuild -showsdks

若查詢失敗,或顯示的工具鏈不是專案預期版本,先修正 Xcode 安裝或開發者目錄選擇,再繼續註冊。Apple 的文件亦說明如何安裝 Xcode 命令列工具;該工具是否足以滿足專案需求,仍需以實際的 xcodebuild 建置驗證,不能只憑安裝成功判定。Apple 的命令列工具安裝說明

註冊 Runner 只證明主機可接收工作,並不證明簽名、鑰匙圈或圖形介面操作已可在背景服務中使用。涉及這些能力時,應在與正式 Runner 相同的執行方式下另行驗證。

為目標倉庫選定註冊範圍並接入 Runner

在 GitHub 的目標倉庫、組織或企業設定中新增 macOS 自託管 Runner,依畫面提供的流程下載應用程式並執行配置。註冊範圍應符合實際管理需求:單一專案通常先確認倉庫層級;若要由多個倉庫共用,則應先檢查組織或企業的使用權限和管理規則。

配置過程會要求 GitHub 提供的註冊資訊。以下僅示範參數位置,不是可直接使用的帳號或憑據:

./config.sh --url <目標倉庫或組織網址> --token <由 GitHub 提供的暫時註冊令牌>

不要把真實令牌貼進公開文件、提交到倉庫,或保存在供其他人讀取的工作流檔案中。註冊完成後,檢查 GitHub 設定頁的 Runner 清單,確認該主機已顯示在線,並核對標籤與實際系統相符。GitHub Runner 設定應用程式的流程

GitHub Actions self-hosted runner 能否執行 Xcode 建置? 可以,但前提是 Runner 所在 Mac 已具備專案需要的 Xcode 工具鏈,而且工作流確實被派送到這台主機。標籤能協助 GitHub 選擇符合條件的 Runner;它不會替主機安裝 Xcode,也不會自動處理簽名或上架設定。GitHub 在工作流中選擇自託管 Runner 的說明

設定 macOS 服務並驗證無人值守狀態

只在終端機前景啟動 Runner,不能證明主機重新啟動後仍能接收工作。需要持續運作時,依 GitHub 為 macOS 提供的程序,將 Runner 設定為服務;常見操作是在 Runner 目錄中使用服務管理指令:

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

服務安裝與啟動方式應以目前版本的 GitHub Runner 應用程式與服務文件為準。執行後要同時查看本機服務狀態與 GitHub 顯示的 Runner 狀態;其中一側正常、另一側離線,仍表示接入尚未完成。

還要用實際工作流檢查服務工作階段和互動式桌面工作階段的環境差異。確認服務帳號能讀取專案需要的檔案、能使用預期的工具鏈,並且不會意外依賴登入桌面後才出現的環境變數。若任務需要鑰匙圈、憑證或圖形介面,先在服務執行方式中驗證;驗證未通過,就不要把「手動登入時可操作」當成 Runner 背景任務可用的證據。

服務顯示失敗或 Runner 持續離線時,先停止向該主機派送發布任務,核對服務日誌、網路連線與配置狀態,再依 GitHub 的監控與故障排查指引處理。若調整後仍無法恢復,回退到手動建置或其他已驗證的工作環境,避免在服務狀態不明時執行帶有發布憑據的任務。

建立可信工作流,驗證 Xcode 命令列建置

首次驗收應使用倉庫內可信分支的建置工作,不要直接把簽名與上傳發布一起導入。以下範例限定在推送至指定分支時執行,權限只讀取倉庫內容,並要求工作派送至具備自託管與 macOS 標籤的 Runner:

name: iOS build

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  build:
    runs-on: [self-hosted, macOS]
    steps:
      - name: Check out source
        uses: actions/checkout@v4

      - name: Show Xcode toolchain
        run: xcodebuild -version

      - name: Build project
        run: xcodebuild -project Example.xcodeproj -scheme Example -sdk iphonesimulator build

請將專案名稱、Scheme 與建置目標改為實際值;若倉庫使用工作區或不同建置方式,也應按專案調整命令。範例中的動作版本是工作流語法示意,不代表已替任何專案驗證相容性。工作流權限可在設定中明確限制;上述 contents: read 是檢出程式碼所需權限的範例,應依實際任務再審查是否需要其他權限。GitHub 工作流語法與權限設定

此階段的驗收目標是確認排程、程式碼檢出、Xcode 命令呼叫與建置結果都能在記錄中追溯。若工作被其他 Runner 接走、程式碼檢出失敗,或 xcodebuild 找不到專案設定,就先修正標籤、工作目錄或建置命令,不要急著加入歸檔和上傳步驟。簽名與 App Store 發布涉及另一組憑據和權限設計,應待基本建置穩定後再分開評估。

依驗收證據決定是否投入日常建置

遠端 Mac iOS 自動建置是否適合長期運作,要看實際記錄,而不是只看 Runner 設定頁顯示在線。驗收清單可逐項勾選:

  • [ ] GitHub 顯示 Runner 在線,標籤與預定用途一致。
  • [ ] 可信分支的工作流成功派送到預期 Runner,且程式碼檢出完成。
  • [ ] xcodebuild 能讀取專案並完成預定建置,工作流記錄可供後續排查。
  • [ ] 產物符合專案建置目標;若尚未測試歸檔或簽名,明確標記為未驗收,不把基本建置成功視為發布完成。
  • [ ] 停止並重新啟動服務後,Runner 能重新上線;若不能,已記錄恢復步驟並暫停發布用途。
  • [ ] Runner 更新、工作流權限複核、故障排查及移除流程均有負責人。

配置和驗收紀錄可與專案維運文件分開保存;若需要為遠端主機建立連線管理流程,可先參考 KuzCloud 使用說明。已經配置主機的使用者,也可從 KuzCloud 控制台確認自身服務的管理入口;這些服務操作資訊不能取代 GitHub 端的 Runner 狀態與工作流日誌。

驗收情況 建議判斷 下一步
工作流來源可信,Runner 權限有限,Xcode 建置與服務重啟均已驗證 可評估投入日常建置 保留工作流記錄,持續複核憑據與存取範圍
Runner 在線,但建置未完成或服務重啟後未恢復 暫不承擔日常發布任務 先修正工具鏈、服務環境或網路問題
公開 PR 可能執行不可信程式碼,Runner 又能接觸敏感憑據 不應將該 Runner 派給這類工作 隔離工作流與憑據,未完成前改走安全的替代建置方式
建置任務不需要 Xcode 或 macOS 專用能力 重新評估是否需要這台 Mac 不要為非必要工作增加 Runner 維護責任

若目前方式是手動在本機建置,容易遇到開發者離線時無人接手、工作流記錄不集中,以及本機工具鏈與發布環境不一致等限制;但遠端 Runner 也增加主機服務、權限邊界和更新維護責任。只有當專案確實需要常駐 macOS 建置節點,且團隊能管理這些風險時,才值得把遠端 Mac 納入日常流程。若希望先了解 KuzCloud 的遠端 Mac 使用方式,再評估它是否符合 Runner 的主機需求,可從 KuzCloud 遠端 Mac 服務頁面查看;實際適用性仍應以自己的工作流、工具鏈與安全驗收結果為準。

讓 macOS Runner 在專屬遠端 Mac 上穩定運行

透過 KuzCloud 租用專屬 Mac mini M4,為 iOS 建置提供獨立、持續可用的實體算力。

完整 root 權限,方便安裝所需工具鏈,並以 SSH 或 VNC 遠端管理 Runner。