클라우드 Mac 연결 및 빌드 가이드: SSH, VNC, CI

먼저 인스턴스 상태 확인

접속 방법 선택

콘솔에서 인스턴스 세부 정보를 열고 인스턴스 번호, 노드, 준비 상태를 확인하세요. 공인 주소, 사용자 이름, 포트 및 초기 접속 정보는 해당 인스턴스에 표시된 값을 기준으로 합니다. 다른 컴퓨터의 정보를 사용하지 마세요.

SSH 접속

빌드 명령 실행, 파일 전송, 로그 확인에 적합합니다. SSH 기본 포트는 22이며, 인스턴스에 다른 포트가 표시되면 해당 값을 사용하세요.

인스턴스 세부 정보에서 호스트 주소와 사용자 이름을 확인하세요. 처음 연결할 때는 호스트 지문을 확인한 다음 본인의 공개 키를 설정하세요. 개인 키는 로컬에 보관하고 지원 티켓에 첨부하지 마세요.

첫 빌드 예시 보기

VNC 그래픽 데스크톱

Xcode 실행, Simulator 확인, 그래픽 인터페이스 설정에 적합합니다. VNC 기본 포트는 5900이며, 연결 주소, 비밀번호, 실제 포트는 인스턴스 세부 정보에서 확인하세요.

연결한 뒤 데스크톱을 조작할 수 있는지 먼저 확인하세요. VNC 비밀번호를 코드 저장소에 사용하지 마세요. 네트워크에서 허용된다면 접근이 통제된 연결이나 SSH 터널을 우선 이용하세요.

그래픽 데스크톱 문제 해결

콘솔 웹 터미널

먼저 콘솔에 로그인한 뒤 인스턴스 세부 정보에 표시된 연결 방법을 확인하세요. 웹 터미널이 제공되는 경우 브라우저에서 HTTPS로 연결하며, 일반적으로 443을 사용하므로 터미널 포트를 별도로 입력할 필요가 없습니다.

접속 정보는 로그인한 계정 세션에서 가져오며, 공개된 독립 링크가 아닙니다. 인스턴스에 해당 연결 방법이 표시되지 않으면 SSH 또는 VNC를 이용하세요. 터미널 주소를 임의로 추측하지 마세요.

인스턴스 연결 방법 보기

한 번 빌드해 보고 파이프라인에 연결하세요

접속과 빌드를 따로 확인하세요

먼저 로그인할 수 있는지 확인한 다음 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이 공유 상태인지 확인하세요.

아카이브 성공이 업로드 완료를 뜻하지는 않습니다

업로드하려면 유효한 서명, 내보내기 설정, 업로드 자격 증명이 필요합니다. 예시는 프로젝트에 fastlane이 설정되어 있다고 가정합니다. Build 214는 실제 배포 확인이 아니므로 업로드 도구의 결과를 기준으로 확인하세요.

명확한 작업을 머신에 맡기세요

셀프 호스팅 러너 설정

MergeMac은 전용 물리 노드를 제공합니다. CI 저장소 권한, 작업 설정, 자격 증명은 직접 관리해야 합니다. 먼저 동일한 실행 사용자로 터미널에서 아카이브가 되는지 확인한 뒤 러너를 등록하세요. 그러면 환경 문제를 작업 스케줄링 문제로 오인하지 않을 수 있습니다.

GitHub Actions

대상 저장소 또는 조직의 Actions 러너 설정으로 이동해 macOS와 해당 Apple Silicon 아키텍처를 선택하세요.
대여한 노드에서 현재 페이지에 표시된 명령으로 러너를 다운로드하고 검증한 뒤 등록하세요. 등록 token은 민감 정보이므로 저장소에 올리거나 화면 캡처에 포함하지 마세요.
다음과 같은 태그를 추가하세요: mergemac、macos、m4。workflow의 runs-on 에서 해당 태그를 지정하세요.
먼저 Xcode 버전만 확인하는 작업을 제출해 올바른 노드에서 실행되는지 확인한 다음, 의존성 설치, 아카이브, 업로드 단계를 추가하세요.

신뢰할 수 없는 외부 풀 리퀘스트가 서명 자료를 보유한 러너를 직접 사용하게 하지 마세요. 배포 작업과 일반 검증 작업의 권한을 분리하세요.

GitLab Runner

프로젝트 또는 그룹에서 러너를 만들고 현재 등록 절차에 필요한 서비스 주소와 인증 token을 확인하세요.
노드에 해당 아키텍처의 GitLab Runner를 설치하고 생성된 안내에 따라 등록하세요. 로컬 Xcode 도구 체인이 필요하다면 적절한 Shell 실행 방식을 선택하세요.
다음 태그를 설정하세요: macos、xcode 등. 작업에도 해당 태그를 명시하세요. 배포 러너는 보호된 브랜치나 태그에서만 사용할 수 있도록 설정하세요.
먼저 환경 확인 작업을 실행해 작업 디렉터리, 실행 사용자, 키체인 접근을 확인한 뒤 정식 빌드를 활성화하세요.

token을 갱신하거나 대여 기간이 끝나기 전에 CI 플랫폼에서 해당 러너의 권한을 취소하세요. 노드에서 파일만 삭제해도 플랫폼 권한은 자동으로 취소되지 않습니다.

콘솔 용어 이해하기

여덟 가지 용어 한눈에 보기

이 용어는 리소스와 연결 방식을 설명합니다. 별도의 소프트웨어 라이선스를 뜻하지 않으며 여러 대의 컴퓨터가 자동으로 더 큰 Mac 한 대로 합쳐지는 것도 아닙니다.

물리 노드: 데이터센터에서 독립적으로 할당할 수 있는 Mac mini 한 대로, 실제 macOS 개발 환경을 실행합니다.
전용: 대여 기간 동안 CPU, GPU, 통합 메모리, 로컬 디스크를 포함한 전체 머신 리소스가 한 사용자에게만 할당됩니다.
비가상 머신: 물리 Mac의 운영체제를 직접 사용합니다. 공유 호스트에서 분리한 가상 인스턴스가 아닙니다.
VNC: macOS 그래픽 데스크톱을 원격으로 보고 조작하는 연결 프로토콜입니다.
SSH: 암호화된 명령줄 로그인, 명령 실행, 파일 전송에 사용하는 연결 프로토콜입니다.
셀프 호스팅 러너: 대여한 노드에 설치하는 CI 실행기로, 파이프라인 설정에 따라 빌드 작업을 수행합니다.
통합 메모리: Apple 칩의 CPU와 GPU가 함께 사용하는 메모리입니다. 실제 사용 가능 용량은 macOS와 다른 프로세스가 사용하는 공간을 제외한 값입니다.
Thunderbolt 5 병렬 연결: Thunderbolt 5로 여러 장치를 직접 연결해 멀티 노드 실험을 진행할 수 있습니다. 작업 분배는 애플리케이션 자체에서 지원해야 합니다.

증거를 저장한 다음 환경을 변경하세요

증상별로 원인 좁히기

실패 시간과 시간대, 인스턴스 번호, 전체 오류 메시지, 최근 변경 사항을 기록하세요. 한 번에 한 항목만 바꾸고 동일한 검증을 다시 실행하세요. 재설치는 첫 번째 해결책이 아닙니다.

01
VNC 검은 화면 또는 응답 없음

먼저 콘솔에서 인스턴스가 준비됐는지 확인한 다음 SSH 연결을 테스트하세요. SSH는 연결되는데 그래픽 데스크톱에 문제가 있다면 로그인, 로그아웃 또는 그래픽 세션 전환이 진행 중인지 확인하세요. 클라이언트를 종료한 뒤 다시 연결해 보세요.

화면이 계속 검게 표시되면 클라이언트 버전과 스크린샷을 보관해 지원 티켓을 제출하세요. 문제를 확인하려고 방화벽을 끄거나 강제로 재시작하지 마세요. 실행 중인 빌드가 중단될 수 있습니다.
02
Xcode 버전이 일치하지 않음

각각 xcode-select -p 와 xcodebuild -version을 실행하세요. 대화형 세션과 러너를 모두 확인해야 합니다. 여러 버전이 설치되어 있어도 명령줄에서 사용할 버전이 자동으로 바뀌지는 않습니다.

작업 하나에만 적용하려면 DEVELOPER_DIR 을 대상 Xcode의 Developer 디렉터리로 지정하세요. 그러면 시스템 전체의 기본 버전을 변경해 다른 작업에 영향을 주지 않습니다. 디렉터리가 없다면 설치 경로부터 확인하고 예시 이름을 그대로 복사하지 마세요.
03
Simulator가 디스크 공간을 모두 사용함

다음 명령으로 df -h 남은 공간을 확인한 뒤 DerivedData, 아카이브, 기기 데이터, 시뮬레이터 런타임도 점검하세요. 보관해야 하는 빌드 산출물을 먼저 내보내고 시뮬레이터를 사용하는 작업을 중지하세요.

xcrun simctl delete unavailable 을 실행하면 사용할 수 없는 시뮬레이터 기기 기록을 삭제할 수 있습니다. 모든 런타임을 삭제하는 명령은 아닙니다. 정리 전에 대상을 확인하고 프로젝트 디렉터리나 키체인에 재귀 삭제를 실행하지 마세요.
04
서명 인증서가 유효하지 않음

인증서 만료, 프로비저닝 프로파일 무효, 개인 키 누락, 키체인 잠금 여부를 구분하세요. 인증서 유효 기간, 팀, bundle identifier가 일치하는지 확인한 다음 CI 실행 사용자가 해당 개인 키에 접근할 수 있는지 점검하세요.

인증서를 갱신한 뒤 프로비저닝 프로파일과 보호된 변수도 갱신하고 동일한 scheme으로 다시 검증하세요. 지원 티켓에는 오류 코드와 민감 정보를 가린 로그만 첨부하세요. 개인 키, 인증서 내보내기 암호, 서명 자료 전체를 보내지 마세요.

먼저 백업한 다음 재설치를 확인하세요

재설치하면 환경이 바뀌며 작업 공간은 보존되지 않습니다

시스템 재설치와 대여 기간 종료 후 데이터 삭제는 별도의 절차입니다. 대여한 노드를 소스 코드, 서명 자료, 빌드 산출물의 유일한 저장 위치로 사용하지 마세요.

대여 기간 중 직접 재설치

콘솔에서 인스턴스 세부 정보를 열고 시스템 재설치를 실행하기 전에 CI 작업 예약을 중지하세요. 프로젝트, 산출물, 필요한 설정을 내보내고 다른 위치에서 백업을 열 수 있는지 확인하세요.

초기화에는 보통 몇 분이 걸립니다. 실제 소요 시간과 완료 상태는 콘솔에 표시된 내용을 기준으로 확인하세요. 작업 중에는 요청을 반복해서 제출하지 마세요. 완료 후 접속 정보를 다시 확인하고 호스트 지문을 검증한 다음 개발 환경을 다시 구성하세요.

재설치 후 SSH, Xcode, 의존성, 러너를 다시 확인하세요. 이전 서비스 설정이 그대로 남아 있다고 가정하지 마세요.

대여 종료 후 디스크 데이터 삭제

대여 기간이 끝나면 노드는 데이터 삭제 및 시스템 초기화 절차를 거친 뒤 다음 사용자에게 제공됩니다. 보관할 데이터는 만료 전에 직접 내보내세요. 만료 후에도 접속할 수 있을 것이라고 기대하지 마세요.

코드 저장소 배포 키, CI 러너 token, 업로드 자격 증명도 함께 취소하세요. 디스크 삭제는 노드 내부의 데이터를 처리할 뿐, 외부 시스템의 접근 권한까지 취소하지는 않습니다.

데이터 처리나 보안 범위에 대한 문의가 있다면 먼저 보안 안내를 확인한 뒤 콘솔 지원 티켓으로 해당 인스턴스에 대해 문의하세요.

보안 및 데이터 삭제 안내 보기

다음 답변으로 바로 문제를 해결할 수 있도록

지원팀에 문의하기

대여한 인스턴스 관련 문제는 주문 및 노드 정보와 연결하기 쉽도록 콘솔 지원 티켓으로 제출하는 것이 좋습니다. 로그인할 수 없는 경우, 대여 전 문의 또는 보안 제보는 지원 이메일로 보내세요. 같은 문제를 여러 채널에 반복해서 제출하지 마세요.

콘솔 지원 티켓

로그인한 뒤 티켓 페이지에서 인스턴스 번호, 영향 범위, 재현 단계를 입력하세요. 기존 문제의 진행 상황을 확인하려면 새 티켓을 만들지 말고 원래 티켓에 내용을 추가해 하나의 기록으로 관리하세요.

권장 형식: 발생 시간 및 시간대 → 기대 결과 → 실제 오류 → 시도한 조치. 민감 정보를 가린 최소한의 로그만 첨부하고 소스 코드 전체를 업로드하지 마세요.

로그인하고 티켓 제출

지원 이메일

계정에 로그인할 수 없다면 이메일 제목에 문의 유형을 적고 가입 이메일 주소와 확인에 필요한 주문 번호를 알려주세요. 계정 비밀번호나 결제 카드 번호는 보내지 마세요.

지원팀은 아시아·태평양 및 미국 동부 시간대에 맞춰 협업합니다. 첫 응답 시점은 문제의 우선순위와 현재 대기열에 따라 달라집니다. 구체적인 진행 상황은 티켓이나 이메일 답변을 확인하세요. 별도로 공지되지 않은 평균 응답 시간은 약속하지 않습니다.

support@mergemac.com

문의 및 문제 정리 안내 보기

환경을 설정하고 빌드를 맡기세요

이미 머신을 대여했다면 먼저 콘솔에서 상태를 확인하세요. 빌드 노드가 더 필요하다면 원하는 구성을 선택해 대여하세요. 모두 전용 물리 Mac mini이며 가상 머신이 아닙니다.

클라우드 Mac 지금 대여 콘솔로 돌아가기