macOS용 호스티드 러너

macOS용 호스티드 러너 (Hosted runners on macOS)

macOS용 호스티드 러너는 GitLab CI/CD와 완전히 통합된 온디맨드 macOS 환경을 제공해요. 이 러너를 쓰면 Apple 생태계(macOS, iOS, watchOS, tvOS)용 앱을 빌드하고, 테스트하고, 배포할 수 있어요. 우리 Mobile DevOps 섹션에는 iOS용 모바일 앱을 빌드하고 배포하는 기능, 문서, 가이드가 정리돼 있으니 함께 참고하면 좋아요.

macOS용 호스티드 러너는 현재 beta 단계이며, 오픈소스 프로그램과 Premium·Ultimate 요금제 고객에게 제공돼요. generally available 전환은 epic 8267에서 제안되어 있어요.

사용 전에 macOS 호스티드 러너에 영향을 주는 알려진 이슈와 사용 제약 목록을 먼저 확인해보세요.

출처: 문서

본문

macOS에서 사용 가능한 머신 타입

GitLab은 macOS 호스티드 러너에 대해 다음과 같은 머신 타입을 제공해요. x86-64 대상을 빌드하려면 Rosetta 2를 사용해 Intel x86-64 환경을 에뮬레이션할 수 있어요.

Runner Tag	vCPUS	Memory	Storage
`saas-macos-medium-m1`	4	8 GB	50 GB
`saas-macos-large-m2pro`	6	16 GB	50 GB

지원되는 macOS 이미지

Linux 호스티드 러너에서는 어떤 Docker 이미지든 실행할 수 있는 반면, macOS에서는 GitLab이 제공하는 VM 이미지 세트를 사용해요.

.gitlab-ci.yml 파일에서 아래 이미지 중 하나를 지정해서 빌드를 실행할 수 있는데, 각 이미지는 특정 버전의 macOS와 Xcode를 실행해요.

VM image	Status
`macos-15-xcode-16`	`GA`	Preinstalled Software
`macos-26-xcode-26`	`GA`	Preinstalled Software
`macos-27-xcode-27`	`beta`	Preinstalled Software

이미지를 지정하지 않으면 macOS 러너는 macos-26-xcode-26을 사용해요.

macOS 이미지 업데이트 정책

이미지와 설치된 구성요소는 GitLab 릴리스 때마다 갱신되어 사전 설치 소프트웨어를 최신 상태로 유지해요. GitLab은 보통 여러 버전의 사전 설치 소프트웨어를 지원하는데, 자세한 내용은 사전 설치 소프트웨어 전체 목록에서 확인할 수 있어요.

macOS와 Xcode의 메이저·마이너 릴리스는 Apple 릴리스 이후 다음 마일스톤에서 제공돼요.

새 메이저 릴리스 이미지는 처음에는 beta로 제공되고, 첫 마이너 릴리스가 나오면 일반 공개(GA)로 전환돼요. 동시에 지원되는 GA 이미지는 두 개뿐이라, 가장 오래된 이미지는 지원 이미지 수명주기에 따라 3개월 후 deprecated 처리되어 제거돼요.

새 메이저 릴리스가 GA가 되면 모든 macOS 잡의 기본 이미지가 돼요.

예제 `.gitlab-ci.yml` 파일

다음 샘플 .gitlab-ci.yml 파일은 macOS 호스티드 러너를 시작하는 방법을 보여줘요:

.macos_saas_runners:
  tags:
    - saas-macos-medium-m1
  image: macos-26-xcode-26
  before_script:
    - echo "started by ${GITLAB_USER_NAME} / @${GITLAB_USER_LOGIN}"

build:
  extends:
    - .macos_saas_runners
  stage: build
  script:
    - echo "running scripts in the build job"

test:
  extends:
    - .macos_saas_runners
  stage: test
  script:
    - echo "running scripts in the test job"

fastlane으로 iOS 프로젝트 코드 서명하기

GitLab을 Apple 서비스와 연동하거나, 기기에 설치하거나, Apple App Store에 배포하려면 먼저 애플리케이션에 코드 서명을 해야 해요.

각 macOS 러너 VM 이미지에는 모바일 앱 배포를 단순화하는 오픈소스 도구인 fastlane이 포함되어 있어요.

애플리케이션 코드 서명을 설정하는 방법은 Mobile DevOps 문서의 지침을 참고하세요.

Homebrew 최적화

기본적으로 Homebrew는 어떤 작업을 시작할 때마다 업데이트를 확인해요. Homebrew의 릴리스 주기는 GitLab macOS 이미지 릴리스 주기보다 짧을 수 있는데, 이 차이 때문에 Homebrew가 업데이트를 수행하는 동안 brew를 호출하는 단계가 더 오래 걸릴 수 있어요.

의도하지 않은 Homebrew 업데이트로 인한 빌드 시간을 줄이려면 .gitlab-ci.yml에서 HOMEBREW_NO_AUTO_UPDATE 변수를 설정하세요:

variables:
  HOMEBREW_NO_AUTO_UPDATE: 1

CocoaPods 최적화

프로젝트에서 CocoaPods를 사용한다면 CI 성능을 높이기 위해 다음 최적화를 고려해보세요.

CDN 액세스 활성화

콘텐츠 전송 네트워크(CDN) 액세스를 사용하면 전체 프로젝트 저장소를 클론하는 대신 CDN에서 패키지를 다운로드할 수 있어요. CDN 액세스는 CocoaPods 1.8 이상에서 사용할 수 있고, 모든 GitLab macOS 호스티드 러너에서 지원돼요.

CDN 액세스를 활성화하려면 Podfile이 다음으로 시작하는지 확인하세요:

source 'https://cdn.cocoapods.org/'

GitLab 캐싱 사용

GitLab의 CocoaPods 패키지 캐싱을 사용하면 pod가 변경될 때만 pod install을 실행하도록 해서 빌드 성능을 개선할 수 있어요.

프로젝트의 캐시를 구성하려면:

.gitlab-ci.yml 파일에 cache 구성을 추가하세요: `cache: key: files:
- Podfile.lock paths:

Pods`

프로젝트에 cocoapods-check 플러그인을 추가하세요.
pod install을 호출하기 전에 설치된 의존성을 확인하도록 잡 스크립트를 수정하세요: bundle exec pod check || bundle exec pod install

pod를 소스 제어에 포함하기

pods 디렉터리를 소스 제어에 포함할 수도 있어요. 그러면 CI 잡에서 pod를 설치할 필요가 없어지지만, 프로젝트 저장소 전체 크기는 커져요.

알려진 이슈와 사용 제약

VM 이미지에 잡에 필요한 특정 소프트웨어 버전이 없다면 필요한 소프트웨어를 가져와 설치해야 해요. 이 때문에 잡 실행 시간이 늘어나요.
자체 OS 이미지를 가져올 수는 없어요.
gitlab 사용자의 키체인은 공개적으로 사용할 수 없어요. 대신 키체인을 직접 만들어야 해요.
macOS 호스티드 러너는 headless 모드로 실행돼요. testmanagerd처럼 UI 상호작용이 필요한 워크로드는 지원되지 않아요.
Apple Silicon 칩은 효율 코어와 성능 코어가 있어서 잡 실행마다 성능이 달라질 수 있어요. 코어 할당이나 스케줄링을 제어할 수 없어서 불일치가 생길 수 있어요.
macOS 호스티드 러너에 사용되는 AWS 베어메탈 macOS 머신 가용성이 제한돼요. 머신이 없으면 잡의 대기 시간이 길어질 수 있어요.
macOS 호스티드 러너 인스턴스가 요청에 응답하지 않는 경우가 있어서, 최대 잡 지속 시간에 도달할 때까지 잡이 멈춰 있을 수 있어요.
macOS는 기본적으로 대소문자를 구분하지 않는 파일 시스템을 사용해요. 대소문자만 다른 중복 파일 경로가 있으면 예상치 못한 오류가 발생할 수 있어요. 이런 중복 경로는 Git 작업 트리나 브랜치·태그가 저장되는 Git refs에 있을 수 있어요.

더 알아보기

다음으로는 Mobile DevOps 튜토리얼을 따라가며 iOS 앱 빌드 환경을 구성해보고, fastlane으로 코드 서명까지 설정해보세요. macOS 이미지의 수명주기와 사전 설치 소프트웨어 목록도 참고하면 예상 가능한 빌드 환경을 유지할 수 있어요.

macOS용 호스티드 러너