빌드 연결 가이드

노드를 파이프라인에 연결하세요

팀 전용 물리 Mac이 준비되었습니다. 먼저 연결을 확인하고, 도구 체인을 고정한 다음 Runner를 등록하세요. 이 체크리스트로 처음 30분을 계획할 수 있습니다. 프로젝트에 따라 의존성 다운로드와 전체 빌드에 걸리는 시간은 달라집니다.

아직 노드를 대여하지 않으셨나요? Apple Silicon M4 / M4 Pro, 전체 장비 단독 사용, 가상 머신 아님, 하루 $20.1부터.

물리 Mac 노드 대여 콘솔 열기

노드 수령 후 먼저 확인하세요

자동화 작업을 등록하기 전에 사용할 수 있는 그래픽 연결을 하나 확보하고 SSH도 확인하세요. 유일한 연결 방법이 검증되기 전에 암호 로그인을 끄지 마세요.

01
연결 정보 확인

콘솔에 로그인해 해당 인스턴스의 상세 페이지에서 노드 ID, 주소, 사용자 이름과 연결 안내를 확인하세요. 인증 정보는 계정에서만 확인하고, 문의 내용이나 파이프라인 설정, 코드 저장소에 복사하지 마세요.
02
데스크톱 열기 및 비밀번호 변경

인스턴스 상세 페이지에서 브라우저 원격 데스크톱을 열고 해당 인스턴스의 macOS 환경인지 확인하세요. 처음 로그인한 뒤 시스템 사용자 비밀번호를 변경하고 팀의 비밀번호 관리자에 저장하세요. 갱신과 인증 정보 교체 담당자도 정해 두세요.
03
원격 로그인 설정

macOS 시스템 설정의 공유 옵션에서 원격 로그인을 확인하고 필요한 사용자만 허용하세요. 콘솔에 표시된 주소와 포트로 연결하세요. 기본 포트가 아니라면 ssh 명령에 포트를 명시하세요.
04
키 인증 연결 확인

업무용 컴퓨터에서 전용 SSH 키를 생성하고 노드의 authorized_keys에는 공개 키만 추가하세요. 현재 세션은 유지한 채 터미널을 하나 더 열어 키 로그인이 되는지 확인한 다음 다른 인증 설정을 변경하세요.

노드 권한 확인

mkdir -p ~/.ssh
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
whoami
sw_vers
uname -m

확인 결과: 사용자 이름이 인스턴스 인증 정보와 일치하고, 시스템 버전이 프로젝트 요구 사항에 맞아야 합니다. Apple Silicon 환경의 아키텍처 출력은 arm64여야 합니다. 최초 SSH 연결에서 지문 확인 메시지가 표시되면 먼저 호스트 신원을 확인하세요. 연결을 위해 호스트 키 검증을 바로 끄지 마세요.

연결 후 먼저 명령 실행하기

명령줄에서 확인한 뒤 CI에 연결하세요

아래는 출력 형식 예시이며 실제 노드의 기록이 아닙니다. 예시 프로젝트 이름은 TeamApp입니다. 저장소의 workspace, scheme, 서명 설정에 맞게 바꾸세요.

glide-m4 — ssh

$ ssh "$NODE_USER@$NODE_ADDRESS"
Authenticated using "publickey".
$ uname -m
arm64

$ xcodebuild -workspace TeamApp.xcworkspace \
  -scheme TeamApp -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath build/TeamApp.xcarchive archive
** ARCHIVE SUCCEEDED **

$ bundle exec fastlane gym --scheme TeamApp
Successfully exported and compressed dSYM file
Successfully exported and compressed ipa file
Successfully generated ipa file:
build/TeamApp.ipa

연결에 성공해도 환경이 준비된 것은 아닙니다

SSH 연결 후 Ruby, Bundler 및 프로젝트 의존성을 계속 확인하세요. 저장소에 고정된 버전을 우선 사용해 팀 전체의 빌드 환경을 바꾸는 전역 업그레이드 명령은 피하세요.

확인 기준: 동일한 사용자로 저장소에 접근해 의존성 설치 명령을 실행할 수 있어야 합니다.

아카이브와 내보내기를 따로 확인하세요

Archive는 성공했지만 IPA 내보내기가 실패한다면 내보내기 방식, 서명 인증서 및 프로비저닝 프로파일을 먼저 확인하세요. 마지막 실패 메시지만 캡처하지 말고 첫 번째 오류와 앞뒤 맥락을 보관하세요.

확인 기준: 지정된 경로에 후속 작업에서 사용할 빌드 산출물이 있어야 합니다.

자동화 연결 · 팀 저장소 연결

명확한 태그로 작업을 이 Mac에 할당하세요

노드는 전용 물리 장비지만 프로젝트의 병렬 실행 가능 여부는 메모리, 디스크 및 작업 격리 방식에 따라 달라집니다. 먼저 빌드 작업 하나로 전체 흐름을 확인한 뒤 동시 실행 수를 늘리세요.

GitHub Actions self-hosted runner

저장소 또는 조직의 Actions 설정에서 self-hosted runner를 추가하고 macOS와 ARM64를 선택하세요. 해당 페이지에서 제공하는 최신 다운로드, 검증 및 등록 명령을 사용하고 출처가 불분명한 오래된 설치 패키지는 사용하지 마세요.

등록할 때 전용 시스템 사용자를 지정하고 용도 태그를 추가하세요. vmfly,ios-build 등을 태그로 추가하세요. 워크플로의 runs-on 을 해당 태그로 지정해 작업이 공유 실행 환경에 배정되지 않도록 하세요.

runs-on: [self-hosted, macOS, ARM64, vmfly, ios-build]

확인 기준: 관리 페이지에 Runner가 온라인으로 표시되고, 수동으로 실행한 작업을 이 노드가 처리해야 합니다.

GitLab Runner

GitLab 환경과 호환되는 Runner 버전을 사용하고 프로젝트 또는 그룹의 Runner 생성 절차에 따라 인증 토큰을 발급받으세요. macOS에서는 shell executor를 사용하고 노드에 macos-arm64 와 용도 태그를 지정하세요.

파이프라인 작업에 동일한 tags를 지정하세요. Runner 작업 디렉터리의 소유자가 실행 사용자와 일치하는지 확인하세요. 인증서, 의존성 캐시 및 아카이브 출력에도 같은 사용자가 접근할 수 있어야 대화형 터미널에서는 성공하고 자동 작업에서는 실패하는 상황을 막을 수 있습니다.

ios_archive:
  tags:
    - macos-arm64
    - ios-build
  script:
    - bundle exec fastlane gym

확인 기준: 테스트 작업에서 시스템 아키텍처를 출력하고 프로젝트에 필요한 도구 체인을 읽을 수 있어야 합니다.

재시작 후 복구도 확인하세요

GitHub Runner는 등록 디렉터리에서 서비스 스크립트를 실행해 ./svc.sh install 한 다음 ./svc.sh start하면 됩니다. GitLab Runner는 설치 방식에 따라 gitlab-runner install 과 gitlab-runner start를 실행하세요. 동일한 Runner에 자동 시작 방식을 두 가지 중복 설치하지 마세요.

macOS에서 사용자 LaunchAgent로 실행되는 서비스는 일반적으로 해당 사용자의 로그인 세션에 의존합니다. 서비스가 실제로 생성한 설정과 실행 사용자를 확인하고, ‘시동 시 실행’을 ‘빌드 사용자 로그인 완료’와 혼동하지 마세요. 배포 작업이 없을 때 재시작 후 온라인 상태, 경로, 키체인 접근 및 산출물 내보내기를 한 번 검증하세요.

서명 자료의 접근 범위를 제한하세요

팀에서 승인한 안전한 방식으로 빌드 인증서와 프로비저닝 프로파일을 전달하세요. 인증서에는 해당 개인 키가 포함되어야 하며 공개 인증서만 가져와서는 서명할 수 없습니다. 잠금 해제 비밀번호와 자동화 토큰은 CI 보호 변수에 저장하고 사용할 수 있는 브랜치와 작업을 제한하세요.

팀에서 fastlane match를 사용한다면 기존 저장소와 접근 정책을 그대로 따르세요. CI가 기존 서명 자료를 읽을 때는 읽기 전용 모드를 우선 사용하세요. 아카이브 명령 자체를 점검하기 전에 bundle identifier, 대상 팀, 내보내기 방식 및 프로비저닝 프로파일의 유효 기간이 서로 맞는지 확인하세요.

무인 작업에서도 지정된 키체인에 접근할 수 있어야 합니다. 장기간 사용하는 평문 비밀번호를 스크립트에 넣거나 로그에 모든 환경 변수를 출력하지 마세요. 로그를 공유하기 전에 개인 키, 토큰, 비밀번호 및 서명 자료를 제거하세요.

도구 체인 확인 · 버전 재현성

Xcode 경로를 고정하고 캐시는 별도로 관리하세요

먼저 노드의 현재 환경을 확인한 다음 프로젝트에 필요한 버전을 설치할지 결정하세요. 대화형 데스크톱에서 선택한 Xcode가 Runner 프로세스에서도 사용된다고 가정하지 마세요.

현재 선택 확인. 경로를 전환할 때는 실제 설치 디렉터리로 바꾸세요

xcodebuild -version
xcode-select -p
xcrun simctl list runtimes

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -checkFirstLaunchStatus

여러 버전 함께 사용하기

서로 다른 Xcode 앱에는 구분하기 쉬운 파일 이름을 지정하세요. 공유 노드에서 프로젝트마다 다른 버전을 쓴다면 매번 시스템 전체의 기본 선택을 바꾸기보다 작업 안에서 DEVELOPER_DIR를 설정하세요.

확인 기준: Runner가 실제로 실행한 작업 로그에 xcodebuild -version이 출력되고 프로젝트 요구 사항과 일치해야 합니다.

시뮬레이터 런타임

Xcode 설정에서 프로젝트에 필요한 런타임을 설치한 다음 xcrun simctl list 로 사용 가능한 기기를 확인하세요. UI 테스트에서는 destination을 명시해 존재하지 않는 OS 버전이나 기기를 기다리는 일을 방지하세요.

확인 기준: 먼저 대상 시뮬레이터를 단독으로 실행한 다음 최소 UI 테스트를 수행하세요.

DerivedData 및 빌드 산출물

프로젝트별 DerivedData 경로를 지정하고 필요한 캐시만 보관하며 산출물 보존 정책을 설정하세요. 정리 전에 관련 빌드를 중지하고 디렉터리 내용과 사용량을 확인하세요. 공유 작업 디렉터리에 재귀 삭제 명령을 바로 실행하지 마세요.

확인 기준: 의존성, 캐시 및 IPA의 저장 디렉터리가 명확하고 다음 아카이브에 필요한 디스크 공간이 남아 있어야 합니다.

자동화에 연결하기 전에 Xcode 최초 실행에 필요한 구성 요소를 설치하세요. 대화형 터미널에서는 명령을 찾지만 CI에서는 찾을 수 없다고 나온다면 모든 의존성을 재설치하기 전에 실행 사용자, PATH, 작업 디렉터리 및 셸 초기화 방식을 비교하세요.

그래픽 연결 · 작업을 위한 대안 확보

디버깅 작업에 맞는 연결 방식을 선택하세요

브라우저 데스크톱은 최초 설정에 적합하고, 그래픽 작업을 오래 한다면 클라이언트 연결을 비교해 보세요. 무인 빌드에는 SSH와 Runner를 사용하세요. 코드와 산출물을 보관하는 유일한 장소로 그래픽 연결 세 가지 중 어느 것도 사용하지 마세요.

아래 내용은 초기 설정 권장 사항이며 네트워크 지연이나 화면 성능을 보장하지 않습니다.
연결 방식	권장 작업	초기 설정	끊길 때 먼저 확인할 항목
브라우저 원격 데스크톱	최초 로그인, 시스템 설정, 빌드 진행 상황을 임시로 확인	콘솔에서 인스턴스 상세 페이지를 여세요. 우선 단일 화면과 적당한 해상도로 시작하세요.	로컬 네트워크, 브라우저 확대/축소, 데스크톱 세션을 여러 개 동시에 열었는지 확인
VNC 클라이언트	그래픽 인터페이스를 장시간 조작하고 클라이언트 인코딩 및 화질 조정	인스턴스 연결 안내에 따라 설정하세요. 먼저 자동 인코딩 또는 균형 잡힌 화질을 선택하세요.	화질이나 색 심도를 단계적으로 낮추고 여러 설정을 한꺼번에 바꾸지 마세요.
macOS 화면 공유	로컬 Mac에서 데스크톱 디버깅 및 보조 작업	인스턴스에서 지원하는 연결 방식을 사용하고 단일 화면 1920 × 1080부터 시작하세요.	고해상도, 움직임이 많은 화면 및 네트워크 구간을 확인하세요. 먼저 해상도를 낮춘 뒤 비교하세요.

화면 지연과 빌드 지연을 구분해 기록하세요

데스크톱 화면 잔상만으로 컴파일 작업이 느려졌다고 볼 수는 없습니다. SSH로 작업 출력과 리소스 사용량을 확인해 빌드가 계속 진행 중인지 살펴보세요. 반대로 데스크톱이 원활하더라도 서명, 의존성 다운로드 또는 원격 저장소 접근이 정상이라는 뜻은 아닙니다.

연결 문제가 발생하면 사용 방식, 발생 시각과 시간대, 로컬 네트워크 유형, SSH 연결 여부를 기록하세요. 원격 로그인이나 화면 공유 설정을 변경할 때는 기존 연결을 유지해 변경 후 모든 연결 수단을 잃지 않도록 하세요.

구독 관리 · 먼저 주문 확인

빌드 일정에 맞춰 청구 내용을 변경하세요

계정, 인스턴스 및 청구는 콘솔에서 관리합니다. 갱신이나 구성을 변경하기 전에 주문 ID와 인스턴스 ID를 확인해 임대 기간이 확정되기 전에 배포 작업을 잡지 않도록 하세요.

갱신 및 만료

콘솔에서 현재 구독, 만료 시각 및 미결제 청구서를 확인하세요. 결제 후 구독 상태를 다시 확인하세요. 만료 전에 코드, 인증서 백업 및 빌드 산출물을 팀이 관리하는 위치로 동기화하고 만료되는 노드를 장기 백업으로 사용하지 마세요.

갱신하지 않은 노드는 만료 후 서비스가 중단되고 디스크 전체가 삭제됩니다. 보관해야 하는 데이터는 미리 다른 곳으로 옮기세요.

플랜 변경 및 스토리지 확장

Glide M4는 Apple Silicon M4, 메모리 16GB, SSD 256GB입니다. Cruise M4 Pro는 Apple Silicon M4 Pro, 메모리 64GB, SSD 2TB입니다. 플랜을 변경하기 전에 문의를 제출해 처리 방법을 확인하세요. 기존 장비의 메모리를 즉시 업그레이드하는 것으로 이해하지 마세요.

+1TB SSD, +2TB SSD 및 Thunderbolt 5 병렬 연결 옵션은 주문 시 확인하세요. 이미 대여한 노드를 변경하려면 먼저 문의를 제출해 확인을 받으세요.

결제 및 입금 확인

USDT-TRC20 및 Visa / Mastercard / Amex(Stripe)만 지원하며 모든 요금은 USD로 결제됩니다. 실제 사용 가능한 결제 수단은 API 응답을 기준으로 하며, 결제가 확인된 뒤 물리 장비 배정이 시작됩니다.

결제 상태가 갱신되지 않으면 주문 ID와 결제 증빙을 첨부하세요. USDT 결제는 거래 해시도 함께 보내세요. 중복 결제하지 말고 전체 카드 번호를 보내지 마세요.

콘솔 청구 내역 보기

문제 상황을 지원팀에 전달하세요

계정이 있다면 콘솔에서 문의를 제출하고 진행 상황을 확인하세요. 노드 ID, 오류 발생 시각과 시간대, 재현 절차 및 민감 정보를 삭제한 로그 일부를 첨부하세요. 구매 전 문의 또는 로그인할 수 없는 경우 연락처 페이지에서 support@vmfly.com을 확인하세요.

‘예상 결과’와 ‘실제 결과’를 설명하고 SSH, 데스크톱, Runner 중 어떤 기능을 계속 사용할 수 있는지도 알려 주세요. 비밀번호, 개인 키 또는 전체 결제 카드 정보를 첨부하지 마세요.

콘솔에서 문의 제출 연락 안내 보기