SSH 登入
適合執行建置指令、傳輸檔案及檢查記錄。SSH 預設連接埠為 22；若執行個體提供其他連接埠，請使用實際值。
在執行個體詳細資訊中查詢主機位址與使用者名稱。首次連線時，先核對主機指紋，再設定自己的公開金鑰；私密金鑰請留在本機，勿附在工單中。
查看首次建置範例
先確認執行個體狀態
選擇連線方式
前往控制台的執行個體詳細資訊，確認執行個體編號、節點與就緒狀態。公網位址、使用者名稱、連接埠與初始憑證，請以該執行個體實際提供的資訊為準，勿套用其他機器的參數。
VNC 圖形桌面
適合開啟 Xcode、檢查 Simulator 及調整圖形介面設定。VNC 預設連接埠為 5900；請從執行個體詳細資訊取得連線位址、密碼與實際連接埠。
連線後先確認桌面操作正常。請勿將 VNC 密碼用於程式碼儲存庫；在網路條件允許時，優先透過受控連線或 SSH 通道存取。
查看圖形桌面問題控制台網頁終端
先登入控制台，再查看執行個體詳細資訊提供的連線入口。若有提供網頁終端，請使用瀏覽器透過 HTTPS 連線，通常使用 443，無須另外輸入終端連接埠。
憑證來自已登入的帳戶工作階段，並非公開的獨立連結。若執行個體未顯示此入口，請使用 SSH 或 VNC；勿自行猜測終端位址。
查看執行個體連線入口
先完成一次，再串接 CI
分開驗證連線與建置
先確認可以登入，再檢查 Xcode 路徑與版本。以下是輸出格式範例，並非執行個體的即時記錄；工作階段名稱、建置編號與耗時僅供說明如何判讀。
merge@tokyo-m4pro-07
建置輸出範例
$ ssh -p <SSH_PORT> <USER>@<HOST>
Welcome to MergeMac
$ xcode-select -p
/Applications/Xcode.app/Contents/Developer
$ xcodebuild -version
$ cd <PROJECT_DIRECTORY>
$ xcodebuild -scheme App archive
** ARCHIVE SUCCEEDED **
$ fastlane pilot upload
Successfully uploaded Build 214替換參數後執行
請將尖括號中的參數替換為執行個體詳細資訊中的值。App 是範例 scheme；若使用 workspace 專案，還需加入自己的 -workspace，並確認 scheme 已設為共用。
Archive 成功不代表上傳完成
上傳還需要有效的簽署設定、匯出設定檔及上傳憑證。範例假設專案已設定 fastlane；Build 214 並非你的交付確認，請以實際上傳工具的輸出為準。
讓機器執行指定工作
串接 self-hosted runner
MergeMac 提供獨享實體節點；CI 儲存庫權限、工作設定與憑證由你管理。先以同一個執行使用者在終端成功執行 archive，再註冊 runner，避免將環境問題誤判為排程問題。
GitHub Actions
- 前往目標儲存庫或組織的 Actions runner 設定，選擇 macOS 與相符的 Apple Silicon 架構。
- 在租用節點上，依目前頁面提供的指令下載、驗證並註冊 runner。註冊 token 屬於敏感資訊，請勿存入儲存庫或放進截圖。
- 新增標籤，例如
mergemac、macos、m4。在 workflow 中使用runs-on指定這些標籤。 - 先提交只檢查 Xcode 版本的工作，確認由正確的節點接手，再加入相依套件安裝、archive 與上傳步驟。
請勿讓不受信任的外部合併請求直接使用持有簽署資料的 runner；發布工作與一般驗證工作應分開授權。
GitLab Runner
- 在專案或群組中建立 runner，取得目前註冊流程要求的服務位址與驗證 token。
- 在節點安裝相符架構的 GitLab Runner，依產生的指引完成註冊；若需要本機 Xcode 工具鏈，請選擇合適的 Shell 執行方式。
- 設定
macos、xcode等標籤，並在工作中明確指定。發布用 runner 僅限受保護的分支或標籤使用。 - 先執行環境檢查工作，確認工作目錄、執行使用者與鑰匙圈存取正常，再啟用正式建置。
更新 token 或租期結束前，請在 CI 平台撤銷該 runner 的授權；只刪除節點上的檔案不會自動撤銷平台授權。
看懂控制台用語
八個術語，一次說明
這些詞描述資源與連線方式，不代表額外的軟體授權，也不會自動把多台機器合併成一台更大的 Mac。
- 實體節點
- 機房中可獨立分配的一台 Mac mini，執行真正的 macOS 開發環境。
- 獨享
- 租期內，整台機器的 CPU、GPU、統一記憶體與本機磁碟資源僅分配給一位租用者。
- 非虛擬機
- 直接使用實體 Mac 上的系統，而非共享主機上切分出的虛擬執行個體。
- VNC
- 用於遠端檢視及操作 macOS 圖形桌面的連線通訊協定。
- SSH
- 用於加密命令列登入、執行指令與傳輸檔案的連線通訊協定。
- self-hosted runner
- 安裝在你租用節點上的 CI 執行器，依你的流水線設定派發建置工作。
- 統一記憶體
- Apple 晶片的 CPU 與 GPU 共用的記憶體；實際可用容量還需扣除系統及其他程序的使用量。
- Thunderbolt 5 並聯
- 透過 Thunderbolt 5 直接連接多台裝置進行多機實驗；仍需由應用程式自行支援工作分派。
先保留證據，再調整環境
依症狀縮小範圍
記下故障時間與時區、執行個體編號、完整錯誤訊息及最近的變更。每次只調整一項，再執行相同的驗證；重裝不是第一步。
-
01
VNC 黑畫面或沒有回應
先確認控制台上的執行個體是否就緒，再測試 SSH 是否能連線。若 SSH 可用但圖形桌面異常，請檢查是否正在登入、登出或切換圖形工作階段；關閉用戶端後重新連線。
仍是黑畫面時，請保留用戶端版本與螢幕截圖，並提交工單。請勿為了測試而直接關閉防火牆或反覆強制重新啟動，否則可能中斷執行中的建置。
-
02
Xcode 版本不一致
分別執行
xcode-select -p與xcodebuild -version。互動式工作階段與 runner 都要檢查；安裝多個版本不代表命令列已切換。單一工作可使用
DEVELOPER_DIR指定目標 Xcode 的 Developer 目錄，避免變更整台機器的預設版本而影響其他工作。若目錄不存在，請先確認安裝路徑，勿直接照抄範例名稱。 -
03
Simulator 佔滿磁碟
使用
df -h查看剩餘空間，再檢查 DerivedData、archive、裝置資料及模擬器 runtime。先匯出需要保留的建置產物，並停止正在使用模擬器的工作。xcrun simctl delete unavailable可刪除無法使用的模擬器裝置記錄，但不會刪除所有 runtime。清理前請確認目標，勿對專案目錄或鑰匙圈執行遞迴刪除。 -
04
簽署憑證失效
分辨憑證過期、描述檔失效、私密金鑰遺失與鑰匙圈未解鎖。檢查憑證有效期限、團隊與 bundle identifier 是否相符，再確認 CI 執行使用者能否讀取對應的私密金鑰。
更新憑證後，也要更新描述檔與受保護變數，並使用相同的 scheme 重新驗證。工單只附上錯誤代碼與已遮蔽敏感資訊的記錄，請勿傳送私密金鑰、憑證匯出密碼或完整簽署資料。
先備份，再確認重裝
重裝會變更環境，不會保留工作區
系統重裝與租期結束後的資料清除是不同流程。請勿將租用節點當作原始碼、簽署資料或建置產物的唯一儲存位置。
租期內自行重裝
前往控制台的執行個體詳細資訊，使用系統重裝功能前，先停止 CI 排程、匯出專案、產物與必要設定，並確認備份能在其他位置開啟。
初始化通常需要幾分鐘，實際耗時與完成狀態以控制台回覆為準。工作進行中請勿重複提交；完成後重新取得連線憑證、核對主機指紋並重建開發環境。
重裝後請重新驗證 SSH、Xcode、相依套件與 runner；勿假設舊的服務設定仍然存在。
到期後清除磁碟資料
租期結束後，節點會進入資料清除與系統重設流程，之後再供後續租用。需要保留的資料請在到期前自行匯出，勿將到期後仍可連線視為備份方案。
同時撤銷程式碼儲存庫部署金鑰、CI runner token 與上傳憑證。磁碟抹除只會清除節點內的資料，不會替你撤銷外部系統的存取授權。
若有資料處理或安全界線方面的疑問，請先查看安全說明，再透過控制台工單確認特定執行個體的狀況。
提供資訊，讓支援人員快速開始排查
將問題交給支援團隊
已租用執行個體的問題，請優先提交控制台工單，方便連結訂單與節點；無法登入、售前諮詢或安全通報，請寄至支援信箱。請勿透過多個管道重複建立相同問題。
控制台工單
登入後前往工單區，填寫執行個體編號、影響範圍與重現步驟。若要升級既有問題，請直接補充原工單，保留同一筆排查記錄。
建議格式：發生時間與時區 → 預期結果 → 實際錯誤 → 已嘗試的操作。附上經遮蔽敏感資訊的最精簡記錄片段，請勿整包上傳原始碼。
登入並提交工單支援信箱
若無法登入帳戶，請在電子郵件主旨中說明問題類別，並提供註冊信箱及可供核對的訂單編號；請勿傳送帳戶密碼或付款卡號。
支援團隊會依亞太與美國東部時區協作處理。首次回覆時間視問題等級與目前佇列而定，請以工單或電子郵件回覆為準；本文不承諾未公布的平均處理時間。
support@mergemac.com設定好環境，再交由它執行建置
已有機器？先在控制台確認狀態；準備新增建置節點？直接選擇租用方案。每台都是獨享實體 Mac mini，並非虛擬機。