GitHub Actions 怎麼用遠端 Mac 自動建置？2026 設定指南

GitHub 官方文件列明，自託管 Runner 需要透過 HTTPS 的 443 埠與 GitHub 服務通訊（網路需求）。若專案需要 macOS 工具鏈或自訂且持續的建置環境，遠端 Mac 可配置成 GitHub Actions 自託管 Runner；但主機維護和安全隔離也會落在使用者身上。公開倉庫或不受信任的貢獻程式碼，不應直接接觸存有敏感憑據的常駐 Runner。

適合閱讀的對象
獨立 Apple 平台開發者：希望把重複建置工作交給遠端 macOS 主機。
數位遊民與自由工作者：需要跨裝置觸發建置，並評估遠端 Mac 是否符合專案環境。
小型遠端團隊技術負責人：需要安排 Runner 權限、憑據隔離和維護責任。

開始部署前：遠端 Mac 是否真的需要接手建置

遠端 Mac 是工作流派送後執行指令的主機，不是 GitHub Actions 工作流本身。工作流仍由 GitHub 管理；Runner 接收符合條件的工作，再於主機上執行建置命令。因此，先確認工作對 macOS 的依賴，比先註冊 Runner 更重要。

適合交給遠端 Mac 的任務，通常需要 macOS 專屬工具、專案自訂環境，或需要在主機上保留特定工具與設定。若建置只使用跨平台命令，且 GitHub 託管 Runner 已能提供所需環境，就沒有必要為了「有一台 Mac」而增加維運工作。

還有一種情況適合雙軌：可信任的主分支建置使用遠端 Mac；不可信任的外部貢獻工作流則改用隔離環境，或只派送至符合需求的託管 Runner。若兩邊的工具鏈或建置結果不同，則要分別驗收，不能把「其中一邊成功」視為整條交付流程已完成。

設定前：主機帳戶、網路與權限準備

註冊前先核對主機的 macOS 帳戶、網路連線、工作目錄和倉庫管理權限。Runner 要能連到 GitHub 的服務端點；只確認可以瀏覽一般網站，不能代替確認 Runner 所需的網路連線。若環境有防火牆或代理設定，應先交由網路管理者檢查必要的連線是否被阻擋。

建議使用專供建置的 macOS 帳戶和獨立工作目錄，避免 Runner 直接沿用日常管理帳戶的檔案與權限。建置所需的憑據也應限於必要用途；不需要的個人資料、SSH 金鑰或長期存取權杖，不應放在 Runner 可讀取的位置。

管理者還要確認 Runner 綁定的倉庫或組織範圍。依 GitHub 的自託管 Runner 存取管理文件，Runner 可按管理範圍設定可用對象；不要為了省事就讓不相關的倉庫共用同一台主機。

註冊階段：取得臨時憑據並連接 Runner

GitHub 官方的 Runner 設定流程包含取得設定指示、在主機上設定 Runner，以及啟動 Runner 等階段。實際操作時，應從 GitHub 當下提供的官方指示取得設定資料；註冊用令牌屬於臨時憑據，不要把令牌貼進工作流檔案、文件或長期保存的腳本。完整操作可參照新增自託管 Runner 的官方步驟。

註冊時可為用途設定辨識清楚的標籤，例如 ci-mac，讓工作流能選到預期的主機。標籤只協助派送，不代表已驗證主機內的工具、Xcode 版本或專案相容性；標籤名稱及套用方式可參考Runner 標籤說明。

完成註冊後，先在 GitHub 的 Runner 清單確認狀態，再檢查主機上的 Runner 程序是否仍在執行。畫面顯示已註冊，只能證明設定走到某個階段，不能證明工作流已成功派送，更不能證明建置產物可用。

首次驗收：用最小工作流確認任務落在遠端 Mac

第一次測試先使用可信任分支和手動觸發，避免尚未確認權限邊界，就讓外部事件自動執行程式碼。以下範例列出基本結構；<已核准的版本或提交參照> 應替換成團隊已審核的 action 參照，PROJECT_PATH 和 SCHEME 則需依專案設定。

name: macOS build

on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64, ci-mac]
    steps:
      - name: 取得原始碼
        uses: actions/checkout@<已核准的版本或提交參照>

      - name: 確認主機工具
        run: |
          uname -s
          sw_vers
          xcodebuild -version

      - name: 執行建置
        run: |
          xcodebuild \
            -project "$PROJECT_PATH" \
            -scheme "$SCHEME" \
            -configuration Release \
            build
        env:
          PROJECT_PATH: ${{ vars.PROJECT_PATH }}
          SCHEME: ${{ vars.SCHEME }}

工作流權限應從最低需求開始；例如範例只授予讀取內容的權限。若專案需要寫入權限或發布憑據，應逐項確認必要性，再加入對應設定。GitHub 的工作流語法文件說明了權限及工作流欄位；外部 action 也應納入審核，參照其安全使用建議。

驗收時要同時看三個位置：工作流執行頁面是否顯示工作已開始、主機端是否有相應的 Runner 活動，以及工作日誌中的系統與工具輸出是否符合預期。像 uname -s 回報 Darwin，可以協助確認命令在 macOS 環境執行；真正的專案建置仍要檢查結束狀態與產物，不能以工具資訊輸出代替。

若需要讓後續工作流下載建置結果，還要確認產物路徑和保留方式。GitHub 對工作流產物的用途與操作有獨立說明；建置成功但沒有可取回的產物，仍不是完整交付。

開放自動觸發前：依程式碼來源劃分信任邊界

自託管 Runner 會在主機上執行工作流程式碼。GitHub 特別提醒，自託管 Runner 面對不可信工作流時存在安全風險；因此，外部貢獻程式碼若能在常駐主機上執行，就可能接觸到主機可讀取的檔案、工具或其他資源。部署前應閱讀安全使用 GitHub Actions 的官方說明。

建議按觸發來源分開決策：

• 可信任的內部分支：在確認提交來源、工作流內容及所需憑據後，才派送至自託管 Runner。
• 外部貢獻或公開來源：不讓其直接執行在持有敏感憑據的常駐 Runner；改用隔離環境，或設定人工審批與其他限制。
• 發布和部署工作：將建置與發布憑據分開管理，只在確有需要的工作中授予必要權限。
• 倉庫範圍不明：先收窄 Runner 可服務的倉庫，再開啟自動觸發；不要用全組織共用取代權限規劃。

初期只啟用手動觸發或可信分支事件。待權限與日誌驗收完成，再逐步加入其他事件。事件種類和觸發條件可查看工作流觸發事件參考。如果無法隔離外部程式碼，也無法移除 Runner 可讀取的敏感資料，就先不要讓該類工作流接觸這台主機。

日常運維：Runner 離線、主機重啟與工作積壓

Runner 離線時，先從 GitHub Actions 執行狀態分辨問題位置。工作長時間等待且沒有接手主機，應先檢查 Runner 是否在線、服務程序是否運作及標籤是否匹配；工作已開始但命令失敗，則檢查工作日誌中的路徑、依賴與工具設定。不要因工作排隊就立刻重複提交相同建置，否則可能增加積壓，卻沒有修復原因。

主機重啟後，確認 Runner 是否按預期恢復連線，再以不涉及發布的測試工作驗證派送。若系統更新、帳戶狀態或網路變動後仍無法連線，依官方自託管 Runner 監控與故障排除指引檢查主機和 Runner 記錄。

工作積壓期間，要有明確的備援與暫停條件：相容的工作可切到託管 Runner；依賴本機工具鏈的工作則先停止自動派送，待遠端 Mac 恢復並完成測試後再恢復。若建置涉及發布、簽署或敏感憑據，不能只為清空佇列就略過人工審查。遠端 Mac 是否能在特定時間內恢復，取決於主機、網路和維護安排，沒有實測資料時不應承諾固定恢復時間。

完整交付驗收：自託管、託管 Runner 或雙軌

最後用真實專案走完一次交付，而非只跑系統資訊命令。確認觸發事件符合預期、工作由正確 Runner 接手、建置成功、產物能取回，並演練一次 Runner 離線後的備援或暫停流程。若專案依賴 macOS 專屬工具，還要確認實際環境與依賴；具體 macOS、Xcode 及專案相容性仍須在目標主機上驗證。

若只偶爾需要 macOS 建置，先比較短期使用與自行長期維護的責任；若建置持續且有人可管理權限、更新與故障復原，自託管才有合理性。需要估算遠端 Mac 使用成本時，可先查看遠端 Mac 方案與租用資訊，並依專案週期和所需環境核對實際方案，不以未驗證的規格或價格作為決策依據。

若目前以本地 Mac 或通用 Runner 為主，可能仍要處理隨身設備依賴、macOS 環境不一致，以及故障時缺少備援等問題；反過來說，長期高頻且需要固定硬體的建置，也未必適合租用，購置自有主機可能更符合維運方式。完成真實工作流驗收後，再按專案週期與主機維護責任選擇：若只需階段性測試或旅途中維持 Apple 平台建置，可參考 SFTPMAC 的遠端 Mac 服務資訊，評估租用環境是否比攜帶或維護自有 Mac 更合適。