GitLab CI Mac Runner는 어떻게 구성할까? 2026 배포 검수 가이드

증상 → Linux 실행 노드에서는 Apple 플랫폼 빌드가 막힙니다. 해결 → GitLab CI 맥 러너는 macOS 전용 노드에 설치해 시험하되, Shell executor의 격리 한계를 먼저 통과 조건으로 삼으세요. GitLab은 macOS 설치를 지원하지만 Shell executor는 격리가 제한되며 유지보수 모드로 안내됩니다. 공유 노드나 신뢰할 수 없는 코드가 들어오는 프로젝트에 기본 배포하지 마세요.

이 글은 Xcode 빌드와 테스트를 GitLab CI로 옮기려는 iOS·macOS 개발자에게 적합합니다.
macOS Runner를 등록하고 재시작 후 동작까지 관리해야 하는 DevOps 엔지니어도 대상입니다.
실행 계정, 자격 증명, 격리 경계를 검토하는 연구 플랫폼 및 보안 담당자도 확인하세요.

SECTION 01첫 단계: macOS Runner를 맡길 작업과 노드를 구분합니다

GitLab Runner는 macOS에 설치할 수 있으며, iOS·macOS 작업은 Shell executor를 사용하는 구성을 공식 문서에서 설명합니다. 그러나 설치 가능 여부가 곧 안전한 공유 노드라는 뜻은 아닙니다. GitLab의 실행기 안내에서 Shell executor는 유지보수 모드로 분류되고, 격리 기능도 제한적이라고 명시됩니다. macOS 설치 절차와 실행기 상태 및 지원 안내를 함께 확인하세요.

macOS용 GitLab Runner를 설치할 수 있나요?
가능합니다. 다만 노드의 역할을 Apple 플랫폼 빌드·테스트로 한정하고, 실행할 프로젝트와 저장소의 신뢰 수준을 먼저 정해야 합니다. 일반적인 코드 검사와 플랫폼 공통 작업은 기존 CI 실행 환경에 두고, Xcode가 필요한 작업만 맥 노드로 보내면 불필요한 권한 노출을 줄일 수 있습니다.

GitLab CI에서 맥 실행기는 어떤 실행기를 선택해야 하나요?
Xcode와 macOS 도구를 직접 호출해야 한다면 공식 macOS 안내에 기재된 Shell executor 구성을 기준으로 검토할 수 있습니다. 다만 이를 컨테이너처럼 작업을 격리하는 방식으로 취급해서는 안 됩니다. 더 강한 격리가 필요하다면 Shell executor에 권한을 더하는 대신, 요구되는 격리 수준을 충족하는 다른 지원 실행 구성을 먼저 평가하세요. Shell executor의 격리와 보안 설명을 배포 결정에 반영해야 합니다.

SECTION 02두 번째 단계: 전용 노드와 도구 버전을 기록합니다

맥 노드를 등록하기 전에 실행 계정, 사용 목적, 허용 프로젝트, 작업 실패 시 되돌릴 경로를 문서로 남기세요. 개인 작업 환경을 그대로 실행 노드로 겸용하면 셸 설정, 사용자 파일, 키체인 권한이 CI 작업에 노출될 수 있습니다. 별도 계정이나 전용 장비로 분리할 수 없다면, 먼저 저장소 접근 범위와 자격 증명 경계를 확인하고 시험 범위를 좁히세요.

Xcode 또는 명령 줄 도구는 프로젝트가 요구하는 도구 체인에 맞춰 준비합니다. 설치됐다는 사실만으로 CI 작업에서 사용할 도구가 선택됐다고 판단하지 마세요. Apple 개발자 문서의 명령 줄 도구 설치 안내와 Xcode 명령 줄 도구 참조를 확인한 뒤, 노드에서 실제 개발자 디렉터리와 도구 버전을 기록합니다.

명령이 정상 출력되는지, 프로젝트가 요구하는 구성 요소를 찾는지 확인하세요. Xcode 버전이나 노드 성능은 문서만으로 대신 판단하지 말고, 실제 프로젝트가 사용할 도구와 빌드 로그를 근거로 남기세요.

SECTION 03세 번째 단계: 로그인 세션을 확인한 뒤 Runner를 등록합니다

GitLab의 macOS 안내에 따라 Runner를 설치하고 등록합니다. 등록 과정은 GitLab Runner 등록 문서를 따르세요. 토큰은 명령 예시에 직접 넣거나 문서·로그에 남기지 말고, 실제 값 대신 <등록_토큰> 같은 자리표시자를 사용하세요. 프로젝트 범위와 태그도 의도한 작업만 이 노드로 배정되도록 설정합니다.

macOS의 Runner는 사용자 로그인 세션에 의존하는 사용자 수준 LaunchAgent로 동작합니다. 시스템 수준 서비스인 LaunchDaemon과 같다고 간주하면 안 됩니다. 따라서 터미널에서 등록에 성공하거나 Runner가 온라인으로 표시되는 사실만으로, 로그아웃 이후에도 작업을 받을 수 있다고 결론 내릴 수 없습니다. 서비스 방식은 GitLab macOS Runner 설치 문서의 설명을 기준으로 확인하세요.

자동 로그인을 켜면 재부팅 뒤 세션이 이어질 수 있지만, 계정이 열린 상태를 유지하는 보안 비용이 생깁니다. 자동 로그인을 기본 해결책으로 두지 말고, 장비 접근 통제와 키체인·서명 자산의 노출 위험을 검토한 뒤 결정하세요.

SECTION 04네 번째 단계: 최소 작업으로 실제 Xcode 호출을 검증합니다

먼저 Runner의 태그와 작업 라우팅을 확인하는 작은 파이프라인을 실행합니다. 프로젝트, 저장소, 태그, 스킴, 경로는 실제 값으로 바꾸되, 로그와 설정 예시를 공유할 때는 비밀 값이 포함되지 않도록 정리하세요. 다음 예시는 동작 확인용 뼈대이며, 프로젝트의 빌드 방식에 맞춰 수정해야 합니다.

mac_build:
  tags:
    - <맥_러너_태그>
  script:
    - whoami
    - xcode-select -p
    - xcodebuild -version
    - xcodebuild -project <프로젝트_경로> -scheme <스킴> -showBuildSettings

Runner가 온라인인지, 작업이 실제로 예약됐는지, 저장소 체크아웃이 끝났는지, 셸 명령이 어떤 계정으로 실행됐는지를 각각 확인하세요. 그다음 출력된 개발자 디렉터리와 Xcode 버전을 노드 기준선과 비교합니다. 마지막으로 프로젝트에서 쓰는 빌드 또는 테스트 명령을 실행하고, 성공·실패 로그와 선택된 스킴을 보관하세요.

예상한 Xcode가 실제 CI 작업에 사용되는지 어떻게 확인하나요?
작업 로그에서 xcode-select -p와 xcodebuild -version의 출력을 확인하고, 이어지는 빌드 명령의 결과를 프로젝트 기준과 대조하세요. Runner 화면의 온라인 상태는 Xcode 선택이나 프로젝트 빌드 성공을 증명하지 않습니다. Xcode 경로가 다르면 작업 스크립트가 기대하는 환경을 다시 선택한 뒤 같은 검증을 반복하세요.

SECTION 05다섯 번째 단계: 자격 증명과 작업 간 잔여물을 검사합니다

첫 빌드가 통과해도 바로 공유 사용으로 넓히지 마세요. 저장소 접근 권한, 작업 디렉터리에 남는 파일, 키체인 접근, 코드 서명 자산을 각각 검토합니다. 작업이 끝난 뒤 다른 작업이 이전 결과물이나 임시 자격 증명을 읽을 수 있는지 확인하고, 보관이 필요 없는 파일은 제거하는 절차를 추가하세요.

GitLab은 자체 관리 Runner의 보안 위험을 별도로 설명합니다. 자체 관리 Runner 보안 안내와 Shell executor 문서를 기준으로, 외부 기여 코드나 권한 범위가 다른 프로젝트를 같은 노드에 받지 않도록 하세요. 서명 자산이 필요한 작업은 저장소 전체에 비밀 값을 노출하지 말고, 누가 실행할 수 있는지와 자격 증명 회수 방법을 운영 절차에 포함해야 합니다.

아래 항목 중 하나라도 답이 정해지지 않았다면 확대 배포를 보류하세요.

• [ ] 맥 노드가 개인 개발 환경과 분리되어 있고, 허용된 프로젝트가 정해져 있습니다.
• [ ] 실행 계정과 저장소 접근 권한을 필요한 범위로 제한했습니다.
• [ ] 작업 후 작업 공간과 임시 파일이 남는지 확인하고 정리 방법을 마련했습니다.
• [ ] 키체인 및 서명 자산의 접근 주체와 회수 절차를 확인했습니다.
• [ ] 외부 기여 코드나 신뢰할 수 없는 작업은 이 노드에 배정되지 않습니다.
• [ ] 실패 시 해당 태그의 작업 배정을 중지하고 기존 CI 경로로 되돌릴 수 있습니다.

SECTION 06여섯 번째 단계: 로그아웃과 재부팅 뒤 운영 여부를 결정합니다

정상 빌드가 끝나면 사용자 로그아웃, 시스템 재시작, Runner 상태 변경을 각각 점검하세요. 각 조건에서 Runner가 다시 연결되는지, 작업이 예약되는지, 실제 Xcode 명령이 실행되는지를 기록합니다. macOS Runner가 로그인 사용자 세션에 의존한다는 안내를 고려하면, 로그아웃 뒤 동작이 달라질 수 있습니다. 재부팅 복구를 검증하지 않은 상태에서 상시 실행을 전제로 운영하지 마세요.

사용자 로그아웃이나 맥 재시작 뒤에도 GitLab Runner가 계속 실행되나요?
같은 결과를 모든 설정에 일반화할 수 없습니다. 문서는 macOS Runner의 사용자 세션 의존성을 설명하므로, 네 노드에서 로그아웃과 재시작을 직접 시험해야 합니다. 재연결 여부뿐 아니라 Runner 서비스 상태, 작업 예약, 실제 빌드 로그까지 확인하세요. 복구가 요구사항에 미치지 못하면 자동 로그인을 무조건 켜기보다 운영 방식이나 실행 구성을 다시 검토하세요.

시험 결과는 다음처럼 분리해 승인하세요. Runner 온라인은 연결 상태의 증거입니다. 작업 예약은 태그와 프로젝트 라우팅의 증거입니다. Xcode 출력은 도구 선택의 증거입니다. 실제 빌드·테스트 성공은 프로젝트 실행의 증거이며, 재시작 뒤의 성공은 복구 가능성의 증거입니다. 이 증거를 모두 확보한 뒤에만 제한된 프로젝트의 시험 운영을 시작하세요.

현재 Linux 또는 Windows 실행 노드만 사용하는 구성은 macOS 전용 도구 체인을 호출할 수 없고, 개인 맥을 그대로 공유하면 개발 환경과 키체인 권한이 CI 작업에 섞일 수 있습니다. 반면 전용 맥 노드를 직접 상시 운영하면 장비 준비와 로그인 세션, 복구 점검을 직접 책임져야 합니다. 우선 단기 시험이나 분리된 CI 환경이 필요한 경우라면, MACNOX의 원격 맥 환경 안내와 요금 및 이용 조건을 확인해 실제 요구사항에 맞는지 검토하세요. 지속적인 고부하 작업이나 물리 장비 접근이 필요한 경우에는 임대가 적합하지 않을 수 있습니다. 자격 증명과 재시작 검수가 끝나기 전에는 어떤 노드도 공유 Runner로 확대하지 마세요.

SECTION 07더 읽어보기

• 원격 맥에서 GitLab CI iOS 빌드와 아카이브 검증하기
• 기업 CI에서 엑스코드 이십육 라이선스와 첫 실행 상태 점검하기