팀 빌드 설정 가이드

러너 설정, 여기서 시작하세요

Apple Silicon M4 Mac mini 전체를 팀 작업 전용으로 사용하세요. 먼저 인스턴스와 연결을 확인하고 러너를 등록한 다음 Xcode 툴체인을 고정하세요. 문제를 발생한 단계에서 해결하면 전체 파이프라인을 다시 설정할 필요가 없습니다.

빌드 노드 임대 내 인스턴스 보기

기존 주문은 콘솔에서 상태를 확인하세요. 등록 토큰, SSH 비밀번호, 서명 자료는 공개 로그에 남기지 마세요.

주문부터 연결까지

네 가지 점검 단계로 노드 시작하기

결제 확인 후 접속 정보를 받아 확인하는 데 약 4분이 걸립니다. 아래 시간은 절차를 진행할 때의 참고값이며, 결제 게이트웨이 확인, 네트워크 재시도, 종속 항목 설치, 러너 등록 시간은 포함하지 않습니다. 실제 진행 상태는 콘솔을 기준으로 확인하세요.

확정된 주문 확인
약 30초

콘솔에서 주문 결제가 완료됐는지 확인하고, 모델·기간·노드가 구매 내용과 일치하는지 점검하세요. Merge M4 S는 16GB RAM / 256GB SSD, Merge M4 L은 24GB RAM / 512GB SSD이며, 두 모델 모두 Apple Silicon M4를 사용합니다.

여기서 막혔다면 먼저 청구 상태를 확인하세요. 페이지가 아직 갱신되지 않았다고 결제를 반복하지 마세요. 주문 번호를 보관한 뒤 이 페이지의 청구 섹션에서 결제 내역을 확인하세요.
물리 노드 할당 확인
약 2분

주문에 연결된 인스턴스 상세 정보를 열고 시스템에서 인스턴스 상태와 연결 정보를 불러올 때까지 기다리세요. 각 머신은 한 고객에게만 할당되는 비가상 머신입니다. 같은 팀의 작업 예약은 팀이 설정한 러너가 관리합니다.

여기서 막혔다면 인스턴스 ID, 주문 번호, 현재 상태를 기록해 콘솔에서 지원 티켓을 제출하세요. ‘결제 완료’를 ‘인스턴스 접속 정보 생성 완료’로 간주하지 마세요.
접속 정보 확인
약 1분

인스턴스 상세 정보에서 SSH 주소, 포트, 사용자 이름과 VNC 연결 정보를 확인하세요. 표시된 항목을 그대로 사용하고, 기본 포트를 추측하거나 이전 인스턴스의 주소와 비밀번호를 재사용하지 마세요.

여기서 막혔다면 현재 로그인한 계정이 해당 주문을 소유하는지 확인한 다음 올바른 인스턴스를 열었는지 점검하세요. 지원 티켓에는 인스턴스 ID와 누락된 항목 이름만 적으면 됩니다. 전체 비밀번호는 보내지 마세요.
04
원격 연결 테스트
약 30초
SSH는 명령줄 빌드, 러너 등록, 파일 동기화에 사용하고, VNC는 Xcode GUI, 시뮬레이터, 대화형 설정에 사용합니다. macOS GUI와 명령줄을 모두 이용할 수 있으며, 두 방식을 함께 활용할 수도 있습니다.
```
ssh -p "$SSH_PORT" "$SSH_USER@$SSH_HOST"
uname -m
sw_vers
```
처음 연결할 때는 호스트 지문을 확인하세요. 연결에 성공하면 아키텍처 출력이 arm64인지 확인하세요. 시간 초과가 발생하면 주소, 포트, 로컬 네트워크를 점검하고, 인증에 실패하면 사용자 이름과 접속 정보를 확인하세요. 호스트 신원 확인을 끄는 방식으로 지문 이상을 우회하지 마세요.

VNC 클라이언트에는 인스턴스 상세 정보에 표시된 해당 연결 항목을 사용하세요. SSH 포트를 그대로 사용하지 마세요. 연결 후 화면이 느리면 해상도를 낮추세요. 자동 빌드는 계속 SSH로 실행할 수 있습니다.

인스턴스 및 접속 정보 확인 원격 연결 안내 보기

기존 팀 CI 활용

작업을 이 M4에 정확히 할당하기

먼저 CI 플랫폼의 러너 또는 에이전트 추가 페이지에서 설치 파일과 등록 명령을 확인한 뒤 노드에서 실행하세요. 아래는 등록 시 확인할 항목입니다. 토큰, 조직 주소, 작업 디렉터리는 플랫폼에서 발급되므로 예시 변수를 그대로 복사하지 마세요. 설치 후에는 서명 자료가 필요 없는 테스트 작업을 먼저 실행하세요.

GitHub Actions

저장소 또는 조직 설정에서 self-hosted runner를 추가하고 macOS 및 ARM64 패키지를 선택하세요. 압축을 푼 뒤 러너 디렉터리에서 플랫폼이 제공한 설정 명령을 실행하고 프로세스를 시작하세요.

./config.sh \
  --url "$RUNNER_URL" \
  --token "$RUNNER_TOKEN" \
  --labels macos-m4
./run.sh

워크플로에서 runs-on: [self-hosted, macOS, ARM64, macos-m4]를 지정하고 태그가 등록 결과와 일치하는지 확인하세요. 태그는 작업을 라우팅하는 데 사용되며, 머신이 작업을 자동으로 격리한다는 뜻은 아닙니다.

확인 항목: 플랫폼에 러너가 온라인으로 표시되고 테스트 작업의 uname -m 출력이 arm64인지 확인하세요. 러너를 상시 실행하려면 설치 패키지의 서비스 안내에 따라 설정하고 동일한 빌드 사용자로 실행하세요.

권장 태그: macos-m4

GitLab Runner

프로젝트 또는 그룹에서 러너를 만들고 현재 버전에서 사용하는 인증 토큰을 확인하세요. ARM64 버전을 설치해 등록한 다음 shell executor를 선택하면 해당 빌드 사용자의 macOS 환경에서 작업이 실행됩니다.

gitlab-runner register
gitlab-runner verify
gitlab-runner run

플랫폼에서 러너에 macos-m4 태그를 설정하고 작업의 tags 에 같은 값을 입력하세요. 대화형으로 등록할 때는 플랫폼이 제공한 주소와 토큰을 입력하세요. 토큰을 저장소에 기록하지 마세요.

확인 항목: 러너가 올바른 프로젝트에 연결되어 있고 작업이 실행 상태로 전환되는지 확인하세요. 계속 대기 중이면 머신 부하를 확인하기 전에 태그, 보호 브랜치 설정, 러너의 프로젝트 권한을 점검하세요.

실행 방식: shell

Jenkins 에이전트

전용 노드를 만들고 원격 작업 디렉터리와 macos-m4 태그를 설정하세요. 컨트롤러 안내에 따라 호환되는 Java를 설치하고 컨트롤러가 제공한 에이전트 파일을 다운로드한 뒤 생성된 실행 인수를 사용하세요.

java -jar agent.jar \
  -url "$JENKINS_URL" \
  -secret "$AGENT_SECRET" \
  -name "$AGENT_NAME" \
  -webSocket \
  -workDir "$AGENT_WORKDIR"

파이프라인에서 agent { label 'macos-m4' }를 지정하세요. 작업 디렉터리는 빌드 사용자가 쓸 수 있어야 합니다. Java 버전은 컨트롤러 요구 사항과 일치해야 하며, 로컬 터미널에서 Java가 실행되는지만 확인해서는 안 됩니다.

확인 항목: 컨트롤러에 노드가 온라인으로 표시되고 작업 공간이 예상한 디렉터리에 있는지 확인하세요. 먼저 executor 하나로 기준 상태를 만들고 메모리, 디스크, 테스트 부하를 고려해 동시 작업 수를 정하세요.

단일 작업으로 먼저 검증

머신 전체를 전용으로 사용하면 다른 고객과 CPU를 나눠 쓰지 않지만, 팀 내부 대기열까지 자동으로 관리되지는 않습니다. 같은 러너에서 여러 작업을 실행한다면 동시 실행, 작업 공간, 서명 자료 격리는 직접 관리해야 합니다.

재현 가능한 환경 고정

로컬과 CI에서 같은 Xcode 사용하기

‘터미널에서는 빌드되는데 러너에서는 실패’하는 문제는 툴체인 경로나 실행 사용자가 다를 때 자주 발생합니다. 먼저 현재 버전을 기록하고 툴체인을 선택한 다음 필요한 시뮬레이터 런타임을 설치하세요. Xcode 재설치는 첫 번째 해결책이 아닙니다.

전환 전에 버전 기록

여러 Xcode 버전을 각각 다른 앱 경로에 설치할 수 있습니다. 먼저 아래 명령으로 시스템, 현재 개발 디렉터리, 빌드 도구 버전을 기록한 다음 프로젝트 요구 사항과 비교하세요.

sw_vers
xcode-select -p
xcodebuild -version
xcrun --find swift

머신 전체의 기본값을 변경하려면 xcode-select를 사용하세요. 전환하기 전에 다른 빌드가 실행 중인지 확인하고 CI 실행 사용자로 결과를 다시 점검하세요.

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

작업별 툴체인 선택, 프로젝트별 다운로드

팀에서 여러 Xcode 버전을 사용한다면 각 작업에 DEVELOPER_DIR를 설정해 전역 전환의 영향을 줄이세요. 예시 경로는 노드에 실제로 설치된 버전의 디렉터리로 바꾸세요.

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcodebuild -version
xcrun simctl list runtimes
xcrun simctl list devices available
df -h

Xcode 설정에서 프로젝트 요구 사항에 맞는 시뮬레이터 런타임을 다운로드하세요. 런타임, 시뮬레이터 데이터, DerivedData는 모두 디스크 공간을 사용합니다. 설치 전 여유 공간을 확인하고 팀에서 실제 사용하는 버전만 유지하세요.

명령어가 실행된다고 해서 프로젝트 종속 항목이 모두 준비된 것은 아닙니다. 동일한 사용자로 Ruby, CocoaPods, 패키지 관리자, 프로젝트 잠금 파일을 확인하세요. 최초 설치 안내는 먼저 대화형 환경에서 확인해야 합니다.

첫 빌드를 제출하기 전에 러너 실행 환경에서 다음 세 가지를 확인하세요
확인 항목	확인 명령 또는 위치	통과 기준
툴체인 경로	`xcode-select -p` 및 작업 환경 변수	프로젝트에서 지정한 Xcode를 가리키며 버전 출력이 예상과 일치함
실행 사용자	`whoami` 및 `printf '%s\n' "$HOME"`	빌드 사용자, 홈 디렉터리, 키체인의 소유 사용자가 일치함
작업 공간 및 디스크	`pwd` 및 `df -h`	작업 공간에 쓸 수 있고 종속 항목, 임시 파일, 아카이브를 저장할 공간이 충분함

팀에서 용어 통일하기

용어 여덟 가지, 구분해야 할 경계 여덟 가지

머신, 연결 방식, 작업 예약을 구분해 이해하면 문제가 어느 단계에서 발생했는지 정확히 설명할 수 있습니다.

물리 노드: macOS와 빌드 작업을 실제로 실행하는 Mac mini입니다. 인스턴스 상세 정보의 연결 정보는 임대한 노드에 해당합니다.
전용: 머신 전체가 한 고객에게만 할당되어 다른 고객과 CPU를 나눠 쓰지 않습니다. 팀 내부 작업의 동시 실행은 팀이 관리해야 합니다.
비가상 머신: 공유 호스트에서 나눈 가상 인스턴스가 아닌, 전용 물리 Mac 환경을 제공합니다.
VNC: macOS 그래픽 화면을 원격으로 보고 조작하는 연결 방식으로 Xcode, 시뮬레이터, 대화형 설정에 적합합니다.
SSH: 빌드 명령 실행, 프로세스 관리, 관련 도구를 통한 파일 전송에 사용하는 암호화된 명령줄 연결 방식입니다.
self-hosted runner: 팀이 자체 노드에 등록하고 관리하는 CI 실행 프로그램입니다. CI 플랫폼에서 작업을 가져와 실행합니다.
Apple Silicon: Mac에서 사용하는 Apple 칩 아키텍처입니다. 이 서비스의 두 모델 모두 M4를 사용합니다. 종속 항목과 러너 설치 패키지를 선택할 때 arm64 지원 여부를 확인하세요.
Thunderbolt 5 연결: 목록에서 머신별로 요금이 부과되는 연결 옵션입니다. 여러 머신의 CPU나 메모리를 한 대처럼 합치지는 않으며, 작업 부하는 직접 구성해야 합니다.

로그를 보존한 뒤 환경 변경

오류가 발생한 단계부터 빌드 복구

실패한 명령, 종료 코드, 처음 발생한 유효한 오류를 저장한 뒤 변수 하나만 바꿔 다시 실행하세요. Xcode 전환, 캐시 삭제, 러너 재등록을 동시에 하지 마세요. 어떤 조치가 문제를 해결했는지 파악할 수 없습니다.

서명 실패: 먼저 실행 사용자와 키체인 확인

먼저 ‘컴파일 실패’와 ‘서명 실패’를 구분하세요. 아카이브 또는 서명 단계에서 오류가 발생한 경우에만 서명 인증서, 해당 개인 키, 프로비저닝 프로파일과 유효 기간을 확인하세요. 해당 자료는 프로젝트 요구 사항에 따라 팀에서 설정해야 합니다.

whoami
security list-keychains -d user
security find-identity -v -p codesigning

GUI에서는 서명되지만 CI에서 실패한다면 러너가 같은 사용자로 실행되는지, 대상 키체인이 검색 목록에 있는지, 비대화형 프로세스에 필요한 접근 권한이 있는지 확인하세요. 키체인 잠금 해제가 필요하면 CI의 보호된 비밀 변수로 인증 정보를 주입하세요. 스크립트, 명령 기록, 로그에 비밀번호를 남기지 마세요.

인증서를 가져온 후에는 프로비저닝 프로파일의 팀, 앱 식별자, 빌드 설정이 일치하는지도 확인하세요. 지원 티켓에는 민감 정보를 가린 오류만 첨부하세요. 개인 키, 인증서 비밀번호, 서명 자료 전체는 업로드하지 마세요.

캐시 문제: 프로젝트 하나만 대상으로 정리

먼저 같은 커밋을 다시 실행하고 Xcode 버전을 기록하세요. 종속 항목 하나만 해결되지 않는다면 잠금 파일, 종속 항목 버전, 다운로드 오류를 확인하세요. 네트워크 문제는 캐시 전체를 반복해서 비운다고 해결되지 않습니다.

프로젝트별 DerivedData 경로를 설정하면 해당 프로젝트의 빌드 산출물만 다시 만들기 쉽습니다. 아래 명령은 독립 작업 공간이 이미 있는 경우에 사용하세요. 실행 전에 변수를 실제 경로와 공유 scheme으로 바꾸세요.

xcodebuild \
  -workspace "$WORKSPACE" \
  -scheme "$SCHEME" \
  -derivedDataPath "$PROJECT_DERIVED_DATA" \
  clean build

clean 을 실행하면 다음 빌드에 필요한 작업량이 늘어납니다. 여러 작업에서 쓰기 가능한 캐시 디렉터리를 공유하지 마세요. 정리하거나 옮기기 전에 해당 디렉터리를 사용하는 작업을 중지하세요.

디스크 공간 부족: 캐시, 런타임, 빌드 산출물을 구분

먼저 남은 공간을 확인한 다음 DerivedData, 아카이브, 시뮬레이터 데이터가 실제로 얼마나 차지하는지 점검하세요. 사용자 디렉터리 전체를 재귀적으로 삭제하지 말고, 아카이브를 업로드하는 동안 산출물을 지우지 마세요.

df -h
du -sh "$HOME/Library/Developer/Xcode/DerivedData"
du -sh "$HOME/Library/Developer/Xcode/Archives"
du -sh "$HOME/Library/Developer/CoreSimulator"

관련 작업을 중지한 뒤 더 이상 사용하지 않는 프로젝트 캐시를 정리하세요. Xcode에서 필요 없는 런타임을 제거하고, 백업된 이전 아카이브는 팀의 보관 정책에 따라 처리하세요. 프로젝트, 서명 자료, 릴리스 산출물은 별도로 백업해야 합니다.

장기적으로 더 많은 공간이 필요하다면 주문 설정에서 +1TB SSD 또는 +2TB SSD 옵션을 고려하세요. 저장 공간을 늘려도 메모리가 늘어나는 것은 아닙니다. 먼저 병목이 작업 동시 실행이 아닌 디스크에 있는지 확인하세요.

러너 오프라인: 연결, 프로세스, 권한 순으로 점검

먼저 SSH로 노드에 접속할 수 있는지 확인한 다음 러너 프로세스와 로그를 점검하세요. 노드는 온라인인데 CI 플랫폼에서 오프라인으로 표시된다면 프로세스가 종료되었는지, CI 컨트롤러에 네트워크로 연결할 수 있는지, 토큰이나 노드 권한이 변경되었는지 확인하세요.

러너를 포그라운드에서 한 번 실행해 연결을 확인하고 첫 번째 연결 오류를 보관하세요. 포그라운드에서는 작동하지만 터미널을 닫으면 연결이 끊긴다면 해당 러너 안내에 따라 상시 실행 서비스를 설정해야 합니다. 서비스 실행 사용자는 툴체인, 작업 디렉터리, 키체인 설정에 사용하는 사용자와 일치해야 합니다.

재시작하기 전에 실행 중인 아카이브 또는 업로드 작업이 없는지 확인해 산출물이 중간에 잘리지 않도록 하세요. 플랫폼에는 온라인으로 표시되지만 작업이 대기 중이라면 러너를 반복해서 삭제하고 재등록하지 말고 태그, 브랜치 권한, 동시 실행 제한을 확인하세요.

여러 인스턴스 풀을 운영한다면 노드에 macos-m4-build 및 macos-m4-release처럼 구분하기 쉬운 태그를 추가하세요. 그러면 릴리스 작업은 해당 서명 환경이 설정된 노드로만 전달됩니다.

결제 내역을 확인한 뒤 다시 시도

결제 내역과 주문을 하나씩 대조

일·주·월·분기 단위로 요금이 부과되며 모든 결제는 미국 달러(USD)로 처리됩니다. USDT-TRC20과 Stripe를 통한 Visa / Mastercard / Amex만 지원합니다. 실제 이용 가능한 결제 게이트웨이는 백엔드 응답을 확인하세요.

USDT-TRC20을 보냈지만 주문이 아직 확인 대기 중

주문 결제 페이지에 표시된 네트워크, 수취 주소, 금액을 하나씩 확인하세요. 송금 내역이 있다고 주문 확인이 완료된 것은 아닙니다. 블록체인 거래 상태와 콘솔의 청구 상태를 모두 확인해야 합니다.

확인을 재촉하려고 송금하지 마세요. 다른 주문의 결제 정보를 현재 주문에 사용하지 마세요. 주문 번호, 거래 해시, 금액, 송금 시간을 보관해 콘솔 지원 티켓으로 제출하세요. 지갑 키나 복구 문구는 보내지 마세요.

결제 페이지가 닫혔다면 같은 주문으로 돌아가 현재 상태를 확인한 뒤 결제를 계속할지 결정하세요. 같은 서비스에 중복 결제하지 않도록 주의하세요.

카드 결제가 완료되지 않았다면 인증 및 카드 발급사 결과 확인

카드 정보와 청구 정보가 올바른지, 한도가 충분한지, 카드 발급사 인증이 완료되었는지 확인하세요. 리디렉션 페이지가 차단되었다면 현재 결제 절차에 필요한 페이지를 열 수 있도록 허용한 뒤 주문을 확인하세요.

거절 메시지가 표시되면 오류 요약을 저장하고 카드 발급사에 거래 제한 여부를 문의하세요. 짧은 시간에 결제를 연속으로 제출하지 마세요. 은행에는 청구가 표시되지만 주문이 확인되지 않았다면 즉시 다시 결제하지 말고 지원 티켓으로 확인하세요.

지원 티켓에는 주문 번호, 발생 시간, 민감 정보를 가린 오류 화면만 첨부하면 됩니다. 전체 카드 번호, 보안 코드, 은행 인증 코드는 필요하지 않습니다.

갱신 전 인스턴스, 기간, 만료일 확인

콘솔에서 기존 인스턴스에 해당하는 구독 또는 청구 내역을 열고 인스턴스 ID, 만료일, 청구 기간을 확인한 후 결제하세요. 새 주문과 기존 인스턴스 갱신은 별개이므로 모델 이름만 보고 판단하지 마세요.

갱신 완료 여부는 청구 내역과 인스턴스 상태로 확인하세요. 자동으로 갱신된다고 가정하지 마세요. 만료 전에 프로젝트, 캐시 정책, 릴리스 산출물을 백업하세요. 인스턴스 해제 후 디스크가 삭제되므로 복구 가능한 백업으로 간주해서는 안 됩니다.

노드는 연중무휴 365일 정상 운영됩니다. 서비스 가용성 문제가 의심되면 인스턴스 ID, 영향을 받은 시간대, 연결 오류를 제출해 확인을 요청하세요. 사용자가 프로세스를 중지한 경우와 노드 사용 불가 문제를 혼동하지 마세요.

재현 가능한 정보 첨부

문제 상황을 지원팀에 전달

기존 인스턴스 문제는 콘솔에서 지원 티켓을 제출하세요. 인스턴스 ID, 발생 시간과 시간대, 실패 단계, 예상 결과, 민감 정보를 가린 로그를 첨부하세요. 여러 대를 시작하거나 러너 풀을 구성하려면 문의 페이지에서 요구 사항을 정리하거나 support@vpsmerge.com으로 이메일을 보내세요.

비밀번호, 등록 토큰, 개인 키, 전체 결제 정보는 보내지 마세요. 반복되는 전체 로그보다 처음 발생한 유효한 오류가 문제 해결에 더 도움이 됩니다.

콘솔에서 지원 티켓 제출 팀 문의 내용 정리