Зачем использовать собственные GitLab Runner на Mac?
GitLab предлагает общие runner на Linux, но для сборки iOS-приложений требуется macOS, работающая на оборудовании Apple. Собственные macOS runner от GitLab ограничены и дороги. Собственный GitLab Runner на Mac Mini M4 даёт вам:
-
Неограниченные минуты CI/CD
Бесплатный тариф GitLab включает 400 минут CI/CD на общих runner. На собственном runner ограничений нет.
-
Нативный Apple Silicon
Собирайте на том же чипе M4, на котором работают устройства ваших пользователей. Никаких накладных расходов на трансляцию через Rosetta.
-
Полный контроль окружения
Устанавливайте любую версию Xcode, симуляторы, инструменты и зависимости, которые вам нужны.
-
Постоянные кэши
DerivedData, пакеты SPM и кэши CocoaPods сохраняются между запусками пайплайна.
Установка GitLab Runner
Подключитесь по SSH к вашему выделенному серверу сборки Mac mini M4 и установите GitLab Runner, а также xcbeautify для читаемых логов сборки, с помощью Homebrew:
# Connect to your Mac Mini M4
ssh admin@your-server-ip
# Put the preinstalled Homebrew on your PATH (once per account)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
# Install GitLab Runner with Homebrew, plus xcbeautify for the pipeline's build logs
brew install gitlab-runner xcbeautify
# Verify installation (prints the version and OS/Arch: darwin/arm64)
gitlab-runner --version
Установка как службы macOS
# Run the runner as a launchd service. It is a LaunchAgent: it starts when
# your user session starts, so on a headless Mac enable automatic login for
# this user (System Settings > Users & Groups) to bring it back after a reboot
brew services start gitlab-runner
# Verify the service is running
brew services list | grep gitlab-runner
# gitlab-runner started admin ~/Library/LaunchAgents/homebrew.mxcl.gitlab-runner.plist
Регистрация Runner
Откройте ваш проект в GitLab, перейдите в Settings > CI/CD > Runners и выберите Create project runner (для группы: Build > Runners > Create group runner). В поле Tags укажите macos и m4 (их использует пайплайн ниже), создайте runner и скопируйте его токен аутентификации, который начинается с glrt-. С токеном аутентификации команда register не принимает теги и другие параметры runner: они задаются здесь, в GitLab. Чтобы автоматизировать этот шаг, создайте runner через API (пример ниже).
Регистрация с токеном аутентификации runner
# Optional: create the runner with the API instead of the GitLab UI.
# Needs an access token with the create_runner scope; the "token"
# field of the response is the runner authentication token (glrt-...)
curl --request POST \
--header "PRIVATE-TOKEN: YOUR_ACCESS_TOKEN" \
--url "https://gitlab.com/api/v4/user/runners" \
--data "runner_type=project_type" \
--data "project_id=YOUR_PROJECT_ID" \
--data "tag_list=macos,m4" \
--data "run_untagged=false"
# Register the runner with its authentication token (starts with glrt-).
# Tags, untagged jobs and locking come from the runner you created in GitLab:
# do not pass --tag-list or --run-untagged with an authentication token
gitlab-runner register \
--non-interactive \
--url "https://gitlab.com/" \
--token "YOUR_RUNNER_AUTHENTICATION_TOKEN" \
--executor "shell" \
--name "mac-mini-m4-runner"
# Confirm the runner can reach GitLab
gitlab-runner verify
Старый способ: регистрация с регистрационным токеном
Регистрационные токены объявлены устаревшими в GitLab 15.6, и GitLab планирует удалить их в GitLab 20.0. Начиная с GitLab 17.0 они работают, только если администратор (или, на GitLab.com, владелец группы верхнего уровня) снова их включил. Используйте этот способ только на экземпляре GitLab, который всё ещё этого требует.
# Legacy: registration token (deprecated since GitLab 15.6,
# removal scheduled for GitLab 20.0). On GitLab 17.0 and later,
# it works only where registration tokens were enabled again.
gitlab-runner register \
--non-interactive \
--url "https://gitlab.example.com/" \
--registration-token "YOUR_REGISTRATION_TOKEN" \
--executor "shell" \
--description "mac-mini-m4-runner" \
--tag-list "macos,apple-silicon,m4,ios,xcode" \
--run-untagged="false"
Проверка конфигурации Runner
# View the runner config file
cat ~/.gitlab-runner/config.toml
# Expected output:
# concurrent = 2
# check_interval = 0
#
# [session_server]
# session_timeout = 1800
#
# [[runners]]
# name = "mac-mini-m4-runner"
# url = "https://gitlab.com/"
# token = "..."
# executor = "shell"
# [runners.cache]
# MaxUploadedArchiveSize = 0
# Adjust concurrency based on your hardware:
# Mac Mini M4 (16GB): concurrent = 2
# Mac Mini M4 Pro (24GB): concurrent = 3
# Mac Mini M4 Pro (48GB): concurrent = 4
Отредактируйте ~/.gitlab-runner/config.toml, чтобы настроить параллелизм:
# Edit the config
nano ~/.gitlab-runner/config.toml
# Set concurrent to match your hardware capacity
concurrent = 2
# Restart the service to apply changes
brew services restart gitlab-runner
Runner должен теперь отображаться как Online в вашем проекте GitLab в разделе Settings > CI/CD > Runners.
Создание .gitlab-ci.yml для iOS
Создайте файл .gitlab-ci.yml в корне вашего репозитория. Этот полный пайплайн собирает, тестирует и деплоит ваше iOS-приложение:
# .gitlab-ci.yml
stages:
- build
- test
- deploy
variables:
SCHEME: "MyApp"
WORKSPACE: "MyApp.xcworkspace"
# Any device listed by: xcrun simctl list devices available
DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"
# Pick the Xcode for every job without sudo
# (preinstalled Xcode; for another version, use the path from xcodes installed)
DEVELOPER_DIR: "/Applications/Xcode.app/Contents/Developer"
# Only run on our Mac runner
default:
tags:
- macos
- m4
before_script:
# The runner cleans the checkout (git clean -ffdx) before each job, so keep
# DerivedData outside it: one warm folder per project and concurrent job slot
- export DERIVED_DATA="${CI_BUILDS_DIR}/DerivedData/${CI_PROJECT_PATH_SLUG}-${CI_CONCURRENT_PROJECT_ID}"
- xcodebuild -version
# Pods/ is removed with the rest of the checkout's untracked files: reinstall it
- |
if [ -f "Podfile" ]; then
pod install
fi
# ---- BUILD ----
build:
stage: build
script:
- |
xcodebuild build \
-workspace "${WORKSPACE}" \
-scheme "${SCHEME}" \
-destination "${DESTINATION}" \
-derivedDataPath "${DERIVED_DATA}" \
CODE_SIGNING_ALLOWED=NO \
| xcbeautify
# ---- TEST ----
unit_tests:
stage: test
needs: ["build"]
script:
- |
xcodebuild test \
-workspace "${WORKSPACE}" \
-scheme "${SCHEME}" \
-destination "${DESTINATION}" \
-derivedDataPath "${DERIVED_DATA}" \
-resultBundlePath "TestResults.xcresult" \
-parallel-testing-enabled YES \
| xcbeautify --report junit --report-path build/reports
artifacts:
when: always
paths:
- TestResults.xcresult/
reports:
junit: build/reports/junit.xml
expire_in: 7 days
after_script:
- xcrun simctl shutdown all 2>/dev/null || true
# ---- DEPLOY ----
deploy_testflight:
stage: deploy
needs: ["unit_tests"]
rules:
- if: $CI_COMMIT_BRANCH == "main"
script:
- |
# Install or update Fastlane
which fastlane || brew install fastlane
# Run Fastlane beta lane
fastlane beta
environment:
name: testflight
variables:
MATCH_PASSWORD: ${MATCH_PASSWORD}
# Names read by fastlane's app_store_connect_api_key action (call it in your lane)
APP_STORE_CONNECT_API_KEY_KEY_ID: ${APP_STORE_KEY_ID}
APP_STORE_CONNECT_API_KEY_ISSUER_ID: ${APP_STORE_ISSUER_ID}
APP_STORE_CONNECT_API_KEY_KEY: ${APP_STORE_KEY_CONTENT}
Добавление переменных CI/CD в GitLab
Перейдите в Settings > CI/CD > Variables в вашем проекте GitLab и добавьте эти переменные как «Masked» и «Protected»:
MATCH_PASSWORD: пароль для шифрования Fastlane MatchAPP_STORE_KEY_ID: ID ключа App Store Connect APIAPP_STORE_ISSUER_ID: Issuer ID App Store ConnectAPP_STORE_KEY_CONTENT: содержимое файла ключа .p8
Оптимизация производительности
Конфигурация кэша GitLab
На постоянном Mac самый быстрый кэш тот, который GitLab не нужно перемещать: пайплайн выше хранит DerivedData вне рабочей копии, поэтому он остаётся «тёплым» между задачами. С shell executor собственный кэш GitLab упаковывается и распаковывается в каждой задаче, поэтому используйте его для небольших папок, например Pods/:
# DerivedData already stays on disk outside the checkout (DERIVED_DATA above).
# Use GitLab's cache for small folders, keyed on the lockfile:
build:
cache:
key:
files:
- Podfile.lock
paths:
- Pods/
policy: pull-push
# For test jobs that don't modify the cache, use pull-only:
unit_tests:
cache:
key:
files:
- Podfile.lock
paths:
- Pods/
policy: pull
Использование артефактов для передачи данных между этапами
# Useful when the build and test jobs can run on different Macs.
# build-for-testing compiles the app and its test bundles once; artifacts must
# sit inside the project folder, so this job builds there
build:
script:
- |
xcodebuild build-for-testing \
-workspace "${WORKSPACE}" \
-scheme "${SCHEME}" \
-destination "${DESTINATION}" \
-derivedDataPath build/DerivedData \
| xcbeautify
artifacts:
paths:
- build/DerivedData/Build/Products/
expire_in: 2 hours
# The test stage receives the built products and runs them without rebuilding
unit_tests:
needs: ["build"] # downloads the build job's artifacts
script:
- |
xcodebuild test-without-building \
-xctestrun build/DerivedData/Build/Products/*.xctestrun \
-destination "${DESTINATION}" \
| xcbeautify
Параллельное выполнение тестов
# On one Mac, let xcodebuild split the test classes across simulator clones.
# (GitLab's parallel: keyword only helps if each copy runs a different part of
# the suite, using CI_NODE_INDEX and CI_NODE_TOTAL; otherwise it repeats it.)
unit_tests:
stage: test
script:
- |
xcodebuild test \
-workspace "${WORKSPACE}" \
-scheme "${SCHEME}" \
-destination "${DESTINATION}" \
-derivedDataPath "${DERIVED_DATA}" \
-parallel-testing-enabled YES \
-maximum-parallel-testing-workers 4 \
| xcbeautify
Плановая очистка кэша
# On the Mac Mini, set up a weekly cleanup cron job
crontab -e
# Add these lines:
# Every Sunday at 3 AM, remove DerivedData folders not used for 7 days
# (the pipeline keeps them in ~/builds/DerivedData, one per project and slot)
0 3 * * 0 find ~/builds/DerivedData -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} + 2>/dev/null
# Checkouts in ~/builds are reused by the next job (git fetch): no need to delete them
# Clean Homebrew cache monthly
0 5 1 * * /opt/homebrew/bin/brew cleanup --prune=30 2>/dev/null
Устранение неполадок
Runner отображается как «offline» в GitLab
Runner работает как LaunchAgent, поэтому запускается при входе пользователя в систему: после перезагрузки он остаётся офлайн, пока этот пользователь не войдёт. На headless Mac включите автоматический вход для этого пользователя (Системные настройки > Пользователи и группы; недоступно, пока включён FileVault). Затем проверьте статус службы runner и логи:
# Check service status
brew services list | grep gitlab-runner
# View logs
cat /opt/homebrew/var/log/gitlab-runner.log
# Restart the service
brew services restart gitlab-runner
# Verify connectivity to GitLab
gitlab-runner verify
Ошибки отказа в доступе при сборке
Runner может нуждаться в доступе к директории разработчика Xcode:
# Ensure the runner user has Xcode access (run once, in your SSH session)
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept
# If using simulators, ensure the user can access them
xcrun simctl list devices
Кэш не восстанавливается
Убедитесь, что ключи кэша согласованы и пути существуют:
# Check cache directory permissions
ls -la ~/builds/
# The shell executor stores caches locally by default
# Verify the cache directory in config.toml:
cat ~/.gitlab-runner/config.toml
# Ensure [runners.cache] section has the right settings
# For local caching (most efficient for persistent runners):
# [runners.cache]
# Type = "" # empty = local cache
Сборка Xcode зависает или превышает тайм-аут
Это часто вызвано запросами доступа к связке ключей или проблемами с симулятором:
# Unlock the keychain before builds
security unlock-keychain -p "YOUR_PASSWORD" ~/Library/Keychains/login.keychain-db
# Kill stuck simulators
xcrun simctl shutdown all
killall -9 com.apple.CoreSimulator.CoreSimulatorService 2>/dev/null || true
# Set a build timeout in .gitlab-ci.yml
build:
timeout: 30 minutes
FAQ
Можно ли использовать Docker executor на macOS?
Как зарегистрировать runner для группы GitLab?
Что лучше использовать: shell executor или SSH executor?
Можно ли запускать runner GitLab и GitHub Actions на одном Mac?
Как обновить GitLab Runner?
# Update via Homebrew
brew upgrade gitlab-runner
# Restart the service
brew services restart gitlab-runner
# Verify the new version
gitlab-runner --version