MacOS Runners
Table of Contents
[TOC]
Background
Section titled “Background”GitLab’s MacOS hosted runners have been a long-term goal spanning 5+ years. The current implementation uses AWS MacOS dedicated hosts after previous attempts with MacStadium that nearly reached GA but had fundamental flaws preventing full deployment.
Overview
Section titled “Overview”Google Cloud and AWS Account Information
Section titled “Google Cloud and AWS Account Information”All the MacOS fleeting hosts are dedicated hosts in AWS.
Google Cloud Project
Section titled “Google Cloud Project”- Runner Managers Location: Managed through Google Cloud Project
gitlab-ci-155816
Architecture
Section titled “Architecture”Environments
Section titled “Environments”All MacOS runner environments follow the same architectural pattern:
- saas-macos-staging: Production duplicate (M1) for testing all components (Account
251165465090) - saas-macos-medium-m1: Mac mini M1 machines for production workloads (Account
215928322474) - saas-macos-large-m2pro: Mac mini M2 Pro machines for resource-intensive jobs (Account
730335264460)
Key Technologies
Section titled “Key Technologies”- AWS MacOS Dedicated Hosts: Bare metal Mac mini machines running in AWS
- MacOS Virtualization Framework: Direct job VM management (replacing Tart after licensing changes)
- Tart: Still used for building job VM images (not for runtime)
- Packer: Automated AMI building
- Ansible: Tool installation and configuration
Key Projects
Section titled “Key Projects”General Runner Repositories
Section titled “General Runner Repositories”For general information on the projects that are used to maintain runners, including MacOS runners, refer to the projects overview.
MacOS Infrastructure
Section titled “MacOS Infrastructure”-
- gRPC server providing RPC API for job VM creation
- Integrated into gitlab-runner
-
- Manages auto-scaling groups for AWS
- Requires Terraform setup with ARN/credentials
Configuration Management
Section titled “Configuration Management”Testing
Section titled “Testing”- Macos platform tests
- CI pipelines for platform validation
MacOS Terraform Configurations
Section titled “MacOS Terraform Configurations”The infrastructure is defined using Terraform configurations located in the config-mgmt repository:
- Large macOS Runners (M2 Pro) configuration
- Medium macOS Runners (M1) configuration
- Staging macOS Runners configuration
Image Building
Section titled “Image Building”MacOS has a distinct process for building images for both host machines and job VMs.
Access to MacOS instances and job VMs
Section titled “Access to MacOS instances and job VMs”Refer to access.md for information on how to access MacOS instances and job VMs.
Debugging Issues
Section titled “Debugging Issues”Refer to debugging.md for a playbook on debugging issues with AWS MacOS runner instances.
Additional Information
Section titled “Additional Information”Refer to resources.md for information on the available AWS resources.