클라우드 Mac 연결 및 iOS 자동화 빌드 가이드

작업 항목

증상에 맞는 기록부터 확인

각 항목에서 확인 대상, 명령어 또는 관찰 지표를 제공합니다. 필터는 아래 항목만 변경하며 전체 작업 섹션을 숨기지 않습니다.

CONNECTION

최초 연결 및 로컬 점검

콘솔에서 연결 정보를 확인하고 SSH, 그래픽 인터페이스, 비밀번호와 시간대를 점검합니다.

BUILD

iOS 자동 아카이브 및 내보내기

Xcode 도구 체인, 서명 입력값, 아카이브 경로 및 빌드 결과물 보관 규칙을 확인합니다.

AUTOMATION

CI/CD runner 연동

플랫폼 등록, 노드 태그, 동시 실행 한도 및 작업별 작업 디렉터리를 구분합니다.

DISPLAY

원격 화면 최적화

해상도, 색상, 프레임률, 네트워크 지터 순서로 상호작용 지연 원인을 좁혀 갑니다.

GLOSSARY

빌드 환경 용어

노드, runner, 캐시 및 서명 자산의 의미를 통일해 협업상의 혼선을 줄입니다.

DIAGNOSTICS

명령어 기반 문제 해결

네트워크, 디스크, Xcode 및 서명 문제를 명령어, 예상 결과와 분기별로 정리합니다.

ESCALATION

지원 요청 자료 정리

영역, 시간, 작업 번호와 마스킹된 로그를 제출해 지원팀이 재현할 수 있도록 합니다.

STORAGE

캐시 및 결과물 공간 점검

다시 생성할 수 있는 캐시, 아카이브 결과 및 반드시 보관해야 하는 릴리스 결과물을 구분합니다.

최초 연결

먼저 연결 방법을 확인한 후 노드 설정을 변경하세요

연결 정보는 콘솔에 표시되는 현재 인스턴스 상세 정보를 기준으로 합니다. 이전 지원 요청, 채팅 기록 또는 오래된 스크립트에서 주소와 인증 정보를 복사하지 마세요.

권장 순서 · 4개 항목

최초 로그인 점검표

먼저 안정적인 연결을 하나 확보한 뒤 비밀번호와 시간대를 확인하세요. 네트워크, 해상도, 인증 방식을 동시에 바꾸면 어떤 변수가 변화를 일으켰는지 판단하기 어렵습니다.

01
콘솔에서 현재 연결 정보 확인
노드 영역, 호스트 주소, 포트, 사용자 이름 및 인스턴스 상태를 확인하세요. 인증 정보는 관리되는 비밀번호 관리 도구에만 보관하고 코드 저장소나 빌드 로그에는 넣지 마세요.
02
SSH로 기본 연결 경로 먼저 검증
다음을 실행하세요. ssh -v user@host 해석, 핸드셰이크 및 인증 단계를 확인합니다. 연결 수립 전에 시간 초과가 발생하면 로컬 네트워크와 포트를 먼저 점검하고, 인증에 실패하면 사용자 이름과 현재 인증 정보를 다시 확인하세요.
03
작업에 맞는 그래픽 연결 선택
Xcode 인터페이스를 조작해야 할 때는 VNC 또는 화면 공유를 사용하세요. 먼저 기본 해상도와 색상 설정을 유지하고 키보드, 마우스 및 클립보드가 정상적으로 작동하는지 확인한 후 화질을 조정하세요.
04
최초 로그인 점검 완료
초기 비밀번호를 변경하고 date 및 systemsetup -gettimezone 를 실행해 시간과 시간대를 확인한 다음 프로젝트 디렉터리가 현재 작업 사용자 소유인지 확인하세요.

자동 패키징

빌드 입력값과 결과물 경로를 기록에 남기세요

재현 가능한 iOS 빌드를 위해 도구 체인, 프로젝트 진입점, 서명 자산, 아카이브 매개변수 및 내보내기 위치를 고정해야 합니다. 단순히 '빌드 실패'라고 기록하는 것만으로는 재검토할 수 없습니다.

01 / TOOLCHAIN

Xcode 명령줄 도구 고정

먼저 xcode-select -p 및 xcodebuild -version을 실행해 스크립트가 실제로 사용하는 개발자 디렉터리와 Xcode 버전을 확인하세요. 버전을 전환한 후 두 명령을 다시 실행하고 터미널 창 제목에 의존하지 마세요.

02 / SIGNING

인증서, 개인 키 및 프로비저닝 프로파일 분리

서명 자산은 프로젝트와 환경별로 접근 범위를 제한해야 합니다. 가져온 후 security find-identity -v -p codesigning 을 사용해 사용 가능한 ID를 확인하고 인증서 비밀번호가 파이프라인 로그에 출력되지 않도록 하세요.

03 / ARCHIVE

workspace, scheme 및 아카이브 경로 명시

스크립트에서 workspace 또는 project, 공유 scheme, configuration 및 -archivePath를 명시적으로 지정해야 합니다. 빌드 머신에서 이전 Xcode 그래픽 인터페이스의 임시 선택에 의존하지 마세요.

04 / EXPORT

결과물과 로그 함께 보관

다음과 같은 옵션인 -exportArchive 와 버전 관리되는 내보내기 설정을 사용해 결과물을 생성하세요. 아카이브, 내보내기 결과, 빌드 로그 및 커밋 식별자를 보관하고 실패 시에도 민감정보를 마스킹한 진단 정보를 남기세요.

BUILD RECORD 아카이브 명령어 기본 구조

xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  -archivePath "$PWD/output/App.xcarchive" \
  clean archive

입력커밋 식별자, 종속성 잠금 파일, Xcode 버전, scheme

출력아카이브 디렉터리, 내보내기 디렉터리, 원본 로그, 작업 번호

실패 시 보관종료 코드, 첫 번째 오류 구간, 환경 버전. 민감한 값은 보관하지 않음

CI/CD 연동

runner 등록은 시작일 뿐, 격리 규칙이 장기 운영을 좌우합니다

OakVM 노드는 전용 물리 머신이며 가상 머신이 아닙니다. 동시 실행은 전용 노드를 추가해 확장하고, 같은 노드의 작업도 큐, 태그 및 작업 디렉터리 경계를 명확히 정의해야 합니다.

GITHUB ACTIONS

태그로 프로젝트를 지정 노드에 라우팅

저장소 또는 조직 범위에서 self-hosted runner를 생성하고 등록 범위를 기록하세요.
영역, 칩 및 용도 태그를 사용하세요. 예를 들어 프로젝트 릴리스와 일상 테스트를 분리합니다.
워크플로는 runs-on 과 정확히 일치시켜 의미가 모호한 일반 태그를 사용하지 마세요.
작업이 끝나면 임시 키체인, 임시 디렉터리 및 해당 실행에만 필요한 환경 변수를 정리하세요.

GITLAB CI

runner 범위와 작업 태그 명확히 지정

runner가 인스턴스, 그룹 또는 프로젝트에 속하는지 확인해 관련 없는 프로젝트가 실행하지 못하도록 하세요.
작업에 tags를 선언하고 태그가 없는 작업을 받을 필요가 없으면 해당 기능을 끄세요.
캐시에 프로젝트 단위 키를 설정해 서로 다른 브랜치나 앱이 호환되지 않는 결과를 공유하지 않도록 하세요.
노드 로그와 연결할 수 있도록 작업 번호, 커밋 식별자 및 runner 이름을 보관하세요.

GENERIC RUNNER

일반 runner는 먼저 수명 주기를 정의하세요

등록 스크립트, 서비스 시작 방식 및 로그 위치를 팀 운영 매뉴얼에 포함해야 합니다.
작업마다 독립 작업 디렉터리를 만들고 종료 후 보존 정책에 따라 캐시와 결과물을 처리하세요.
같은 물리 노드에 명확한 동시 실행 상한을 설정해 여러 대형 아카이브 작업이 리소스를 경쟁하지 않도록 하세요.
노드는 365일 연중 정상 운영되며, 작업 재시도에도 상한을 설정하고 실패 원인을 기록해야 합니다.

격리 기준:프로젝트 디렉터리, 빌드 캐시, 서명 자산 및 결과물 디렉터리를 각각 관리하세요. 일상적인 격리를 위해 노드 전체를 비우지 말고, 두 프로젝트가 같은 쓰기 가능한 서명 디렉터리 세트를 공유하지 않도록 하세요.

원격 화면

화면 부하부터 네트워크 경로까지 단계별 점검

VNC와 화면 공유에서 느껴지는 지연이 반드시 노드의 연산 부하 때문인 것은 아닙니다. 일정한 순서로 테스트하면 인코딩 부하, 로컬 네트워크 지터 및 백그라운드 작업 경합을 구분할 수 있습니다.

01
해상도 낮추기
먼저 현재 작업에 필요한 최소 해상도로 낮추고 사용하지 않는 추가 화면 영역을 끄세요. 응답성이 크게 좋아지면 문제는 화면 인코딩량과 관련 있을 가능성이 높습니다.
포인터와 창 이동 관찰
02
색상과 동적 콘텐츠 줄이기
동영상, 애니메이션 미리보기 및 계속 새로 고침되는 모니터링 창을 일시 중지하세요. 빌드 중에는 불필요한 시뮬레이터 화면을 끄고 정적인 편집 작업이 안정되는지 확인하세요.
정적 화면과 동적 화면 비교
03
목표 프레임률 조정
코드 편집과 릴리스 작업에는 보통 높은 프레임률이 필요하지 않습니다. 먼저 입력 응답성과 글자 선명도를 기준으로 삼고 화면 움직임을 단계적으로 높이세요.
입력 지연 변화 기록
04
네트워크 지터 확인
노드 주소에 짧은 지연 시간 테스트를 연속 실행하고 단일 최저값이 아니라 변동과 패킷 손실에 주목하세요. 로컬 네트워크를 바꾼 후 동일한 샘플 수로 다시 테스트하세요.
샘플 요약 보관
05
팀 공유 방식 확인
한 작업에는 주 작업자 한 명만 두고 다른 구성원은 빌드 로그와 결과물 기록으로 협업하세요. 여러 사람이 동시에 그래픽 인터페이스를 조작하면 컨텍스트 충돌이 늘어납니다.
현재 작업자 명확히 지정

용어집

용어를 먼저 통일한 후 설정과 경계를 논의하세요

다음 용어는 OakVM 페이지, 콘솔 및 지원 커뮤니케이션에서 사용됩니다. 서비스 제공 형태와 워크플로를 설명하며 타사 플랫폼의 보증을 의미하지 않습니다.

물리 노드: macOS와 빌드 작업을 직접 실행하는 Apple Silicon 실물 장치로, 주문에 할당된 컴퓨팅 단위입니다.
전용: 대여 기간 동안 노드의 컴퓨팅 리소스는 현재 주문이 사용하며 다른 고객의 작업과 같은 물리 머신을 공유하지 않습니다.
클라우드 Mac: 데이터 센터에 배포되어 네트워크로 접속하는 Mac 환경으로, 그래픽 작업, 명령줄 빌드 및 자동화 작업에 사용할 수 있습니다.
가상 머신 아님: 주문에는 공유 호스트에서 분할된 가상 컴퓨팅 인스턴스가 아닌 전용 물리 머신이 제공됩니다.
VNC: macOS 그래픽 인터페이스를 원격으로 보고 조작하는 연결 방식 중 하나이며, 해상도, 화면 변화 및 네트워크 지터의 영향을 받습니다.
self-hosted runner: CI/CD 플랫폼에 등록되어 직접 보유하거나 대여한 노드에서 파이프라인 작업을 가져와 실행하는 에이전트입니다.
빌드 캐시: 반복적인 다운로드나 컴파일을 줄이기 위해 보관하는 데이터로, 종속성 캐시와 DerivedData 등이 있습니다. 무효화 및 재생성이 가능해야 합니다.
서명 자산: 앱 서명에 필요한 인증서, 개인 키, 프로비저닝 프로파일 및 관련 접근 권한이며 최소 권한 원칙으로 관리해야 합니다.

문제 해결

각 점검 항목에 명령어, 예상 출력 및 예외 상황을 기록하세요

먼저 원본 종료 코드와 첫 번째 유효 오류를 저장한 후 수정하세요. 여러 정리 명령을 연속 실행하면 문제 상황이 사라지고 종속성 오류를 노드 장애로 잘못 판단할 수 있습니다.

클라우드 Mac에서 자주 발생하는 문제의 명령어 점검표
점검 대상	명령어 또는 작업	예상 결과	예외 상황
네트워크 해석 및 연결 가능성	`ping -c 20 host` `ssh -v user@host`	주소 해석이 일치하고 샘플에서 지속적인 패킷 손실이 없으며 SSH가 핸드셰이크 및 인증 단계로 진행됩니다.	해석 오류가 발생하면 주소를 확인하세요. 연결 전에 시간 초과가 발생하면 로컬 경로를 바꿔 재테스트하고, 인증 실패 시 현재 사용자 이름과 인증 정보만 확인하세요.
디스크 및 빌드 공간	`df -h` `du -sh ~/Library/Developer/Xcode/DerivedData`	대상 볼륨에 소스 코드, 종속성, 아카이브 및 내보내기 결과를 저장할 충분한 공간이 있으며 캐시 크기가 팀 기준 이내입니다.	반드시 보관해야 하는 결과물을 먼저 옮긴 후 프로젝트별로 다시 생성 가능한 캐시를 삭제하세요. 소유권을 확인할 수 없는 아카이브 디렉터리는 바로 삭제하지 마세요.
Xcode 도구 체인	`xcode-select -p` `xcodebuild -version`	개발자 디렉터리와 버전이 파이프라인 기록과 일치하고 명령어가 정상적으로 반환됩니다.	경로 오류가 있으면 도구 체인을 명시적으로 전환하세요. 버전이 다르면 작업을 중지해 비교할 수 없는 아카이브가 생성되지 않도록 하세요.
프로젝트 및 scheme	`xcodebuild -list -workspace App.xcworkspace`	대상 scheme이 표시되고 자동화에 사용하는 scheme이 공유되어 있습니다.	목록이 비어 있으면 작업 디렉터리와 종속성 생성 단계를 확인하세요. scheme이 보이지 않으면 프로젝트 공유 설정과 이름의 대소문자를 확인하세요.
서명 ID	`security find-identity -v -p codesigning`	현재 작업에 필요한 서명 ID가 표시되며 만료되었거나 중복 선택으로 인한 혼선이 없습니다.	ID가 없으면 가져오기 범위, 키체인 접근 권한 및 프로비저닝 프로파일의 일치 여부를 확인하세요. 개인 키나 비밀번호를 공개 페이지에 붙여 넣지 마세요.
아카이브 및 내보내기	다음 항목을 보관하세요: `xcodebuild` 종료 코드, 아카이브 경로 및 내보내기 로그.	아카이브 디렉터리가 존재하고 내보내기 결과가 커밋 식별자 및 작업 번호와 연결되어 있습니다.	로그의 첫 번째 error부터 확인하세요. 컴파일, 서명, 아카이브 및 내보내기 단계를 각각 판단하고 마지막 한 줄로 전체 실패를 요약하지 마세요.

RULE 01

한 번에 변수 하나만 변경

네트워크를 전환한 후에는 화면 설정을 그대로 유지하고, Xcode를 전환한 후에는 소스 커밋을 그대로 유지하세요. 그래야 전후 결과를 비교할 수 있습니다.

RULE 02

첫 번째 유효 오류 보관

뒤에 나오는 오류는 연쇄 결과인 경우가 많습니다. 가장 먼저 발생한 오류 구간, 종료 코드 및 해당 명령어를 기록하세요.

RULE 03

로그는 마스킹 후 공유

호스트 인증 정보, 토큰, 개인 키 내용 및 프로젝트의 민감한 경로를 제거하되 시간, 작업 번호 및 도구 버전은 남기세요.

지원 요청

직접 원인을 찾기 어렵다면 다시 검토할 수 있는 작업 기록을 제출하세요

기존 사용자는 먼저 콘솔에 로그인해 지원 요청을 제출하세요. 로그인할 수 없다면 support@oakvm.com으로 이메일을 보내세요. 두 경로 모두 공개 페이지에 연결 인증 정보를 붙여 넣을 필요가 없습니다.

SUPPORT PACKET 첨부 권장 정보 6가지

01노드 영역

싱가포르, 일본(도쿄), 한국(서울), 홍콩, 미국 동부 또는 미국 서부.

02발생 시간

노드 로그를 맞출 수 있도록 날짜, 시간 및 시간대를 명시하세요.

03작업 번호

주문, 인스턴스 또는 CI 작업에서 식별 가능한 번호를 제공하세요.

04재현 단계

진입 경로, 명령어 및 문제가 발생하기 전 마지막 성공 단계를 나열하세요.

05예상 결과와 실제 결과

'사용할 수 없음'이라고만 쓰지 말고 예상 출력과 실제 출력을 각각 설명하세요.

06마스킹된 로그

오류 맥락, 종료 코드 및 버전은 남기고 인증 정보, 토큰 및 개인 키 내용은 제거하세요.

전용 물리 머신 · 가상 머신 아님 · USD 결제

기존 파이프라인에 연결할 클라우드 Mac이 필요하신가요?

OakVM M4 또는 OakVM M4 Pro를 선택하고 6개 노드 영역 중 하나에서 대여 기간을 구성하세요. 모든 영역은 365일 연중 정상 운영되며 실제 가용성은 콘솔의 실시간 응답을 기준으로 합니다.

Mac 빌드 노드 지금 대여하기 가격 및 구성 보기