판정: 기존 launch agent를 쓰는 macOS 노드는 CircleCI Machine Runner 3으로 옮기는 편이 맞습니다. 다만 운영 노드를 바로 덮어쓰지 말고, 격리된 Mac에서 서비스 시작, 작업 라우팅, 작업 공간 정리, 서명 자료 보호와 재시작 복구를 검증한 뒤 생산 노드를 순차 전환해야 합니다.
이 글은 CircleCI macOS 자체 운영 노드를 관리하는 플랫폼 엔지니어링 책임자를 위한 내용입니다. 코드 서명과 사설망 접근의 안정성을 걱정하는 기업 IT 책임자, 기존 Mac을 유지할지 격리 노드나 탄력적인 원격 Mac을 추가할지 결정하는 기술 총괄도 대상입니다.
마지막 검수: 2026년 8월 21일. 내용은 CircleCI의 macOS 마이그레이션 안내, 설치 안내와 설정 참고 자료를 기준으로 확인해야 합니다. Runner 버전과 지원 조건은 변경될 수 있으므로 배포 전 공식 변경 기록을 다시 확인해야 합니다.
00첫 단계: 생산 노드가 아니라 실패를 격리할 시범 노드를 정합니다
직접 교체가 위험한 이유는 새 Runner가 온라인으로 표시되는 것과 실제 작업을 안전하게 처리하는 것이 서로 다른 검수 항목이기 때문입니다. 이전 서비스가 작업을 받지 않게 되었는데 새 서비스가 시작되지 않으면 대기열만 늘어납니다. 반대로 이전 서비스와 새 서비스가 동시에 실행되면 서로 다른 설정과 인증 자료로 작업을 처리할 수 있습니다.
먼저 다음 항목을 문서로 고정합니다.
- 마이그레이션 대상 Mac과 현재 실행 중인 서비스 이름
- 해당 노드를 호출하는 프로젝트, 리소스 클래스와 배포 파이프라인
- 코드 서명, 사설망, 비밀 저장소에 대한 의존성
- 시범 검수 담당자와 운영 전환 승인자
- 실패 시 이전 노드 복구 여부 또는 대체 노드 전환 여부
- 점검 시간과 작업 중지 기준
시범 노드는 운영 서명 키를 그대로 복사한 임시 서버가 되어서는 안 됩니다. 생산 자료가 없는 기준 작업으로 체크아웃, 빌드, 로그, 종료 코드와 결과물 전달을 먼저 검사해야 합니다. 이후에만 제한된 테스트 인증 자료를 사용해 서명 흐름을 별도 검증합니다.
CircleCI의 공식 개요에서는 Machine Runner 3을 기존 launch agent의 대안으로 안내합니다. 따라서 이번 변경은 단순한 패키지 교체가 아니라 서비스 등록 방식과 운영 통제를 다시 확인하는 인프라 변경으로 다뤄야 합니다. 자세한 전환 순서는 공식 macOS 전환 절차를 기준으로 고정합니다.
01두 번째 단계: 남은 서비스와 설치 출처를 분리해 확인합니다
이전 launch agent의 서비스 파일만 지우고 실행 프로세스를 남겨 두거나, 새 Runner를 다른 경로에 설치하면서 두 설정을 혼용하는 경우가 대표적인 실패 원인입니다. 서비스 파일, 설치 디렉터리, 실행 프로세스, 설정 파일 경로를 각각 기록한 뒤 공식 절차에 따라 이전 서비스를 중지하고 제거합니다.
새 설치는 임의의 실행 파일을 내려받아 덮어쓰는 방식으로 진행하지 않습니다. macOS 설치 안내에 있는 설치 방식과 제공되는 패키지를 사용하고, 다음 증적을 남깁니다.
- 설치 파일을 받은 경로와 확인한 파일 식별 정보
- 설치 시각과 실행한 명령
- 설치 로그와 서비스 등록 결과
- 실행 파일의 서명과 공증 상태 확인 결과
- 설치된 Runner 버전과 설정 파일 위치
서명과 공증 확인은 파일이 실행된다는 뜻과 다릅니다. 기업 감사에서는 누가 어떤 출처의 파일을 어떤 권한으로 설치했는지도 필요합니다. 설치 증적이 없으면 장애가 발생했을 때 서비스 오류와 공급 파일 문제를 구분하기 어렵습니다.
검수 중 실패했을 때 운영 Mac에서 두 가지 시작 방식을 임시로 조합해서는 안 됩니다. 이전 서비스로 되돌릴지, 대체 노드로 작업을 보낼지 미리 정해야 합니다. 롤백은 “예전 명령을 다시 실행한다”가 아니라, 작업 라우팅과 인증 자료까지 이전 상태로 되돌리는 절차여야 합니다.
02세 번째 단계: 설정 파일의 문법이 아니라 동작 의미를 검증합니다
기존 설정 파일이 새 Runner에서 읽힌다는 결과는 출발점일 뿐입니다. Machine Runner 3 설정 참고 자료에 있는 항목과 기존 환경의 가정을 대조해야 합니다.
특히 다음 설정을 한 항목씩 비교합니다.
- working_directory가 실제 실행 사용자가 접근할 수 있는 경로인지
- cleanup_working_directory가 작업 종료 뒤 예상한 범위를 정리하는지
- runner mode와 command_prefix가 기존 호출 방식과 맞는지
- 작업의 최대 실행 시간 제한이 배포 작업과 충돌하지 않는지
- task-agent 캐시가 공유 작업 사이에 자료를 남기지 않는지
- 환경 변수와 키체인 경로가 이전 실행 사용자에 종속되지 않는지
설정 호환성은 문법과 일부 필드가 유지된다는 의미로 제한해서 해석해야 합니다. 경로 대체, 파일 권한, 셸 경로, 실행 계정이 다르면 같은 설정이 전혀 다른 결과를 낼 수 있습니다. 따라서 생산 자격 증명이 없는 기준 작업으로 아래 결과를 수집합니다.
- 저장소 체크아웃 성공 여부
- 빌드 도구 호출과 종료 코드
- 로그의 누락 또는 민감 정보 노출 여부
- 생성된 결과물의 저장과 회수
- 작업 종료 뒤 디렉터리와 임시 자료의 상태
기준 작업은 성공만 기록하지 않습니다. 실패할 때 어느 단계에서 멈췄는지와 사람이 복구하는 데 필요한 조치도 함께 남겨야 합니다. 이 기록이 있어야 기존 노드와 새 노드의 차이를 좁힐 수 있습니다.
03네 번째 단계: 잘못된 프로젝트가 Mac에 도달하지 않게 막습니다
Runner가 온라인이어도 잘못된 프로젝트가 해당 Mac에서 실행되면 보안 검수는 실패입니다. namespace, resource class, 인증 토큰과 프로젝트 설정이 시범 노드를 정확히 가리키는지 확인합니다. 운영 배포용 작업과 일반 테스트 작업을 같은 호출 범위에 두지 않는 것이 기본 원칙입니다.
검수 결과에는 다음 증거가 포함되어야 합니다.
- 시범 노드로 작업을 보낼 수 있는 허용 프로젝트
- 같은 리소스 클래스를 호출할 수 없어야 하는 거부 프로젝트
- 프로젝트와 리소스 클래스의 매핑 결과
- 토큰이 저장소, 공유 스크립트와 빌드 로그에 나타나지 않는다는 확인
- 토큰 발급과 교체를 담당하는 사람 또는 팀
조직 수준의 정책을 사용하는 경우에는 자체 운영 Runner 설정 정책과 현재 조직 규칙을 함께 대조합니다. 정책이 존재한다는 이유만으로 모든 프로젝트의 호출이 제한됐다고 가정하면 안 됩니다. 허용과 거부를 실제 작업으로 각각 확인해야 합니다.
토큰을 저장소의 설정 파일에 넣거나 로그에 출력하는 방식은 피해야 합니다. 작업 라우팅이 맞더라도 인증 자료가 노출되면 새 노드는 기존 노드보다 큰 위험을 만들 수 있습니다. 시범 단계에서는 토큰의 발급, 보관, 교체와 폐기 책임을 문서에 명시합니다.
04다섯 번째 단계: 작업 공간과 서명 자료의 교차 오염을 시험합니다
macOS 빌드 노드는 소스 코드만 처리하지 않습니다. SSH 체크아웃 키, 임시 키체인, 프로비저닝 프로필, 인증서와 빌드 결과물이 같은 호스트에 남을 수 있습니다. 특히 공유 Runner에서 작업 정리가 실패하면 다음 작업이 이전 작업의 파일이나 환경 변수를 읽을 가능성이 생깁니다.
서로 다른 두 시험 프로젝트를 준비하고 다음 순서로 확인합니다.
- 첫 번째 프로젝트가 고유한 파일과 환경 변수를 작업 공간에 만듭니다.
- 첫 번째 작업이 끝난 뒤 작업 디렉터리, 캐시와 임시 키체인을 검사합니다.
- 두 번째 프로젝트에서 첫 번째 프로젝트의 파일명, 값과 경로를 조회합니다.
- 첫 번째 프로젝트의 SSH 키, 서명 자료와 결과물이 두 번째 작업에서 보이지 않는지 확인합니다.
- 정리 실패가 발생하면 작업을 성공으로 처리하지 않고 원인을 기록합니다.
생산 서명을 담당하는 노드는 전용 실행 계정과 전용 resource class로 분리하는 편이 안전합니다. 일반 테스트가 같은 신뢰 영역에 들어가면 작업 정리 정책 하나만으로 모든 접근을 막기 어렵습니다. 공유가 필요한 캐시도 코드와 서명 자료를 함께 보관하지 않도록 범위를 나눠야 합니다.
05비교표: 고정 생산 Mac과 격리된 원격 Mac 시범 노드
| 검수 대상 | 기존 생산 Mac에서 바로 교체 | 격리된 원격 Mac에서 시범 운영 |
|---|---|---|
| 실패 영향 | 배포 대기와 복구 작업이 운영 흐름에 직접 연결됩니다 | 실패 범위를 시범 작업으로 제한할 수 있습니다 |
| 서비스 검증 | 이전 서비스 잔류와 새 서비스 충돌을 운영 중에 발견할 수 있습니다 | 서비스 파일과 프로세스를 분리해 비교할 수 있습니다 |
| 서명 자료 | 생산 인증서와 임시 자료가 같은 호스트에 남을 위험이 있습니다 | 제한된 시험 자료로 정리 동작을 먼저 확인할 수 있습니다 |
| 재시작 시험 | 운영 작업 중단을 감수해야 합니다 | 원격 재시작 뒤 상태와 기준 작업을 반복 확인할 수 있습니다 |
| 롤백 | 이전 상태와 새 상태가 섞일 가능성이 있습니다 | 대체 노드 전환 또는 이전 노드 복귀를 독립적으로 연습할 수 있습니다 |
원격 Mac을 시범 노드로 선택할 때는 접속 방식보다 통제 가능성을 먼저 봐야 합니다. SSH, VNC 또는 웹 콘솔 접근이 제공되더라도 실행 계정, 재시작 권한, 네트워크 허용 범위와 자료 폐기 절차를 확인해야 합니다. NUKCLOUD의 원격 Mac 서비스 안내를 검토할 때도 이 항목을 기업 내부 기준표와 대조해야 합니다.
06여섯 번째 단계: 재시작과 장애 복구를 실제 작업으로 승인합니다
재시작 뒤 프로세스가 보인다는 것만으로 자동 작업 수신을 승인하지 않습니다. 원격 재시작 뒤 서비스가 올바른 계정으로 실행되는지, 설정 파일을 읽는지, 예상 resource class에 연결되는지, 기준 작업이 성공하는지를 차례로 확인합니다.
다음 장애를 각각 독립된 시험으로 기록합니다.
- 원격 재시작 뒤 자동 시작
- Runner 프로세스의 비정상 종료 뒤 복구
- 짧은 네트워크 중단 뒤 재연결
- 작업 시간 초과 뒤 작업 공간 정리
- 작업 중단 뒤 중복 배포가 발생하지 않는지 확인
성능 수치를 임의로 채우지 말고 실제 기준 파이프라인의 대기 상태, 성공 여부, 실패 원인과 사람의 복구 동작을 기록합니다. 사이트 실측 자료가 없는 상태에서 처리량이나 복구 시간을 숫자로 제시하면 검수 문서의 신뢰도가 떨어집니다.
최종 판정은 다음 세 가지 중 하나로 남깁니다.
- 통과: 서비스, 라우팅, 정리, 서명 자료와 복구 시험이 모두 증거와 함께 완료된 경우
- 제한 방출: 일반 테스트만 허용하고 생산 서명이나 배포 작업은 기존 노드에 남기는 경우
- 수정 후 재검수: 서비스 충돌, 자료 잔류, 잘못된 라우팅 또는 재시작 실패가 한 항목이라도 남은 경우
조건별 선택
- 시범 노드에서 재시작과 기준 작업이 모두 성공하면 생산 노드를 분할해 전환합니다.
- 작업 정리는 성공하지만 서명 자료 격리가 실패하면 일반 테스트 전용으로 제한하고 생산 서명은 별도 노드로 분리합니다.
- Runner가 온라인이어도 허용 프로젝트와 거부 프로젝트가 구분되지 않으면 운영 전환을 중단합니다.
- 재시작 뒤 자동 복구가 되지 않으면 새 Runner를 생산 노드에 강제 설치하지 말고, 서비스 등록과 실행 계정을 수정한 뒤 다시 검수합니다.
- 고정 노드의 대기열이나 배포 SLA가 감당되지 않으면 기존 노드만 늘리지 말고 격리된 원격 Mac을 추가해 용량을 분리합니다.
- 장기간 같은 작업량이 지속되고 물리 장치 접근이 필요하면 직접 보유한 Mac이 더 적합할 수 있습니다. 반대로 시범 환경, 일시적인 증설과 실패 격리가 목적이면 원격 Mac 임대가 합리적입니다.
07FAQ: 현장에서 자주 막히는 마이그레이션 문제
위 검수에서 통과한 뒤에도 생산 전환 문서에는 설정 파일 위치, 서비스 복구 방법, 토큰 교체 담당자와 실패 시 라우팅을 남겨야 합니다. 기업 환경에서는 설치 성공보다 운영자가 같은 절차를 다시 실행할 수 있는지가 더 중요합니다.
실제 작업을 수행할 원격 Mac을 별도로 마련할 경우에는 NUKCLOUD 도움말에서 접속과 재시작 관련 운영 조건을 확인하고, 시범 결과에 따라 한국 지역 Mac 이용 절차를 검토할 수 있습니다.
직접 보유한 Mac 한 대를 즉시 교체하는 방식은 장비를 추가로 구매하지 않아도 된다는 장점이 있지만, 서비스 잔류, 생산 서명 자료와 테스트 작업의 혼재, 재시작 장애 시 단일 장애점이라는 문제가 남습니다. 반면 NUKCLOUD의 원격 Mac을 격리 시범 노드로 사용하면 실제 CircleCI Machine Runner 3 작업을 생산 노드와 분리해 검증할 수 있고, 통과 뒤 필요한 수만큼 장기 노드를 판단할 수 있습니다. 따라서 유일한 생산 Mac을 바로 개조하기보다, 먼저 임시 또는 추가 원격 Mac으로 마이그레이션 증거를 확보하는 편이 기업 운영에 더 안전합니다.