공식 문서에는 Machine Runner 3의 맥 설치 절차와 리소스 클래스 기반 작업 라우팅이 별도로 정의되어 있습니다. CircleCI 러너 개요를 기준으로 보면, 노드가 온라인으로 보이는 것만으로는 운영 투입을 결정할 수 없습니다. 고정된 Xcode 환경, 사설 저장소, 내부망 의존성 또는 서명 자산이 필요할 때만 CircleCI Machine Runner 3 원격 맥 배포를 진행하고, 표준 작업은 관리형 실행기를 유지하는 것이 좋습니다.
이번 주 권장 일정
- 1일차: 작업 분류, 전용 계정과 접근 범위 설계
- 2일차: namespace, resource class, 인증 정보 구성
- 3일차: Machine Runner 3 설치와 최소 작업 실행
- 4일차: Xcode 빌드 및 서명 작업 분리
- 5일차: 재시작, 작업 공간 정리, 연속 실행 검증
이 글은 CircleCI iOS 또는 macOS 파이프라인을 유지하는 개발자, 서명과 사설 저장소를 연결해야 하는 데브옵스 엔지니어, 원격 맥 노드의 권한과 장애 복구를 맡은 플랫폼 담당자를 위한 안내서입니다. 단순한 관리형 실행기 사용법만 찾는다면 여기서 멈춰도 됩니다.
마지막 업데이트: 2026년 8월 29일. 설치 방식과 지원 범위는 CircleCI의 macOS 설치 안내와 관련 공식 문서를 다시 확인하는 전제로 작성했습니다.
01배포 전 작업을 원격 맥으로 옮길지 먼저 판별합니다
Machine Runner 3는 작업을 대신 관리해 주는 가상 환경이 아닙니다. 지정한 맥 노드에 이미 설치된 도구, 계정 권한, 네트워크 경로를 사용해 작업을 실행합니다. 자체 호스팅 러너의 실행 모델도 이 경계를 전제로 설명합니다.
다음 조건이면 원격 맥 노드가 적합합니다.
- 특정 Xcode 버전을 계속 유지해야 합니다.
- 사설 패키지 저장소나 내부 테스트 서버에 접근해야 합니다.
- 개발자 인증서, 프로비저닝 프로파일, 키체인을 별도 통제해야 합니다.
- macOS 전용 도구를 포함한 Xcode CI가 필요합니다.
- 빌드 작업을 정해진 맥 하드웨어에서 반복해야 합니다.
반대로 운영체제와 도구 구성이 고정될 필요가 없고 공개 의존성만 사용하는 일반 테스트라면 관리형 실행기가 더 단순합니다. 원격 맥을 추가하면 패치, 디스크 정리, 계정 잠금, 로그 보존, 장애 복구를 직접 책임져야 하기 때문입니다.
선택 조건을 작업 단위로 적용합니다
- 고정 Xcode 또는 macOS 전용 도구가 필요하면 원격 맥 자체 호스팅 노드를 선택합니다.
- 서명 작업만 민감하면 일반 빌드와 배포 작업을 나누고, 서명 전용 리소스 클래스를 별도로 둡니다.
- 내부망 접근만 필요하면 네트워크 경로와 방화벽을 먼저 검증한 뒤 노드를 추가합니다.
- 환경 통제가 필요하지 않으면 관리형 실행기로 되돌립니다.
- 둘 다 필요하면 일반 테스트는 관리형 실행기, Xcode 빌드와 배포는 원격 맥으로 분리합니다.
1단계: 실행 계정과 인증 경계를 분리합니다
원격 맥에는 개인 관리자 계정으로 러너를 실행하지 않는 편이 안전합니다. <RUNNER_USER>라는 별도 계정을 만들고 소스, 캐시, 로그, 서명 파일의 접근 범위를 나눕니다. 실제 계정 이름과 경로는 조직의 운영 규칙에 맞춰 정하고 저장소에는 기록하지 않습니다.
권한 설계에서 특히 확인할 항목은 다음과 같습니다.
- 소스 작업 공간은
<WORKSPACE_PATH>아래로 제한합니다. - 캐시는
<CACHE_PATH>에 두고 다른 프로젝트와 공유하지 않습니다. - 로그는
<LOG_PATH>로 분리하고 보존 기간을 정합니다. - 서명 자산은 일반 빌드 작업 계정에서 읽을 수 없게 합니다.
- 원격 접속용 관리자 계정과 러너 실행 계정을 분리합니다.
CircleCI에서 namespace와 resource class는 작업을 특정 노드 그룹으로 보내는 경계입니다. 리소스 클래스 공식 설명에 맞춰 <NAMESPACE>와 <RESOURCE_CLASS>를 정하고, 토큰은 <RUNNER_TOKEN> 같은 자리표시자로만 관리합니다.
resource_class: <NAMESPACE>/<RESOURCE_CLASS>
토큰은 저장소 파일, 설정 화면 캡처, 빌드 로그에 넣지 않습니다. 보안 보관소에 저장하고 담당자가 바뀌거나 노드가 폐기될 때 교체 또는 철회합니다. 토큰 철회 전에는 새 토큰을 배포할 복구 경로를 확보해야 합니다.
032단계: Machine Runner 3를 설치하고 노드 상태를 세 겹으로 확인합니다
Apple Silicon 맥인지 여부보다 중요한 것은 작성 시점의 CircleCI 설치 문서가 해당 macOS 환경을 지원하는지 확인하는 일입니다. Apple Silicon Mac에 설치할 때도 최신 공식 macOS 설치 절차의 설치 방식과 요구 조건을 그대로 따라야 합니다. 설치 패키지, 실행 파일 이름, 설정 위치를 기억에 의존해 바꾸지 않습니다.
설치 순서는 다음과 같습니다.
<RUNNER_USER>로 로그인하거나 해당 계정에서 실행할 준비를 합니다.- 공식 문서에서 안내하는 설치 파일과 검증 절차를 수행합니다.
- 노드 이름을
<NODE_NAME>으로 정하고 작업 디렉터리를<WORKSPACE_PATH>로 지정합니다. - namespace, resource class, 인증 필드를 공식 형식에 맞춰 입력합니다.
- macOS의 다운로드 파일 격리와 서명 또는 공증 관련 경고를 확인합니다.
- 공식 방식으로 러너를 시작하고 로그 출력이 멈추지 않는지 확인합니다.
- 프로세스, CircleCI 인벤토리, 로컬 로그를 서로 대조합니다.
이때 “온라인” 표시는 출발점일 뿐입니다. 프로세스가 종료되지 않았는지, 등록된 노드 이름이 예상값인지, 작업을 받을 수 있는 상태인지 각각 확인해야 합니다. 설치 후 격리 속성을 제거하거나 실행 파일을 재설치하는 파괴적 조치를 하기 전에는 현재 설정과 재설치 경로를 보관합니다.
043단계: 최소 작업으로 라우팅과 Xcode 도구 체인을 검증합니다
첫 작업은 실제 배포 프로젝트가 아니라 폐기 가능한 저장소로 구성합니다. resource class를 명시해 작업이 기대한 원격 맥으로 갔는지 확인합니다. 다른 실행 환경에서 우연히 성공한 결과를 배포 성공으로 오해하면 안 됩니다.
CircleCI 자체 호스팅 러너를 검증할 때는 다음 증거를 남깁니다.
- 작업의 resource class와 실제 노드 이름
- 실행 계정과 작업 디렉터리
- 프로세스 종료 상태
- Xcode 및 명령 줄 도구 선택 결과
- 프로젝트 의존성 설치 로그
- 생성된 결과물의 해시 또는 파일 목록
Xcode 호출은 작업 계정에서 비대화형으로 실행되어야 합니다. Apple의 명령 줄 도구 설치 안내를 확인하고, 명령 줄 도구 선택 방법에 따라 실제 선택 상태를 점검합니다.
개발자 계정으로 터미널에서 성공한 명령이 러너 계정에서도 성공하는지 확인합니다. 로그인 셸에만 등록된 경로, 사용자 키체인 잠금, 승인 대화 상자, 개인 캐시를 그대로 믿으면 안 됩니다. 이 단계에서 Xcode CI가 실패하면 서명 자산을 추가하지 말고 도구 체인과 의존성 경로부터 고칩니다.
054단계: 일반 빌드와 서명 배포를 다른 경계로 나눕니다
서명 인증서와 프로비저닝 프로파일을 모든 작업에 노출하면 테스트 작업 하나의 탈출 범위가 커집니다. 일반 테스트, 아카이브, 배포를 서로 다른 작업 또는 리소스 클래스로 구분합니다.
서명 격리의 장점과 비용
장점
- 일반 테스트 작업이 서명 자산을 읽지 못하게 할 수 있습니다.
- 배포 작업을 승인된 노드와 브랜치로 제한하기 쉽습니다.
- 인증서 교체 때 영향 범위를 좁힐 수 있습니다.
- 실패한 테스트 작업의 작업 공간을 더 안전하게 폐기할 수 있습니다.
비용
- 리소스 클래스와 작업 정의가 늘어납니다.
- 인증서 만료와 프로파일 교체 절차가 필요합니다.
- 서명 전용 노드의 대기 시간이 생길 수 있습니다.
- 키체인 잠금과 비대화형 실행 문제를 별도로 해결해야 합니다.
서명 방식은 팀이 이미 승인한 흐름과 CircleCI의 최신 보안 안내를 기준으로 정합니다. 실제 인증서 이름, 계정, 토큰, 키체인 암호를 설정 예시에 복사하지 않습니다. CircleCI 보안 자주 묻는 질문과 조직의 비밀값 관리 정책을 함께 검토합니다.
065단계: 재시작과 연속 작업을 통과해야 운영 노드가 됩니다
원격 맥 재시작 후 러너가 자동으로 다시 실행되는지 확인합니다. 자동 실행 방식은 설치 시점의 공식 macOS 문서와 현재 운영 설정을 기준으로 합니다. 단순히 화면 공유가 다시 연결되는 것은 러너 복구 증거가 아닙니다.
검증 절차는 다음과 같습니다.
- 실행 중인 테스트 작업이 없을 때 계획된 재시작을 수행합니다.
<RUNNER_USER>의 러너 프로세스가 다시 살아나는지 확인합니다.- CircleCI 인벤토리에서 노드가 작업 수신 상태인지 확인합니다.
- 새 최소 작업을 보내 실제로 다시 수신하는지 확인합니다.
- Xcode 명령과 의존성 접근이 재시작 전과 같은지 비교합니다.
- 실패 작업 뒤 소스, 비밀 파일, 임시 결과물이 남는지 검사합니다.
- 연속 작업에서 캐시 오염, 동시 대기, 로그 누락이 없는지 확인합니다.
작업 공간 정리는 성공한 작업보다 실패한 작업에서 더 잘 드러납니다. 중단된 빌드가 다음 작업의 소스 변경이나 서명 파일에 영향을 주지 않는지 확인해야 합니다. 연결 문제가 발생하면 자체 호스팅 러너 장애 해결 문서와 러너 연결 점검 안내를 순서대로 확인합니다.
운영 투입 판정표
| 확인 항목 | 통과 증거 | 중단 조건 |
|---|---|---|
| 작업 라우팅 | 지정한 resource class와 노드 이름이 일치합니다 | 다른 노드에서 실행됩니다 |
| Xcode 호출 | 러너 계정에서 비대화형 빌드가 끝납니다 | 사용자 로그인 세션에서만 성공합니다 |
| 재시작 복구 | 재시작 뒤 새 작업을 다시 받습니다 | 수동 실행 없이는 복구되지 않습니다 |
| 작업 공간 정리 | 실패 뒤 민감 파일과 임시 산출물이 제거됩니다 | 다음 작업에 이전 상태가 남습니다 |
| 로그와 복구 | 실패 원인과 복구 담당자가 확인됩니다 | 프로세스만 온라인으로 표시됩니다 |
관리형 실행기, 원격 맥, 이중 구성을 비용 항목으로 비교합니다
가격만 비교하면 자체 호스팅 노드의 실제 부담을 놓치기 쉽습니다. 원격 맥은 임대료 외에도 저장 공간, 로그 보존, 업데이트 시간, 장애 대응 비용을 포함해 판단해야 합니다. 반대로 관리형 실행기는 호스트 운영 부담이 적지만, 고정된 Xcode 환경이나 내부망 접근을 원하는 경우 제약이 생길 수 있습니다.
| 운영 방식 | 환경 통제 | 유지보수 부담 | 적합한 작업 |
|---|---|---|---|
| 관리형 실행기 | 제한적 | 낮음 | 표준 테스트와 일반 검증 |
| 원격 맥 자체 호스팅 | 높음 | 직접 부담 | 고정 Xcode, 사설 의존성, 내부망 |
| 이중 구성 | 작업별 분리 | 중간 | 일반 테스트와 서명 배포를 분리하는 팀 |
원격 맥을 장기간 고정 노드로 쓸 계획이라면 개인 전용 맥 미니 운영 방식처럼 접근 계정과 관리 범위를 먼저 설계합니다. 단순히 맥을 확보한 뒤 CI 설정을 붙이는 방식은 업데이트와 복구 단계에서 다시 막힙니다.
| 비용 항목 | 관리형 실행기 | 원격 맥 노드 | 확인할 내용 |
|---|---|---|---|
| 컴퓨팅 사용료 | 실행 정책에 따름 | 선택한 임대 기간과 구성에 따름 | 실제 작업 시간과 대기 시간 |
| 운영 인력 | 낮은 편 | 계정, 패치, 장애 대응 필요 | 담당자와 대응 시간 |
| 저장 공간 | 제공 범위 확인 | 노드 용량과 정리 정책 관리 | 캐시와 결과물 보존 |
| 네트워크 | 서비스 정책 확인 | 내부망과 원격 접속 경로 설계 | 사설 저장소 접근 |
| 서명 관리 | 조직 정책에 따름 | 키체인과 인증서 직접 격리 | 교체와 철회 절차 |
처음부터 배포 작업 전체를 옮기지 말고, 서명 없는 테스트 작업으로 시작합니다. 이후 재시작과 정리 검증을 통과했을 때만 아카이브와 배포 작업을 추가하는 순서가 안전합니다.
| 단계 | 실행 작업 | 남겨야 할 기록 |
|---|---|---|
| 준비 | 계정, namespace, resource class 구성 | 권한표와 설정 버전 |
| 설치 | 러너 시작과 인벤토리 등록 | 프로세스 및 로컬 로그 |
| 검증 | 폐기 가능한 프로젝트 빌드 | 종료 상태와 결과물 |
| 격리 | 일반 작업과 서명 작업 분리 | 접근 범위와 승인 조건 |
| 운영 | 재시작 및 연속 작업 | 복구 결과와 정리 결과 |
표준 작업에는 관리형 실행기가 더 적합한데도 원격 맥을 붙이면 노드 패치, 캐시 오염, 계정 권한, 재시작 복구를 계속 관리해야 합니다. 반대로 Linux 또는 가상 macOS 환경은 고정된 실제 Xcode 도구 체인, 서명 키체인, 물리 맥 접근이 필요한 작업에서 장기 대안이 되기 어렵습니다. 이런 조건이라면 VpsMesh의 원격 맥 구성 확인 후 프로젝트 기간에 맞춰 임시 노드를 운영하고, 무서명 빌드와 재시작 검증을 먼저 끝내는 방식이 현실적입니다. 일정 기간 지속되는 실제 Mac 빌드 노드가 필요하면 서울 리전 맥 미니 선택지도 함께 비교해 볼 수 있습니다.