Apple은 현재 선택된 개발자 디렉터리를 xcode-select --print-path로 확인하도록 안내합니다. Xcode 명령줄 도구 설정 문서에 나온 이 확인을 포함해, Buildkite는 파이프라인을 조정하고 Mac Agent는 Xcode가 필요한 빌드와 테스트를 실행하도록 구성하세요. Linux에서 처리할 수 있는 단계는 그대로 분리하고, 큐 라우팅만으로 호스트 격리가 보장된다고 판단해서는 안 됩니다.
이 글은 기존 iOS 파이프라인을 Buildkite로 옮기는 플랫폼 엔지니어, 기업용 macOS 빌드 노드를 맡은 IT 담당자, 서명 권한과 릴리스 경계를 관리하는 팀 리더를 위한 안내입니다.
[ SECTION_01 ] 시작 단계: Mac에서 실행할 작업을 먼저 구분합니다
모든 파이프라인 단계를 Mac으로 옮길 필요는 없습니다. 먼저 각 단계가 요구하는 실행 환경과 도구를 확인합니다. Buildkite Agent는 지정된 작업을 받아 호스트에서 실행하므로, macOS와 Xcode가 실제로 필요한 단계만 Mac으로 라우팅하는 것이 기본 원칙입니다. Buildkite Agent 문서는 Agent의 작업 실행과 라우팅 방식을 설명합니다.
작업은 저장소 검사, 플랫폼 독립적인 스크립트, Apple 플랫폼 전용 작업으로 나눠 적습니다. 코드 포맷 확인이나 일반적인 정적 검사가 다른 실행 환경에서 동작한다면 그 환경에 남겨도 됩니다. Xcode 빌드, iOS 시뮬레이터 테스트, Apple 도구 체인에 의존하는 아카이브 작업은 Mac 실행 여부를 별도로 검증합니다.
| 작업 유형 | 권장 실행 위치 | 판단 근거 | 적합도 |
|---|---|---|---|
| 플랫폼 독립적인 검사와 스크립트 | 기존 공용 실행 환경 | macOS나 Xcode 의존성이 없는지 확인합니다 | 높음 |
| Xcode 빌드와 iOS 테스트 | macOS 빌드 노드 | Xcode와 Apple 플랫폼 도구가 필요한지 확인합니다 | 높음 |
| 생산 서명과 릴리스 작업 | 접근을 제한한 Mac 실행 환경 | 서명 자산과 코드 신뢰 수준을 별도로 검토합니다 | 조건부 |
파이프라인을 분할할 때는 단계 사이에 전달되는 소스와 산출물도 확인합니다. 특정 단계만 Mac으로 보냈더라도 이전 단계에서 필요한 파일이 전달되지 않으면 빌드가 실패할 수 있습니다.
[ SECTION_02 ] 준비 단계: 호스트와 Agent 실행 계정을 확인합니다
설치 전에 호스트의 macOS, 칩 아키텍처, 설치된 Xcode와 사용 가능한 도구 체인을 기록합니다. Xcode 선택은 시스템의 실제 설정과 맞아야 합니다. 다음 명령을 실행해 선택된 디렉터리와 도구 체인을 확인할 수 있습니다.
xcode-select --print-path
xcodebuild -version
xcodebuild -showsdks
Apple의 명령줄 도구 설정 문서에 따라 필요한 Xcode가 선택되었는지 확인하세요. 설치되어 있다는 사실만으로 빌드 작업이 그 도구를 사용한다고 단정할 수는 없습니다. 작업 실행 환경 안에서 확인 명령을 수행하고 로그에도 남겨야 합니다.
Buildkite Mac Agent는 어떤 macOS 계정으로 실행하나요?
Agent를 시작한 계정이 작업 프로세스의 파일 접근과 사용자 환경에 영향을 줍니다. 따라서 사람이 로그인한 개발자 계정을 그대로 사용할지, CI 작업 전용 계정을 마련할지 먼저 정하고 책임자를 지정합니다. 작업 디렉터리, 체크아웃된 저장소, 필요한 키체인, 산출물 저장 위치에 해당 계정이 실제로 접근할 수 있는지도 시험합니다.
계정 선택은 편의성만으로 결정하지 마세요. 여러 사람이 관리하는 계정은 퇴사나 권한 변경 시 관리가 불명확해질 수 있습니다. 전용 계정은 책임과 접근 범위를 분명히 하는 데 도움이 되지만, 키체인과 필요한 파일 권한을 별도로 구성해야 합니다. 권한이 부족한 작업을 무턱대고 관리자 권한으로 실행하는 대신 실패 원인을 확인하고 최소 권한으로 조정합니다.
Agent Token과 저장소 접근 자격 증명도 구분합니다. Token은 Agent가 Buildkite와 통신하는 데 쓰이며, 저장소 자격 증명은 체크아웃에 필요할 수 있습니다. 용도와 보관 책임이 다르므로 설정 파일, 파이프라인 스크립트, 로그에 비밀값을 직접 기록하지 마세요. Buildkite Agent Token 문서와 보안 점검 문서를 확인하고, 팀의 비밀 정보 관리 정책에 맞게 접근 범위를 정합니다.
[ SECTION_03 ] 설치 단계: Agent가 재시작 뒤에도 복구되는지 검수합니다
먼저 팀이 선택한 설치 방법과 현재 공식 안내를 대조합니다. Buildkite의 macOS Agent 설치 문서에 따라 설치하고, Agent 설정에 필요한 인증 정보를 안전하게 반영합니다. 설치 명령이나 설정 위치는 설치 방법과 문서 변경에 따라 달라질 수 있으므로, 오래된 내부 메모를 그대로 복사하지 말고 현재 문서를 기준으로 진행하세요.
현재 터미널에서 직접 시작한 Agent는 해당 터미널 세션에 의존할 수 있습니다. 반면 launchd를 통한 서비스 실행은 로그인이나 재시작 뒤의 동작을 별도로 검증해야 합니다. 서비스로 등록했다는 사실만으로 복구가 확인되는 것은 아닙니다. 호스트를 재시작한 뒤 Agent 상태를 확인하고, 실제 테스트 작업을 전달해 작업 수신과 실행, 완료 기록까지 검증합니다.
Agent 프로세스가 보이는지만으로 설치 검수를 끝내지 마세요. 작업 디렉터리 권한, 큐 연결, 로그 기록, 재시작 후 작업 수행까지 확인해야 운영 가능한 상태로 볼 수 있습니다.
[ SECTION_04 ] 구성 단계: 큐와 작업 조건으로 Mac 실행을 지정합니다
Buildkite 파이프라인에서 Xcode가 필요한 단계에 Mac용 큐를 지정하고, Agent가 그 큐에 등록되어 있는지 확인합니다. 아래는 작업 정의에 큐 조건을 두는 예시입니다. 실제 파이프라인의 구조와 큐 이름은 팀 설정에 맞춰 적용하세요.
agents:
queue: "macos"
command: "xcodebuild -workspace App.xcworkspace -scheme App -destination 'generic/platform=iOS Simulator' test"
이 예시가 모든 프로젝트에 그대로 맞는 것은 아닙니다. 워크스페이스나 스킴, 실행 대상은 저장소에 맞춰야 합니다. Buildkite Mac Agent 연결 여부는 큐 이름이 아니라 작업 로그에서 실제로 어떤 Agent가 작업을 받았는지 확인해 판단합니다. 큐 관리 문서에서 큐 설정과 관리를 확인하세요.
실제 작업 흐름에서는 공용 검사와 Apple 플랫폼 전용 단계를 분리합니다. 각 단계가 전달하는 산출물과 필요한 파일을 확인하고, Mac 단계가 이전 단계의 결과를 올바르게 받는지도 점검합니다. 큐 이름만으로 macOS 버전, Xcode 버전, Agent 계정 또는 호스트 격리 상태를 추론하지 마세요. 그런 정보는 Agent 설정과 실행 로그, 호스트의 실제 점검 결과로 확인해야 합니다.
[ SECTION_05 ] 보안 단계: 큐 라우팅과 호스트 격리를 구별합니다
큐는 작업을 적절한 Agent로 전달하는 경로이지, 그 자체로 호스트 수준의 보안 경계를 만드는 장치는 아닙니다. 일반 테스트, 신뢰할 수 없는 풀 리퀘스트, 생산 서명 작업을 같은 방식으로 취급하지 말고 각각의 코드 신뢰도와 필요한 자격 증명을 검토하세요.
신뢰할 수 없는 코드가 실행되는 작업에는 생산 서명 자산을 제공하지 않는 방향으로 설계합니다. 생산 릴리스 작업은 접근 권한을 제한하고, 승인 책임과 실행 환경을 분리할지 평가합니다. 저장소 접근 자격 증명, Agent Token, 서명 자료를 누가 발급하고 회수하는지 문서화하세요. 로그에 비밀값이나 서명 관련 민감 정보가 출력되지 않는지도 확인합니다. 격리가 필요하다면 큐 이름에 의존하지 말고 기업의 실제 호스트 분리 정책과 접근 통제를 점검해야 합니다.
[ SECTION_06 ] 검수 단계: 실제 iOS 작업 흐름으로 연결을 증명합니다
Buildkite 작업이 시작되거나 큐가 온라인으로 표시되는 것만으로는 완료가 아닙니다. 팀에서 사용하는 대표 프로젝트를 선택해 다음 항목을 끝까지 확인합니다.
- 저장소 체크아웃과 필요한 의존성 준비가 성공하는지 확인합니다.
- 작업 실행 중
xcode-select --print-path와xcodebuild -version을 기록해 실제 선택된 Xcode를 확인합니다. - 프로젝트에 맞는
xcodebuild빌드와 테스트를 실행하고 결과를 검토합니다. - 생성된 산출물이 다음 단계에서 사용할 수 있게 보관되는지 확인합니다.
- 필요한 경우에만 아카이브와 서명 절차를 시험하고 승인 기록을 남깁니다.
- Agent 상태와 실행 로그를 함께 살펴 실패 원인을 추적할 수 있는지 점검합니다.
- 호스트 재시작 뒤에도 작업이 수신되고 실행되는지 확인합니다.
Xcode 테스트 결과는 명령의 종료 상태만 확인하고 끝내지 마세요. Apple의 테스트 실행 및 결과 해석 문서를 참고해 결과 보고서와 실패 정보를 검토하고, 팀의 검수 기록에 연결합니다. 풀 리퀘스트 작업과 생산 릴리스 작업의 권한이 다르다면 각각의 실제 흐름으로 검사해야 합니다.
판정은 아래 조건으로 내립니다.
- Xcode 의존 단계만 Mac에서 실행되고 공용 검사는 기존 환경에서 수행된다면, 혼합 라우팅을 선택합니다.
- 테스트와 생산 서명에 필요한 권한 및 호스트 경계가 분명하다면, 해당 정책을 반영해 단계적으로 운영에 적용합니다.
- 신뢰할 수 없는 코드와 생산 서명 자산을 분리할 수 없다면, 서명 작업을 활성화하지 말고 권한 설계부터 다시 검토합니다.
- Agent가 재시작 뒤 작업을 처리하지 못하거나 선택된 Xcode를 입증할 로그가 없다면, 운영 전환을 보류하고 서비스 시작 방식과 도구 체인을 수정합니다.
원격 Mac 노드를 검토할 때는 팀의 접근 방식과 운영 책임, 작업 후 데이터 처리, 장애 시 복구 절차를 먼저 확인하세요. 장비를 직접 구매하면 장기 보유와 유지 관리 책임이 따르고, 임시 용량을 외부에 맡기면 접근 통제와 운영 정책을 사전에 맞춰야 합니다. 원격 Mac을 고려하는 팀은 맥 미니 M4 렌탈 가격 안내를 참고해 확인할 항목을 정리할 수 있습니다.
현재 사내 장비만으로 운영하면 초기 환경 통일에 시간이 들고, 유휴 장비도 계속 관리해야 하며, 증설과 교체를 직접 책임져야 할 수 있습니다. 반대로 원격 Mac 임대는 단기 테스트나 팀 규모 변화에 맞춘 노드 검토에 활용할 수 있지만, 장기간 고정 부하를 맡기거나 물리 장비 접근이 필요한 경우에는 자체 장비가 더 적합할 수 있습니다. NOVAKVM을 검토한다면 실제 인수 방식과 접근 권한, 운영 책임이 팀 정책에 맞는지 먼저 확인한 뒤 한국에서 이용 가능한 맥 미니 안내를 살펴보세요.