SSH로 명령을 실행하고 VNC로 macOS 그래픽 인터페이스를 조작하세요. 가상 머신이 아닌 전용 물리 머신입니다. 소스 코드, 툴체인, CI를 차례로 이전해 로컬 환경의 문제까지 함께 옮기지 마세요.
인스턴스 정보와 SSH 공개 키가 준비되어 있다면 아래 순서대로 연결하세요. 툴체인 최초 설정에 필요한 시간은 연결 단계에 포함되지 않습니다.
로컬 터미널, SSH 공개 키, 콘솔의 호스트 정보를 준비하세요. 예시의 HOST와 PORT및 USER 는 각각 제공된 호스트 주소, SSH 포트, 사용자 이름으로 바꾸세요. 예시를 그대로 복사해 사용하지 마세요.
전용 키가 이미 있다면 그대로 사용하세요. 없다면 컴퓨터에서 Ed25519 키 쌍을 생성하고 암호를 설정한 다음, .pub 파일의 내용을 콘솔에서 해당 인스턴스의 SSH 공개 키 설정에 추가하세요.
ssh-keygen -t ed25519 \
-f ~/.ssh/osxbuild_ed25519
cat ~/.ssh/osxbuild_ed25519.pub개인 키는 로컬에 보관하세요. 티켓, 이메일, 코드 저장소에 붙여 넣지 마세요. 업로드 후 콘솔 안내에 따라 공개 키가 대상 인스턴스에 적용되었는지 확인하세요.
콘솔의 인스턴스 상세 정보에서 연결 정보를 확인하세요. 처음 호스트 지문을 확인하라는 메시지가 나타나면 검증 가능한 제공 정보와 대조하세요. 확인할 수 없다면 티켓을 제출하고, 안내를 건너뛰기 위해 호스트 검증을 끄지 마세요.
ssh -i ~/.ssh/osxbuild_ed25519 \
-p PORT USER@HOST
sw_vers
uname -m
xcodebuild -version먼저 OS, 아키텍처, Xcode 버전을 확인하세요. 마지막 명령에서 툴체인이 준비되지 않았다는 메시지가 나오면 설치와 경로 설정을 완료한 후 빌드 작업을 연결하세요.
아래 내용을 로컬의 ~/.ssh/config에 작성하세요. 예시 별칭은 bake입니다. 이후 동기화, 터널링, 문제 해결 명령에서 이 별칭을 재사용하면 주소와 포트를 매번 입력하지 않아도 됩니다.
Host bake
HostName HOST
Port SSH_PORT
User SSH_USER
IdentityFile ~/.ssh/osxbuild_ed25519
IdentitiesOnly yes
ServerAliveInterval 30
ServerAliveCountMax 3저장한 뒤 ssh bake를 실행하세요. 연결 유지 설정은 연결이 끊겼는지 감지하는 기능이며, 네트워크 재연결을 대신하거나 터미널 작업을 자동으로 복구하지는 않습니다.
Xcode를 설정하거나 키체인을 확인하고 시뮬레이터를 살펴볼 때 데스크톱을 여세요. 먼저 콘솔에서 제공된 VNC 서비스 정보를 확인하세요. 기본 포트를 모든 머신의 연결 정보로 간주하지 마세요.
macOS에서는 내장된 ‘화면 공유’를 사용할 수 있습니다. Windows와 Linux에서는 TigerVNC 등 VNC를 지원하는 클라이언트를 사용하세요. 별도 설치가 필요하면 공식 배포처에서 다운로드하고, 제공된 서비스의 인증 방식과 호환되는지 확인하세요.
먼저 1440 × 900 또는 1600 × 1000 화면 크기로 시작하세요. 고해상도 화면을 꽉 채울 필요는 없습니다. 선택할 수 있다면 먼저 24비트 색상을 사용하고, 네트워크가 제한적이면 16비트를 시도하세요. 선택 가능한 옵션은 클라이언트와 서버가 실제로 지원하는 범위에 따릅니다.
터미널 빌드와 원격 데스크톱은 서로 다른 작업 방식입니다. 데스크톱 화면이 매끄럽지 않다면 SSH로 빌드를 계속 실행하고 로그와 IPA를 가져오세요. 전체 파이프라인이 화면 갱신에 의존하게 할 필요는 없습니다.
로컬에서 아래 명령을 실행하고 터미널을 열어 두세요. VNC_PORT 는 제공된 서버 포트로 바꾸세요. 예시의 15900 은 로컬 포트이므로 사용 중이 아닌 포트로 변경할 수 있습니다.
ssh -N \
-L 127.0.0.1:15900:127.0.0.1:VNC_PORT \
-o ExitOnForwardFailure=yes \
bake그런 다음 VNC 클라이언트의 주소 입력란에 127.0.0.1을, 포트 입력란에 15900을 입력하세요. 주소 입력란이 하나뿐인 클라이언트는 해당 문서에서 안내하는 형식으로 입력하세요.
VNC는 제공된 데스크톱 자격 증명으로 인증합니다. SSH 키는 데스크톱 암호를 대신하지 않습니다. 사용을 마치면 클라이언트를 종료한 뒤 Ctrl + C 를 눌러 터널을 닫으세요.
| 증상 | 먼저 확인할 항목 | 다음 단계 |
|---|---|---|
| 로컬 포트를 열 수 없음 | SSH 연결 여부와 로컬 포트 사용 여부 | 다른 로컬 포트를 사용하고 터널 터미널에 표시된 오류를 보관하세요 |
| 터널은 연결됐지만 데스크톱 연결이 거부됨 | 제공된 VNC 포트와 서비스의 수신 상태 | 인스턴스 상세 정보를 확인하고 데스크톱 포트를 인터넷에 추가로 공개하지 마세요 |
| 인증 후 연결 실패 | 데스크톱 사용자 이름과 암호, 클라이언트의 인증 호환성 | 제공된 자격 증명을 다시 확인하세요. SSH 개인 키를 VNC 암호로 사용하지 마세요 |
| 로그인은 되지만 화면 갱신이 느림 | 해상도, 색상 심도, 로컬 네트워크, 노드와의 거리 | 화면 전송량을 줄이고 그래픽 인터페이스가 필요 없는 빌드는 SSH로 계속 실행하세요 |
먼저 데이터를 옮기고 툴체인을 맞춘 뒤 CI를 연결하세요. 각 단계에서 결과를 확인하고, 캐시와 자동화를 복원하기 전에 깨끗한 아카이브 빌드를 한 번 성공시키세요.
Git으로 프로젝트를 가져오거나 rsync로 로컬 작업 디렉터리와 저장소 외부 리소스를 동기화하세요. 첫 동기화에는 DerivedData와 이전 build 디렉터리를 포함하지 말고, 서명 개인 키를 일반 파일과 함께 전송하지 마세요.
rsync -az --progress \
--exclude='DerivedData/' \
--exclude='build/' \
--exclude='*.p12' \
--exclude='*.mobileprovision' \
./ bake:~/project/확인: 대상 디렉터리, 커밋 버전, 필수 리소스가 일치하는지 확인하세요. 예시에는 삭제 옵션이 없어 첫 동기화 중 원격 파일을 실수로 지우지 않습니다. 동기화 성공을 백업 완료로 간주하지 마세요.
프로젝트에 필요한 Xcode를 설치하거나 선택하고 Homebrew를 설정하세요. CocoaPods는 잠금 파일을 기준으로 복원하고, SPM은 먼저 다시 해석하세요. 캐시는 툴체인 및 의존성 버전이 일치해야 하며 출처를 알 수 없는 디렉터리를 그대로 재사용하지 마세요.
xcode-select -p
xcodebuild -version
brew --version
bundle install
bundle exec pod install확인: 버전이 로컬 기준과 일치하고 의존성을 해석할 수 있어야 합니다. 마지막 두 명령은 CocoaPods 프로젝트에서만 실행하세요. 서명 인증서는 관리되는 경로를 통해 별도로 키체인에 가져오고 유효 기간과 프로비저닝 프로파일의 일치 여부를 확인하세요.
GitHub Actions 또는 GitLab Runner에 전용 실행기를 등록하고, 먼저 버전을 확인한 다음 프로젝트의 Fastlane lane을 실행하세요. 아카이브와 내보내기를 검증한 후 업로드 단계를 추가하세요.
xcodebuild -list \
-workspace App.xcworkspace
bundle exec fastlane ios build확인: 로그에서 커밋 버전, Scheme, 산출물 경로를 추적할 수 있어야 합니다. 예시의 워크스페이스와 lane 이름은 프로젝트에서 실제 사용하는 이름으로 바꾸세요. 릴리스 자격 증명은 별도로 권한을 부여하고 소스 코드와 함께 배포하지 마세요.
자체 호스팅 실행기는 대여한 물리 노드에서 실행됩니다. 라벨은 작업을 라우팅하고 자격 증명은 권한을 부여하므로 서로 혼동하지 마세요. 먼저 작업 하나를 성공시킨 뒤 병렬 작업 수와 디스크 사용량을 검토하세요.
저장소 또는 조직 설정의 안내에 따라 self-hosted runner를 등록하고 사용자 지정 라벨 osxbuild을 추가하세요. 아래 워크플로는 툴체인을 확인하고 아카이브를 생성하지만, 서명 자료 주입, IPA 내보내기, 배포는 포함하지 않습니다.
name: iOS archive
on:
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ios-${{ github.ref }}
cancel-in-progress: false
jobs:
archive:
runs-on: [self-hosted, macOS, ARM64, osxbuild]
steps:
- uses: actions/checkout@v4
- name: Check Xcode
run: xcodebuild -version
- name: Archive
run: |
xcodebuild \
-workspace App.xcworkspace \
-scheme App \
-configuration Release \
-archivePath "$RUNNER_TEMP/App.xcarchive" \
archive워크스페이스와 Scheme을 바꾸고 Scheme이 공유 상태인지 확인하세요. 서명 자료를 보유한 러너는 신뢰할 수 있는 저장소와 작업에서만 사용하세요. 브랜치마다 다른 동시 실행 그룹이 생성되지만, 빌드 디렉터리 공유로 인한 충돌은 별도로 방지해야 합니다.
Jenkins에 고정 노드를 추가하고 전용 빌드 디렉터리를 원격 작업 디렉터리로 지정한 뒤 라벨을 osxbuild-mac으로 설정하세요. SSH를 통해 에이전트를 시작하는 옵션을 선택하고 제공된 호스트와 포트를 입력하세요. 개인 키는 Jenkins 자격 증명 저장소에서 관리하세요.
pipeline {
agent { label 'osxbuild-mac' }
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Toolchain') {
steps {
sh 'xcodebuild -version'
}
}
stage('Build') {
steps {
sh 'bundle exec fastlane ios build'
}
}
}
}먼저 에이전트에 필요한 Java를 사용할 수 있는지, SSH 자격 증명이 유효한지, 호스트 지문을 확인했는지 점검하세요. SSH로 시작한 비대화형 환경에서는 로컬 셸 설정이 로드되지 않을 수 있으므로 Homebrew, Ruby, Fastlane 경로를 명시적으로 설정해야 합니다.
GitLab Runner도 같은 순서로 연결하세요. 실행기를 등록하고 신뢰할 수 있는 프로젝트로 제한한 뒤 프로젝트 라벨을 설정하고, 버전 확인 작업으로 환경을 검증하세요. 그래픽 세션이 필요한 테스트는 실행 조건을 별도로 확인하세요.
실행 슬롯 하나로 시작하세요. 병렬 실행을 늘리기 전에 메모리 사용량, 시뮬레이터 수, DerivedData 경로를 확인하고 여러 작업이 같은 아카이브 디렉터리에 쓰지 않도록 하세요.
그래픽 데스크톱을 자주 사용한다면 팀에서 노드까지의 연결 경로를 우선 비교하세요. 주로 CI를 실행한다면 소스 코드, 의존성, 산출물 업로드 경로를 살펴보세요. 지리적 거리는 출발점일 뿐이며 실제 사용 경험은 통신사, 라우팅, 로컬 네트워크에도 좌우됩니다.
SG · UTC+8
동남아시아 팀과 협업하기 좋은 시간대입니다. 업무 시간에 Xcode를 원격으로 자주 조작한다면 팀의 로컬 네트워크에서 이 노드까지 연결 상태를 먼저 비교해 보세요.
JP · UTC+9
동아시아 팀과 협업하기 좋은 시간대입니다. 주간에는 대화형 개발을, 야간에는 아카이브를 같은 머신에서 처리해 환경 전환을 줄일 수 있습니다.
KR · UTC+9
동북아시아 팀과 협업하기 좋은 시간대입니다. 원격 데스크톱을 자주 사용한다면 화면 갱신과 입력 반응을 직접 비교한 뒤 팀의 접속 경로를 정하세요.
HK · UTC+8
중국 남부와 동남아시아 팀과 협업하기 좋은 시간대입니다. 원격 조작뿐 아니라 의존성 다운로드와 산출물 업로드도 확인해 한 번의 연결 성공만으로 판단하지 마세요.
US-E · UTC−5 / −4
북미 동부 및 서유럽 팀과 협업하기 좋은 시간대입니다. 야간 빌드 예약에는 시간대를 명시하고 서머타임에 따른 현지 시각 변화를 고려하세요.
US-W · UTC−8 / −7
북미 서부 팀과 협업하기 좋은 시간대입니다. 빌드 시간을 현지 업무 시간에 맞추기 좋습니다. 시간대가 다른 팀에 작업을 넘길 때는 로그에 명확한 시각 정보를 남기세요.
두 가지 머신 구성 모두 위 6개 노드를 제공합니다. 실제 이용 가능 여부는 콘솔에 표시되는 최신 정보를 확인하세요. 노드는 연중 365일 가동됩니다. 로컬 네트워크 중단이나 SSH 세션 끊김은 머신의 가동 상태와 별도로 판단해야 합니다.
먼저 검증을 마친 연결 경로 하나를 유지한 채 접근 정책을 조정하세요. 한 번에 한 가지씩 변경하고 새 연결이 성공한 뒤 기존 세션을 닫아 머신에 접속할 수 없게 되는 상황을 피하세요.
먼저 두 번째 터미널에서 전용 키로 로그인할 수 있는지 확인한 뒤 시스템의 SSH 설정에 따라 암호 인증을 비활성화하세요. 설정을 변경하기 전에 구문을 점검하고 다시 연결할 방법이 있는지 확인하세요. 시스템 설정이 익숙하지 않다면 먼저 티켓을 제출해 진행 방법을 확인하세요.
용도에 따라 원격 로그인과 서비스 진입점을 제한하고 VNC는 SSH 터널을 우선 사용하세요. 디버깅 서비스, 빌드 제어 인터페이스, 임시 파일 서버를 인터넷에 직접 노출하지 마세요. 로컬 주소 바인딩과 접근 제어를 함께 점검하세요.
수동 로그인과 CI에는 서로 다른 키를 사용하세요. 담당자가 바뀌거나 자격 증명 유출이 의심되면 이전 권한을 즉시 취소하세요. 키를 교체할 때는 새 공개 키를 먼저 추가해 검증하고, 이전 키를 제거한 뒤 실행기와 팀 인수인계 기록을 업데이트하세요.
빌드에 필요한 동안에만 키체인을 잠금 해제하고 작업 후 접근 권한을 제한하세요. API 키, 인증서 암호, match 복호화 자격 증명은 자격 증명 시스템을 통해 주입하세요. 스크립트가 민감한 변수를 출력하는지 확인하고 개인 키 파일을 저장소에 보관하지 마세요.
보관할 소스 코드, IPA, 아카이브, 파이프라인 설정을 팀 소유 저장소에 동기화하고 파일을 읽을 수 있는지 확인하세요. 대여 기간 종료 후에는 디스크 삭제와 시스템 재설치가 진행되므로 머신의 로컬 디렉터리를 유일한 복사본으로 두지 마세요.
문제 해결에 필요한 것은 정확한 인계 정보입니다.티켓에 주문 번호, 노드, 오류 발생 시각과 시간대, 민감 정보를 삭제한 로그 마지막 50줄을 첨부하세요. 개인 키, 인증서 암호, 계정 암호는 보내지 마세요. 연결 문제는 콘솔 티켓이나 support@osxbuild.com 으로 문의하세요.
이미 머신이 있다면 콘솔의 제공 정보를 먼저 확인하세요. 아직 구성을 선택하지 않았다면 두 가지 전용 클라우드 Mac 구성 중에서 시작해 빌드 규모에 맞는 머신을 고르고 팀 위치에 따라 노드를 선택하세요.