GitLab Runner macOS 자체 호스팅은 어떻게 배포하나요? 2026 가이드
Runner 작업이 Mac에 등록됐는데도 로그인 세션이나 Xcode 경로가 맞지 않아 CI 작업이 실패할 수 있습니다.
가장 빠른 판단은 실제 빌드할 macOS 호스트에 Runner를 설치하고, GitLab이 안내하는 사용자 수준 LaunchAgent와 shell executor를 사용하되 신뢰할 수 있는 프로젝트만 받도록 제한하는 것입니다.
이 글은 GitLab CI/CD에서 Xcode 빌드나 iOS 테스트를 실행하려는 개발자, Windows·Linux에서 macOS 빌드 노드를 관리하는 운영자, 원격 Mac을 지속적 통합에 쓸지 검토하는 팀을 위한 안내입니다.
먼저 실행 노드와 executor 선택을 판별합니다
GitLab Runner macOS 자체 호스팅 배포에서는 GitLab 서비스와 작업 실행 환경을 구분해야 합니다. Runner는 작업을 실행할 macOS 호스트에 설치하고, Xcode와 저장소 의존성도 해당 호스트에 준비합니다. GitLab 서버 자체를 Mac에 설치해야 한다는 뜻은 아닙니다.
GitLab은 iOS와 macOS 빌드에 shell executor를 권장합니다. 이 방식은 Runner가 설치된 호스트의 셸에서 작업을 실행하므로 macOS 도구 체인에 접근할 수 있습니다. 반면 작업별 격리가 강한 컨테이너 환경과 같지는 않습니다. GitLab의 macOS 설치 안내와 shell executor 설명을 기준으로 실행 방식을 정합니다.
| 선택지 | 작업 실행 위치와 조건 | 적합한 경우 | 주요 주의점 |
|---|---|---|---|
| macOS 호스트의 shell executor | Runner가 설치된 Mac의 셸에서 실행 | Xcode 등 macOS 도구 체인이 필요한 빌드 | 작업 간 격리가 제한적이므로 신뢰 범위 통제가 필요 |
| 다른 운영체제의 Runner | 해당 호스트의 실행 환경에서 동작 | macOS 전용 도구가 필요하지 않은 작업 | Xcode가 필요한 작업을 대신 실행할 수 없음 |
| GitLab 서비스와 macOS Runner 분리 | GitLab은 기존 서비스 환경에 두고, Mac은 작업 실행에 사용 | CI 서비스와 Apple 플랫폼 빌드 노드를 분리하려는 구성 | Runner 등록과 태그 라우팅을 별도로 확인 |
| 점검 항목 | 통과 기준 | 미통과 시 조치 |
|---|---|---|
| 실제 실행 환경 | 작업 로그에서 실행 호스트가 의도한 Mac으로 확인됨 | Runner 설치 위치와 태그 라우팅을 재점검 |
| 사용자 세션 | Runner가 지원되는 사용자 세션에서 동작함 | LaunchAgent와 로그인 조건을 확인 |
| Xcode 식별 | 활성 개발자 디렉터리와 도구 버전이 예상한 값으로 확인됨 | Xcode 설치와 선택 경로를 바로잡음 |
| 권한 경계 | 신뢰할 수 있는 프로젝트만 작업을 보냄 | Runner 범위와 프로젝트 접근 권한을 제한 |
| 결과 추적 | 로그, 결과물, 실패 원인을 다시 확인할 수 있음 | CI 설정과 결과물 보존 방식을 보완 |
로그인 세션과 서비스 방식의 조건을 확인합니다
macOS의 GitLab Runner 서비스는 사용자 수준 LaunchAgent로 실행해야 합니다. GitLab 문서는 시스템 수준 LaunchDaemon 실행을 지원하지 않는다고 안내합니다. 서비스 방식을 임의로 시스템 데몬으로 바꾸기보다 GitLab의 macOS 서비스 설정에 맞춰 설치와 실행 절차를 확인해야 합니다.
이 구분은 작업 환경에도 영향을 줍니다. LaunchAgent는 로그인한 사용자와 연결되므로, 사용자 세션이 필요한 작업은 세션 상태에 따라 동작이 달라질 수 있습니다. 키체인 접근, 시뮬레이터 실행, 서명 관련 작업을 포함한다면 해당 작업 계정의 권한과 로그인 상태를 실제 CI에서 검증해야 합니다. 재시작 뒤에도 작업을 받아야 하는 구성이라면 GitLab 문서의 로그인 및 서비스 조건을 확인하고, 자동 로그인이 필요한지와 그에 따르는 물리적 접근 위험을 함께 평가합니다. Apple의 사용자 에이전트와 시스템 데몬 구분도 서비스 계정 설계에 참고할 수 있습니다.
자동 로그인은 Runner의 편의 설정으로만 판단하면 안 됩니다. 빌드 계정이 로그인된 상태로 유지될 때 키체인과 로컬 자원에 접근할 수 있는 주체를 함께 점검해야 합니다.
계정은 빌드에 필요한 권한만 갖도록 구성합니다. 개인 개발자의 로그인 계정에 배포 키나 불필요한 관리 권한을 계속 두지 말고, 작업에서 접근할 수 있는 인증 정보와 저장 위치를 분리합니다.
Xcode와 macOS 도구 체인을 실제 작업에서 검증합니다
호스트에 Xcode가 설치되어 있다는 사실만으로 CI가 올바른 도구를 호출한다고 단정할 수 없습니다. 활성 개발자 디렉터리, 명령행 도구 설치 상태, 추가 구성 요소의 준비 여부를 확인하고 CI 로그에도 식별 결과를 남깁니다.
먼저 호스트에서 아래와 같이 상태를 확인합니다.
xcode-select -p
xcodebuild -version
두 명령의 출력이 팀에서 의도한 설치 경로와 Xcode에 맞는지 살핍니다. 명령행 도구 설치가 필요한 경우 Apple의 설치 안내를 확인합니다. 시뮬레이터 등 추가 구성 요소가 필요하다면 Apple의 Xcode 구성 요소 설치 안내를 기준으로 준비 상태를 점검합니다.
이후 Runner 태그가 지정된 CI 작업에서 도구 식별 결과와 대표 빌드의 로그를 확인합니다. 프로젝트가 요구하는 빌드 하나가 성공했는지와 함께 산출물 및 실패 정보를 추적할 수 있는지도 검증합니다. 빌드 성공은 시뮬레이터 실행, 테스트, 코드 서명과 같은 기능까지 자동으로 증명하지 않으므로 필요한 기능을 각각 확인해야 합니다.
shell executor의 권한 경계와 작업 라우팅을 검증합니다
shell executor는 작업을 호스트의 로컬 셸에서 실행합니다. 따라서 같은 Runner를 여러 신뢰 수준의 프로젝트가 공유하면 작업 간에 파일이나 인증 정보가 노출될 위험을 충분히 검토해야 합니다. GitLab도 shell executor의 보안상 한계를 설명하며, 자체 호스팅 Runner의 범위와 사용 주체를 관리하도록 안내합니다.
운영 전에는 다음 항목을 확인합니다.
- [ ] Runner가 받아야 하는 프로젝트와 그룹의 범위를 제한합니다.
- [ ] 작업 계정에 관리자 권한이나 불필요한 로컬 접근 권한을 부여하지 않습니다.
- [ ] 토큰, 서명 키, 키체인 등 민감 정보가 다른 작업에서 읽힐 가능성을 검토합니다.
- [ ] 신뢰할 수 없는 외부 기여 작업이 같은 Runner에 배정되지 않도록 정책을 확인합니다.
- [ ] 격리 요구가 높다면 shell executor를 격리 컨테이너처럼 취급하지 않고 다른 실행 아키텍처를 먼저 평가합니다.
GitLab의 Runner 범위 관리 안내에 따라 Runner를 어느 프로젝트나 그룹에서 사용할지 결정합니다. 프로젝트별 태그는 작업 선택을 돕지만, 태그만으로 신뢰 경계가 만들어지는 것은 아닙니다.
CI 설정에는 macOS 작업에만 쓰는 전용 태그를 지정하고, 최소 작업 하나를 실행해 로그에서 실제 실행 호스트와 셸을 확인합니다. 결과물과 실패 로그가 보존되는지도 검사합니다. 등록 단계와 토큰 입력 방식은 GitLab Runner 등록 안내를 참고하되, 토큰을 저장소에 직접 기록하지 않습니다.
자주 묻는 배포 판단을 정리합니다
GitLab Runner는 macOS에서 실행할 수 있나요?
가능합니다. 작업을 실행할 macOS 호스트에 Runner를 설치하고, 그 호스트에서 필요한 도구와 의존성을 준비합니다. GitLab 서버를 Mac에 옮기는 구성과는 구분해야 합니다. 등록 뒤에는 전용 태그를 사용해 최소 CI 작업을 실행하고, 로그에 표시된 호스트가 의도한 노드인지 확인합니다.
macOS 빌드에는 어떤 executor가 맞나요?
GitLab 문서는 iOS와 macOS 빌드에 shell executor를 권장합니다. 이 executor는 호스트의 셸에서 작업하므로 Xcode 같은 도구를 사용할 수 있습니다. 다만 작업마다 강한 격리를 제공하지 않으므로, 신뢰할 수 있는 프로젝트만 받도록 범위와 권한을 설정해야 합니다. 격리가 우선이라면 다른 실행 구성을 검토합니다.
LaunchDaemon 대신 LaunchAgent를 써야 하는 이유는 무엇인가요?
GitLab의 macOS 설치 문서는 사용자 수준 LaunchAgent 방식으로 Runner 서비스를 구성하도록 안내하며, 시스템 수준 LaunchDaemon은 지원하지 않는다고 명시합니다. LaunchAgent는 로그인 사용자 세션과 연결됩니다. 재시작 후 동작이 필요하면 문서에 적힌 로그인 조건을 확인하고, 자동 로그인으로 생기는 보안 영향을 별도로 평가합니다.
원격 Mac에서 Xcode 빌드는 무엇으로 확인하나요?
전용 태그가 붙은 최소 CI 작업으로 실행 호스트, 셸, Xcode 버전과 활성 개발자 디렉터리를 기록하고 대표 빌드를 수행합니다. 로그와 결과물을 보존해 실패 원인을 추적할 수 있어야 합니다. 시뮬레이터나 서명이 필요하다면 빌드 성공과 별개로 해당 기능을 사용하는 작업을 실행해 검증합니다.
노드 복구와 유지보수 조건을 결정합니다
배포 전에는 사용자 로그아웃, 호스트 재시작, 도구 체인 변경 뒤 Runner가 기대한 상태로 돌아오는지 확인합니다. 서비스 상태와 로그 위치는 실제 설치 방식에 맞춰 기록하고, 문제가 생겼을 때 누가 로그인 상태와 Xcode 경로를 복구할지 정합니다.
| 운영 목적 | 확인할 조건 | 판단 |
|---|---|---|
| 개인 시험 | 한 명의 담당자가 세션과 로그를 점검할 수 있음 | 제한된 범위에서 검증용으로 사용 |
| 팀 내부 빌드 | 프로젝트 범위, 계정 권한, 재시작 절차가 정리됨 | 통제된 팀 작업에 배정 |
| 핵심 파이프라인 | 장애 복구, 도구 체인 변경, 자격 증명 관리가 운영 절차에 포함됨 | 미검증 조건이 남으면 핵심 작업 배정 보류 |
원격 Mac을 검토할 때는 노드의 실제 접속 방법, 이용 가능 기간, 팀의 Xcode 요구 조건을 먼저 대조해야 합니다. KuzCloud 이용을 고려한다면 현재 이용 조건과 접속 방식을 확인하고, 한국 지역 안내에서 실제 제공 정보를 검토한 뒤 CI 노드로 적합한지 판단합니다. 이 글에서는 확인되지 않은 구성, 성능, 비용 또는 가용성을 전제로 하지 않습니다.
기존 Linux 서버는 macOS 전용 도구 체인을 실행할 수 없고, 자체 Mac은 초기 구매와 유지보수뿐 아니라 로그인 세션과 업데이트 관리까지 팀이 맡아야 합니다. shell executor의 격리 한계도 별도로 남습니다. 지속적인 고정 부하나 물리 인터페이스가 필요한 팀에는 자체 장비가 더 적합할 수 있지만, 기간이 한정된 검증이나 원격 빌드 노드가 필요한 경우에는 현재 조건을 확인한 뒤 KuzCloud의 접속 환경을 살펴보는 방식으로 비교할 수 있습니다.
맥 기반 빌드 환경이 필요하다면, KuzCloud와 시작하세요
전용 맥 미니 실기기로 가상화 부담 없이 macOS 빌드 작업을 실행할 수 있습니다.
완전한 관리자 권한으로 필요한 개발 도구와 자체 호스팅 실행 환경을 자유롭게 구성할 수 있습니다.